From 840df9a23157aa4b4127a6754395d35c07ed1062 Mon Sep 17 00:00:00 2001 From: Jonathan Budzenski Date: Thu, 12 Jan 2017 16:34:01 -0600 Subject: [PATCH] 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 | 3 ++ docs/development/plugin-development.asciidoc | 1 + .../plugin/development-elasticsearch.asciidoc | 41 +++++++++++++++++++ docs/setup.asciidoc | 2 + docs/setup/production.asciidoc | 8 ---- docs/setup/settings.asciidoc | 20 +++++++++ docs/setup/tribe.asciidoc | 33 +++++++++++++++ 7 files changed, 100 insertions(+), 8 deletions(-) create mode 100644 docs/development/plugin/development-elasticsearch.asciidoc create mode 100644 docs/setup/tribe.asciidoc diff --git a/docs/development/core-development.asciidoc b/docs/development/core-development.asciidoc index 5016a428606a38..2b7709f0031170 100644 --- a/docs/development/core-development.asciidoc +++ b/docs/development/core-development.asciidoc @@ -4,9 +4,12 @@ * <> * <> * <> +* <> include::core/development-basepath.asciidoc[] include::core/development-dependencies.asciidoc[] include::core/development-modules.asciidoc[] + +include::plugin/development-elasticsearch.asciidoc[] diff --git a/docs/development/plugin-development.asciidoc b/docs/development/plugin-development.asciidoc index e2d59f5b0c49d5..d86479685fafee 100644 --- a/docs/development/plugin-development.asciidoc +++ b/docs/development/plugin-development.asciidoc @@ -9,6 +9,7 @@ The Kibana plugin interfaces are in a state of constant development. We cannot * <> * <> + include::plugin/development-plugin-resources.asciidoc[] include::plugin/development-uiexports.asciidoc[] diff --git a/docs/development/plugin/development-elasticsearch.asciidoc b/docs/development/plugin/development-elasticsearch.asciidoc new file mode 100644 index 00000000000000..c4faefe2498608 --- /dev/null +++ b/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'); + }); +}); +---- diff --git a/docs/setup.asciidoc b/docs/setup.asciidoc index 3ffc48f9638297..2ed96266e9f383 100644 --- a/docs/setup.asciidoc +++ b/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[] diff --git a/docs/setup/production.asciidoc b/docs/setup/production.asciidoc index 7fa3ab08a49139..0718705068673c 100644 --- a/docs/setup/production.asciidoc +++ b/docs/setup/production.asciidoc @@ -4,7 +4,6 @@ * <> * <> * <> -* <> 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. diff --git a/docs/setup/settings.asciidoc b/docs/setup/settings.asciidoc index bf31ba692dec95..178a64defa33f3 100644 --- a/docs/setup/settings.asciidoc +++ b/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 <> 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. diff --git a/docs/setup/tribe.asciidoc b/docs/setup/tribe.asciidoc new file mode 100644 index 00000000000000..024489b8eba66d --- /dev/null +++ b/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: "" +elasticsearch.tribe.url: "" +---- + +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 <>. + +[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