UI Visualization

    Since Consul 1.9.0, Consul’s built in UI includes a topology visualization to show a service’s immediate connectivity at a glance. It is not intended as a replacement for dedicated monitoring solutions, but rather as a quick overview of the state of a service and its connections within the Service Mesh.

    The topology visualization requires services to be using Consul Connect via .

    The visualization may optionally be configured to include a link to an external per-service dashboard. This is designed to provide convenient deep links to your existing monitoring or Application Performance Monitoring (APM) solution for each service. More information can be found in Configuring Dashboard URLs.

    It is possible to configure the UI to fetch basic metrics from your metrics provider storage to augment the visualization as displayed below.

    Consul has built-in support for overlaying metrics from a backend. Alternative metrics providers may be supported using a new and experimental JavaScript API. See Custom Metrics Providers.

    If running Consul in Kubernetes, the Helm chart can automatically configure Consul’s UI to display topology visualizations. See our for more information.

    To configure Consul’s UI to fetch metrics there are two required configuration settings. These need to be set on each Consul Agent that is responsible for serving the UI. If there are multiple clients with the UI enabled in a datacenter for redundancy these configurations must be added to all of them.

    We assume that the UI is already enabled by setting ui_config.enabled to in the agent’s configuration file.

    To use the built-in Prometheus provider must be set to prometheus.

    The UI must query the metrics provider through a proxy endpoint. This simplifies deployment where Prometheus is not exposed externally to UI user’s browsers.

    To set this up, provide the URL that the Consul agent should use to reach the Prometheus server in ui_config.metrics_proxy.base_url. For example in Kubernetes, the Prometheus helm chart by default installs a service named prometheus-server so each Consul agent can reach it on http://prometheus-server (using Kubernetes’ DNS resolution).

    A full configuration to enable Prometheus is given below.

    Similarly, to configure the UI on Kubernetes, use this .

    Since Consul’s visualization is intended as an overview of your mesh and not a comprehensive monitoring tool, you can configure a service dashboard URL template which allows users to click directly through to the relevant service-specific dashboard in an external tool like Grafana or a hosted provider.

    To configure this, you must provide a URL template in the for all agents that have the UI enabled. The template is essentially the URL to the external dashboard, but can have placeholder values which will be replaced with the service name, namespace and datacenter where appropriate to allow deep-linking to the relevant information.

    UI Visualization - 图2

    1. ui_config {
    2.   enabled = true
    3.   dashboard_url_templates {
    4.       service-overview?orgId=1&var-service={{Service.Name}}&
    5.       var-namespace={{Service.Namespace}}&var-dc={{Datacenter}}"
    6.   }
    7. }

    Note: the URL is wrapped over multiple lines to make it easier to read without horizontal scrolling in the example above however this needs to be a normal single-line string value in an HCL configuration file.

    Consul UI Service Dashboard Link

    In many cases the metrics backend may be inaccessible to UI user’s browsers or may be on a different domain and so subject to CORS restrictions. To make it simpler to serve the metrics to the UI in these cases, the Consul agent can proxy requests for metrics from the UI to the backend.

    This is intended to simplify setup in test and demo environments. Careful consideration should be given towards using this in production.

    The simplest configuration is described in Configuring the UI for metrics.

    Metrics Proxy Security

    Security Note: Exposing a backend metrics service to potentially un-authenticated network traffic via the proxy should be carefully considered in production.

    The metrics proxy endpoint is internal and intended only for UI use. However by enabling it anyone with network access to the agent’s API port may use it to access metrics from the backend.

    If ACLs are not enabled, full access to metrics will be exposed to un-authenticated workloads on the network.

    With ACLs enabled, the proxy endpoint requires a valid token with read access to all nodes and services (across all namespaces in Enterprise):

    It’s typical for most authenticated users to have this level of access in Consul as it’s required for viewing the catalog or discovering services. If you use a Single Sign-On integration (Consul Enterprise) users of the UI can be automatically issued an ACL token with the privileges above to be allowed access to the metrics through the proxy.

    Even with ACLs enabled, the proxy endpoint doesn’t deeply understand the query language of the backend so there is no way it can enforce least-privilege access to only specific service-related metrics.

    If you are not comfortable with all users of Consul having full access to the metrics backend, you should not use the proxy and find an alternative like using a custom provider that can query the metrics backend directly.

    Path Allowlist

    To limit exposure of the metrics backend, paths must be explicitly added to an allowlist to avoid exposing unintended parts of the API. For example with Prometheus, both the /api/v1/query_range and /api/v1/query endpoints are needed to load time-series and individual stats. If the proxy had the base_url set to http://prometheus-server then the proxy would also expose read access to several other endpoints such as /api/v1/status/config which includes all Prometheus configuration which might include sensitive information.

    If you use the built-in provider the proxy is limited to the essential endpoints. The default value for metrics_proxy.path_allowlist is ["/api/v1/query_range", "/api/v1/query"] as required by the built-in prometheus provider .

    Adding Headers

    It is also possible to configure the proxy to add one or more headers to requests as they pass through. This is useful when the metrics backend requires authentication. For example if your metrics are shipped to a hosted provider, you could provision an API token specifically for the Consul UI and configure the proxy to add it as in the example below. This keeps the API token only visible to Consul operators in the configuration file while UI users can query the metrics they need without separately obtaining a token for that provider or having a token exposed to them that they might be able to use elsewhere.

    1. ui_config {
    2.   enabled = true
    3.   metrics_provider = "example-apm"
    4.   metrics_proxy {
    5.     base_url = "https://example-apm.com/api/v1/metrics"
    6.     add_headers = [
    7.       {
    8.         name = "Authorization"
    9.         value = "Bearer <token>"
    10.       }
    11.   }
    12. }

    Consul 1.9.0 includes a built-in provider for fetching metrics from . To enable the UI visualization feature to work with other existing metrics stores and hosted services, we created a “metrics provider” interface in JavaScript. A custom provider may be written and the JavaScript file served by the Consul agent.

    Note: this interface is experimental and may change in breaking ways or be removed entirely as we discover the needs of the community. Please provide feedback on GitHub or on how you’d like to use this.

    The template for a complete provider JavaScript file is given below.

    Additionally, the built in Prometheus provider code can be used as a reference.

    In the example below, we configure the Consul agent to use a metrics provider named , which is defined in /usr/local/bin/example-metrics-provider.js. The name example-provider must have been specified in the call to consul.registerMetricsProvider as in the code listing in the last section.

    1. ui_config {
    2.   enabled = true
    3.   metrics_provider = "example-provider"
    4.   metrics_provider_files = ["/usr/local/bin/example-metrics-provider.js"]
    5.   metrics_provider_options_json = <<-EOT
    6.     {
    7.       "foo": "bar"
    8.     }
    9.   EOT
    10. }

    More than one JavaScript file may be specified in and all we be served allowing flexibility if needed to include dependencies. Only one metrics provider can be configured and used at one time.

    The metrics_provider_options_json field is an optional literal JSON object which is passed to the provider’s init method at startup time. This allows configuring arbitrary parameters for the provider in config rather than hard coding them into the provider itself to make providers more reusable.

    The provider may fetch metrics directly from another source although in this case the agent will probably need to serve the correct CORS headers to prevent browsers from blocking these requests. These may be configured with .

    Alternatively, the provider may choose to use the built-in metrics proxy to avoid cross domain issues or to inject additional authorization headers without requiring each UI user to be separately authenticated to the metrics backend.

    A function that behaves like the browser’s is provided to the metrics provider JavaScript during init as options.fetch. This is a thin wrapper that prefixes any url with the url of Consul’s metrics proxy endpoint and adds your current Consul ACL token to the request headers. Otherwise it functions like the browser’s native fetch and will forward your request on to the metrics backend. The response will be returned without any modification to be interpreted by the provider and converted into the format as described in the interface above.

    Provider authors should make it clear to users which paths are required so they can correctly configure the path allowlist in the metrics proxy to avoid exposing more than needed of the metrics backend.

    Since the JavaScript file(s) are included in Consul’s UI verbatim, the code in them must be treated as fully trusted by the operator. Typically they will have authored this or will need to carefully vet providers written by third parties.

    This is equivalent to using the existing flag to serve an alternative version of the UI - in either model the operator takes full responsibility for the provenance of the code being served since it has the power to intercept ACL tokens, access cookies and local storage for the Consul UI domain and possibly more.

    Currently there are some limitations to this feature.

    • No cross-datacenter support The initial metrics provider integration is with Prometheus which is popular and easy to setup within one Kubernetes cluster. However, when using the Consul UI in a multi-datacenter deployment, the UI allows users to select any datacenter to view.

    • Built-in provider requires metrics proxy Initially the built-in prometheus provider only support querying Prometheus via the . Later it may be possible to configure it for direct access to an expose Prometheus.