Tribe docs (#9690)

* [tribe] Init docs

* [docs] Init es client section

* [docs] Link to client api, move client library docs to core development section

* [docs] Add tribe server settings

* [tribe] Link to elasticsearch tribe docs

* [tribe] Document which nodes server configuration points towards

* [docs] Add index link to elasticsearch clients section

docs/development/core-development.asciidoc

@@ -4,9 +4,12 @@
 * <<development-basepath>>
 * <<development-dependencies>>
 * <<development-modules>>
+* <<development-elasticsearch>>
 
 include::core/development-basepath.asciidoc[]
 
 include::core/development-dependencies.asciidoc[]
 
 include::core/development-modules.asciidoc[]
+
+include::plugin/development-elasticsearch.asciidoc[]

docs/development/plugin-development.asciidoc

@@ -9,6 +9,7 @@ The Kibana plugin interfaces are in a state of constant development.  We cannot
 * <<development-plugin-resources>>
 * <<development-uiexports>>
 
+
 include::plugin/development-plugin-resources.asciidoc[]
 
 include::plugin/development-uiexports.asciidoc[]

docs/development/plugin/development-elasticsearch.asciidoc

@@ -0,0 +1,41 @@
+[[development-elasticsearch]]
+=== Communicating with Elasticsearch
+
+Kibana exposes two clients on the server and browser for communicating with elasticsearch.
+There is an 'admin' client which is used for managing Kibana's state, and a 'data' client for all
+other requests.  The clients use the https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current/index.html[elasticsearch.js library].
+
+[float]
+[[client-server]]
+=== Server clients
+
+Server clients are exposed through the elasticsearch plugin.
+[source,javascript]
+----
+  const adminCluster = server.plugins.elasticsearch.getCluster('admin);
+  const dataCluster = server.plugins.elasticsearch.getCluster('data);
+
+  //ping as the configured elasticsearch.user in kibana.yml
+  adminCluster.callWithInternalUser('ping');
+
+  //ping as the user specified in the current requests header
+  adminCluster.callWithRequest(req, 'ping');
+----
+
+[float]
+[[client-browser]]
+=== Browser clients
+
+Browser clients are exposed through AngularJS services.
+
+[source,javascript]
+----
+uiModules.get('kibana')
+.run(function (esAdmin, es) {
+  es.ping()
+  .then(() => esAdmin.ping())
+  .catch(err => {
+    console.log('error pinging servers');
+  });
+});
+----

docs/setup.asciidoc

@@ -56,6 +56,8 @@ include::setup/access.asciidoc[]
 
 include::setup/connect-to-elasticsearch.asciidoc[]
 
+include::setup/tribe.asciidoc[]
+
 include::setup/production.asciidoc[]
 
 include::setup/upgrade.asciidoc[]

docs/setup/production.asciidoc

@@ -4,7 +4,6 @@
 * <<configuring-kibana-shield, Using Kibana with X-Pack>>
 * <<enabling-ssl, Enabling SSL>>
 * <<load-balancing, Load Balancing Across Multiple Elasticsearch Nodes>>
-* <<kibana-tribe, Kibana and Tribe Nodes>>
 
 How you deploy Kibana largely depends on your use case. If you are the only user,
 you can run Kibana on your local machine and configure it to point to whatever
@@ -112,10 +111,3 @@ cluster.name: "my_cluster"
 # The Elasticsearch instance to use for all your queries.
 elasticsearch.url: "http://localhost:9200"
 --------
-
-[float]
-[[kibana-tribe]]
-=== Kibana and Tribe Nodes
-
-Kibana 5.0 does not support tribe nodes. We are working on a solution that
-addresses this limitation.

docs/setup/settings.asciidoc

@@ -69,3 +69,23 @@ unauthenticated users to access the Kibana server status API and status page.
 `console.proxyConfig`:: A list of configuration options that are based on the proxy target. Use this to set custom timeouts or SSL settings for specific hosts. This is done by defining a set of `match` criteria using wildcards/globs which will be checked against each request. The configuration from all matching rules will then be merged together to configure the proxy used for that request.
 +
 The valid match keys are `match.protocol`, `match.host`, `match.port`, and `match.path`. All of these keys default to `*`, which means they will match any value. See <<configuring-console>> for an example.
+
+`elasticsearch.tribe.url:`:: Optional URL of the Elasticsearch tribe instance to use for all your
+queries.
+`elasticsearch.tribe.username:` and `elasticsearch.tribe.password:`:: If your Elasticsearch is protected with basic authentication,
+these settings provide the username and password that the Kibana server uses to perform maintenance on the Kibana index at
+startup. Your Kibana users still need to authenticate with Elasticsearch, which is proxied through the Kibana server.
+`elasticsearch.tribe.ssl.cert:` and `elasticsearch.tribe.ssl.key:`:: Optional settings that provide the paths to the PEM-format SSL
+certificate and key files. These files validate that your Elasticsearch backend uses the same key files.
+`elasticsearch.tribe.ssl.ca:`:: Optional setting that enables you to specify a path to the PEM file for the certificate
+authority for your Elasticsearch instance.
+`elasticsearch.tribe.ssl.verify:`:: *Default: true* To disregard the validity of SSL certificates, change this setting’s value
+to `false`.
+`elasticsearch.tribe.pingTimeout:`:: *Default: the value of the `elasticsearch.tribe.requestTimeout` setting* Time in milliseconds to
+wait for Elasticsearch to respond to pings.
+`elasticsearch.requestTimeout:`:: *Default: 30000* Time in milliseconds to wait for responses from the back end or
+Elasticsearch. This value must be a positive integer.
+`elasticsearch.tribe.requestHeadersWhitelist:`:: *Default: `[ 'authorization' ]`* List of Kibana client-side headers to send to Elasticsearch.
+To send *no* client-side headers, set this value to [] (an empty list).
+`elasticsearch.tribe.customHeaders:`:: *Default: `{}`* Header names and values to send to Elasticsearch. Any custom headers
+cannot be overwritten by client-side headers, regardless of the `elasticsearch.tribe.requestHeadersWhitelist` configuration.

docs/setup/tribe.asciidoc

@@ -0,0 +1,33 @@
+[[tribe]]
+== Using Kibana with Tribe nodes
+
+Kibana can be configured to connect to a https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-tribe.html[tribe node] for data retrieval.  Because tribe nodes can't create indices, Kibana additionally
+requires a separate connection to a node to maintain state.  When configured, searches and visualizations will retrieve data using
+the tribe node and administrative actions (such as saving a dashboard) will be sent to non-tribe node.
+
+[float]
+[[tribe-configuration]]
+=== Configuring Kibana for tribe nodes
+
+Tribe nodes take all of the same configuration options used when configuring elasticsearch in `kibana.yml`.  Tribe options
+are prefixed with `elasticsearch.tribe` and at a minimum requires a url:
+[source,text]
+----
+elasticsearch.url: "<your_administration_node>"
+elasticsearch.tribe.url: "<your_tribe_node>"
+----
+
+When configured to use a tribe node, actions that modify Kibana's state will be sent to the node at `elasticsearch.url`.  Searches and visualizations
+will retrieve data from the node at `elasticsearch.tribe.url`.  It's acceptable to use a node for `elasticsearch.url` that is part of one of the clusters that
+a tribe node is pointing to.
+
+The full list of configurations can be found at <<settings>>.
+
+[float]
+[[tribe-limitations]]
+=== Limitations
+
+Due to the ambiguity of which cluster is being used, certain features are disabled in Kibana:
+
+* Console
+* Managing users and roles with the x-pack plugin