Acquisition complete HashiCorp officially joins the IBM family. Learn more
Consul
Consul Home

You are viewing documentation for pre-release version v1.21.0 (rc). View latest version.

UI parameters for Consul agent configuration files

This page provides reference information for UI parameters in a Consul agent configuration file.

UI parameters

  • ui_config - This object allows a number of sub-keys to be set which controls the display or features available in the UI.

    The following sub-keys are available:

    • 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 command-line flag.

    • 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 command-line flag.

    • content_path - This specifies the HTTP path that the web UI should be served from. Defaults to /ui/. Equivalent to the -ui-content-path flag.

    • 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 - 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 - 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 - 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. This simplifies deployment where the metrics backend is not exposed externally to UI users' 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.

      Security Note: Exposing your metrics backend via Consul in this way should be carefully considered in production. As Consul doesn't understand the requests, it can't limit access to only specific resources. For example this might make it possible for a malicious user on the network to query for arbitrary metrics about any server or workload in your infrastructure, or overload the metrics infrastructure with queries. See Metrics Proxy Security for more details.

      The following sub-keys are available:

      • 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.

      • path_allowlist - This specifies the paths that may be proxies to when appended to the base_url. It defaults to ["/api/v1/query_range", "/api/v1/query"] which are the endpoints required for the built-in Prometheus provider. If a custom provider is used that requires the metrics proxy, the correct allowlist must be specified to enable proxying to necessary endpoints. See Path Allowlist for more information.

      • 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 - Specifies the HTTP header name to inject into proxied requests.

        • value - Specifies the value in inject into proxied requests.

    • dashboard_url_templates - This map specifies URL templates that may be used to render links to external dashboards in various contexts in the UI. It is a map with the name of the template as a key. The value is a string URL with optional placeholders.

      Each template may contain placeholders which will be substituted for the correct values in content when rendered in the UI. The placeholders available are listed for each template.

      For more information and examples see UI Visualization

      The following named templates are defined:

      • service - This is the URL to use when linking to the dashboard for a specific service. It is shown as part of the Topology Visualization.

        The placeholders available are: