From f1fd722b81064d1b216b933f8c640f870fe13bad Mon Sep 17 00:00:00 2001 From: Paul Banks Date: Tue, 13 Oct 2020 22:11:12 +0100 Subject: [PATCH] Add ui metrics config docs (#8921) * Add ui metrics docs * Update website/pages/docs/agent/options.mdx Co-authored-by: R.B. Boyer Co-authored-by: R.B. Boyer --- website/pages/docs/agent/options.mdx | 82 +++++++++++++++++++++++++++- 1 file changed, 80 insertions(+), 2 deletions(-) diff --git a/website/pages/docs/agent/options.mdx b/website/pages/docs/agent/options.mdx index 9d68480e73..021b5fd7d3 100644 --- a/website/pages/docs/agent/options.mdx +++ b/website/pages/docs/agent/options.mdx @@ -2056,9 +2056,87 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." - [`/v1/health/service/`](/api/health#list-nodes-for-service) - [`/v1/query//execute`](/api/query#execute-prepared-query) -- `ui` - Equivalent to the [`-ui`](#_ui) command-line flag. +- `ui` - **This field is deprecated in Consul 1.9.0. See the [`ui_config.enabled`](#ui_config_enabled) field instead.** + Equivalent to the [`-ui`](#_ui) command-line flag. -- `ui_dir` - Equivalent to the [`-ui-dir`](#_ui_dir) command-line +- `ui_config` - This object allows a number of sub-keys to be set which controls + the display or features available in the UI. Configuring the UI with this + stanza was added in Consul 1.9.0. + + The following sub-keys are available: + + - `enabled` ((#ui_config_enabled)) - This enables the service of the web UI + from this agent. Boolean value, defaults to false. In `-dev` mode this + defaults to true. Replaces `ui` from before 1.9.0. Equivalent to the + [`-ui`](#_ui) command-line flag. + + - `dir` ((#ui_config_dir)) - This specifies that the web UI should be served + from an external dir rather than the build in one. This allows for + customization or development. Replaces `ui_dir` from before 1.9.0. + Equivalent to the [`-ui-dir`](#_ui_dir) command-line flag. + + - `content_path` ((#ui_config_content_path)) - This specifies the HTTP path + that the web UI should be served from. Defaults to `/ui/`. Equivalent to the + [`-ui-content-path`](#_ui_content_path) flag. + + - `metrics_provider` ((#ui_config_metrics_provider)) - Specifies a named + metrics provider implementation the UI should use to fetch service metrics. + By default metrics are disabled. Consul 1.9.0 includes a built-in provider + named `prometheus` that can be enabled explicitly here. It also requires the + `metrics_proxy` to be configured below and direct queries to a Prometheus + instance that has Envoy metrics for all services in the datacenter. + + - `metrics_provider_files` ((#ui_config_metrics_provider_files)) - An optional array + of absolute paths to javascript files on the Agent's disk which will be + served as part of the UI. These files should contain metrics provider + implementations and registration enabling UI metric queries to be customized + or implemented for an alternative time-series backend. + + ~> **Security Note:** These javascript files are included in the UI with no + further validation or sand-boxing. By configuring them here the operator is + fully trusting anyone able to write to them as well as the original authors + not to include malicious code in the UI being served. + + - `metrics_provider_options_json` ((#ui_config_metrics_provider_options_json)) - + This is an optional raw JSON object as a string which is passed to the + provider implementation's `init` method at startup to allow arbitrary + configuration to be passed through. + + - `metrics_proxy` ((#ui_config_metrics_proxy)) - This object configures an + internal agent API endpoint that will proxy GET requests to a metrics + backend to allow querying metrics data in the UI. It simplifies deployment + where the metrics backend is not exposed externally to UI user's browsers. + It may also be used to augment requests with API credentials to allow + serving graphs to UI users without them needing individual access tokens for + the metrics backend. + + The following sub-keys are available: + + - `base_url` ((#ui_config_metrics_provider_base_url)) - This is required to + enable the proxy. It should be set to the base URL that the Consul agent + should proxy requests for metrics too. For example a value of + `http://prometheus-server` would target a Prometheus instance with local + DNS name "prometheus-server" on port 80. This may include a path prefix + which will then not be necessary in provider requests to the backend and + the proxy will prevent any access to paths without that prefix on the + backend. + + - `add_headers` ((#ui_config_metrics_proxy_add_headers)) - This is an + optional list if headers to add to requests that are proxied to the + metrics backend. It may be used to inject Authorization tokens within the + agent without exposing those to UI users. + + Each item in the list is an object with the following keys: + + - `name` ((#ui_config_metrics_proxy_add_headers_name)) - Specifies the + HTTP header name to inject into proxied requests. + + - `value` ((#ui_config_metrics_proxy_add_headers_value)) - Specifies the + value in inject into proxied requests. + + +- `ui_dir` - **This field is deprecated in Consul 1.9.0. See the [`ui_config.dir`](#ui_config_dir) field instead.** + Equivalent to the [`-ui-dir`](#_ui_dir) command-line flag. This configuration key is not required as of Consul version 0.7.0 and later. Specifying this configuration key will enable the web UI. There is no need to specify both ui-dir and ui. Specifying both will result in an error.