From 9a0c2dee6080b007ef74cb47eb76449a2aef8dd1 Mon Sep 17 00:00:00 2001 From: Blake Covarrubias Date: Thu, 3 Mar 2022 21:31:57 -0800 Subject: [PATCH] docs: Update Kubernetes YAML examples in UI visualization (#12419) * Update Kubernetes related YAML config examples to document supported syntax in the latest version of the Helm chart. * Fix syntax in JSON example configs. Resolves #12403 Co-authored-by: mrspanishviking --- .../observability/ui-visualization.mdx | 191 ++++++++++++------ 1 file changed, 134 insertions(+), 57 deletions(-) diff --git a/website/content/docs/connect/observability/ui-visualization.mdx b/website/content/docs/connect/observability/ui-visualization.mdx index 89bc9b74e1..75de23d4c0 100644 --- a/website/content/docs/connect/observability/ui-visualization.mdx +++ b/website/content/docs/connect/observability/ui-visualization.mdx @@ -66,7 +66,9 @@ service named `prometheus-server` so each Consul agent can reach it on A full configuration to enable Prometheus is given below. - + + + ```hcl ui_config { @@ -78,25 +80,40 @@ ui_config { } ``` + + + + +```yaml +ui: + enabled: true + metrics: + enabled: true # by default, this inherits from the value global.metrics.enabled + provider: "prometheus" + baseURL: http://prometheus-server +``` + + + + + ```json { - "ui_config": [ - { - "enabled": true, - "metrics_provider": "prometheus", - "metrics_proxy": [ - { - "base_url": "http://prometheus-server" - } - ] + "ui_config": { + "enabled": true, + "metrics_provider": "prometheus", + "metrics_proxy": { + "base_url": "http://prometheus-server" } - ] + } } ``` + + -Similarly, to configure the UI on Kubernetes, use this [reference](/docs/k8s/connect/observability/metrics). +-> **Note**: For more information on configuring the observability UI on Kubernetes, use this [reference](/docs/k8s/connect/observability/metrics). ## Configuring Dashboard URLs @@ -115,9 +132,9 @@ to the relevant information. An example with Grafana is shown below. - + - + ```hcl ui_config { @@ -130,31 +147,19 @@ ui_config { - - -```json -{ - "ui_config": [ - { - "dashboard_url_templates": [ - { - "service": "https://grafana.example.com/d/lDlaj-NGz/service-overview?orgId=1\u0026var-service={{Service.Name}}\u0026var-namespace={{Service.Namespace}}\u0026var-partition={{Service.Partition}}\u0026var-dc={{Datacenter}}" - } - ], - "enabled": true - } - ] -} -``` - - - - + ```yaml # The UI is enabled by default so this stanza is not required. ui: enabled: true + # This configuration requires version 0.40.0 or later of the Helm chart. + dashboardURLTemplates: + service: "https://grafana.example.com/d/lDlaj-NGz/service-overview?orgId=1&var-service={{Service.Name}}&var-namespace={{Service.Namespace}}&var-dc={{Datacenter}}" + +# If you are using a version of the Helm chart older than 0.40.0, you must +# configure the dashboard URL template using the `server.extraConfig` parameter +# in the Helm chart's values file. server: extraConfig: | { @@ -168,11 +173,26 @@ server: + + +```json +{ + "ui_config": { + "enabled": true, + "dashboard_url_templates": { + "service": "https://grafana.example.com/d/lDlaj-NGz/service-overview?orgId=1\u0026var-service={{Service.Name}}\u0026var-namespace={{Service.Namespace}}\u0026var-partition={{Service.Partition}}\u0026var-dc={{Datacenter}}" + } + } +} +``` + + + -~> **Note**: On Kubernetes, Consul Server configuration is set in your Helm -config via the [`server.extraConfig`](/docs/k8s/helm#v-server-extraconfig) key as JSON. -The `{{` characters in the URL must be escaped using `{{ "{{" }}` so that Helm +~> **Note**: On Kubernetes, the Consul Server configuration set in the Helm config's +[`server.extraConfig`](/docs/k8s/helm#v-server-extraconfig) key must be specified +as JSON. The `{{` characters in the URL must be escaped using `{{ "{{" }}` so that Helm doesn't try to template them. ![Consul UI Service Dashboard Link](/img/ui-dashboard-url-template.png) @@ -206,18 +226,42 @@ 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): - + + + + ```hcl -# Consul OSS service_prefix "" { policy = "read" } node_prefix "" { policy = "read" } +``` -# Consul Enterprise +```json +{ + "service_prefix": { + "": { + "policy": "read" + } + }, + "node_prefix": { + "": { + "policy": "read" + } + } +} +``` + + + + + + + +```hcl namespace_prefix "" { service_prefix "" { policy = "read" @@ -228,8 +272,30 @@ namespace_prefix "" { } ``` +```json +{ + "namespace_prefix": { + "": { + "service_prefix": { + "": { + "policy": "read" + } + }, + "node_prefix": { + "": { + "policy": "read" + } + } + } + } +} +``` + + + + 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](/docs/security/acl/auth-methods/oidc) (Consul @@ -274,7 +340,9 @@ 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. - + + + ```hcl ui_config { @@ -292,28 +360,30 @@ ui_config { } ``` + + + + ```json { - "ui_config": [ - { - "enabled": true, - "metrics_provider": "example-apm", - "metrics_proxy": [ + "ui_config": { + "enabled": true, + "metrics_provider": "example-apm", + "metrics_proxy": { + "base_url": "https://example-apm.com/api/v1/metrics", + "add_headers": [ { - "add_headers": [ - { - "name": "Authorization", - "value": "Bearer \u003ctoken\u003e" - } - ], - "base_url": "https://example-apm.com/api/v1/metrics" + "name": "Authorization", + "value": "Bearer \u003ctoken\u003e" } ] } - ] + } } ``` + + ## Custom Metrics Providers @@ -331,9 +401,9 @@ feedback on [GitHub](https://github.com/hashicorp/consul) or The template for a complete provider JavaScript file is given below. - + -```JavaScript +```javascript (function () { var provider = { /** @@ -553,7 +623,9 @@ named `example-provider`, which is defined in have been specified in the call to `consul.registerMetricsProvider` as in the code listing in the last section. - + + + ```hcl ui_config { @@ -568,6 +640,10 @@ ui_config { } ``` + + + + ```json { "ui_config": { @@ -579,6 +655,7 @@ ui_config { } ``` + More than one JavaScript file may be specified in