Manage Dashboards with Kubernetes

Metoro can continuously synchronize dashboard definitions from Kubernetes ConfigMaps or MetoroDashboard custom resources. This approach lets you treat dashboards as code while still allowing teams to create and manage additional dashboards in the Metoro UI.

Kubernetes-managed dashboards are read-only in the UI. Changes must be applied through Kubernetes manifests.

How synchronization works

Metoro automatically detects MetoroDashboard creates, spec updates, and deletions. Most changes appear in about 30 seconds; allow up to one minute for the exporter and sync workflow to process a change.
Creates and updates of ConfigMaps with the metoro.io/dashboard: "true" label sync on the same fast path and normally appear in about 30 seconds. A full reconcile across all environments and namespaces additionally runs once an hour as a backstop.
You can trigger an on-demand full reconciliation by clicking Sync Dashboards in the UI. This is useful when a change has not appeared after one minute.
Kubernetes-managed dashboards display their source resource and the time of the last sync so you can confirm that changes were applied.
If a sync cannot read a Kubernetes source or the dashboard definition is invalid, Metoro writes an error to your cluster logs.

Allow at least one minute after applying or updating a ConfigMap before triggering a manual sync so that Metoro can discover the new resource.

id’s provided in the dashboard definition will be prefixed with your organization UUID. For example, if you define a dashboard with id: my-dashboard in a ConfigMap, and your organization UUID is org-1234, the resulting dashboard ID in Metoro will be org-1234-my-dashboard.

ConfigMap requirements

Metoro looks for specific labels and data keys to determine whether a ConfigMap should be treated as a dashboard source. Make sure each ConfigMap satisfies the following:

Include the label metoro.io/dashboard: "true". ConfigMaps without this label are ignored.
Provide the dashboard definition inside data.dashboard.yaml. Each ConfigMap can contain one or more dashboards under this key.
Conform to the public dashboard schema (metadata, content tree, and optional settings) described in the OpenAPI specification: Dashboard schema
Use valid resource identifiers and folder paths. IDs must be filesystem-safe, and folder paths have to live under /dashboards/.
id values must be unique across all ConfigMap-managed and UI-managed dashboards. Conflicts cause sync errors.

MetoroDashboard CRD requirements

Use a MetoroDashboard custom resource when you want Kubernetes API validation and one Kubernetes object per dashboard:

Use apiVersion: observability.metoro.io/v1alpha1 and kind: MetoroDashboard.
Provide a spec.content root group. spec.title is optional and defaults to metadata.name.
Do not set a dashboard ID or folder path. Metoro derives the ID as kubernetes-managed.<cluster>.<namespace>.<name> and places the dashboard under /dashboards/kubernetes-managed/<cluster>/<namespace>/.
The root group can contain group widgets, but group widgets cannot contain other group widgets.
Optionally set spec.tags to organize and filter the dashboard in Metoro.

You don’t have to write these manifests by hand: any existing dashboard can be exported as a ready-to-apply manifest from the dashboard’s settings via Export → “YAML (MetoroDashboard CRD)”. Exported manifests omit metadata.namespace, so the resource lands in whichever namespace you apply it to, and the dashboard ID and folder are derived when Metoro syncs the resource.

Example MetoroDashboard

apiVersion: observability.metoro.io/v1alpha1
kind: MetoroDashboard
metadata:
  name: payments-overview
  namespace: payments
spec:
  title: Payments Overview
  tags:
    - payments
    - production
  settings:
    defaultTimeRange: "1h"
    hideGlobalEnvironmentSelector: false
    layoutVersion: 2
  content:
    title: Payments Overview
    widgets:
      - type: markdown
        position:
          type: absolute
          absolute:
            x: 0
            y: 0
            w: 8
            h: 2
        markdown:
          content: |
            ### Payments dashboard
            This dashboard is managed from a MetoroDashboard custom resource.

Example ConfigMap with a single dashboard

This example ConfigMap defines a simple stat table dashboard showing CPU usage per environment. More example dashboards can be found in the metoro-examples GitHub repository.

apiVersion: v1
kind: ConfigMap
metadata:
  name: dashboard-stat
  labels:
    metoro.io/dashboard: "true"
data:
  dashboard.yaml: |
    content:
      title: Stat Table
      widgets:
      - position:
          absolute:
            h: 2
            w: 7
            x: 0
            y: 0
          type: absolute
        stat:
          displaySettings:
            columnSettings:
            - column: attributes.environment
              hiddenByDefault: false
              regexExtractor: '(.*) '
              title: Environment
            - column: attributes.job
              hiddenByDefault: true
            - column: value
              title: value
            globalSettings:
              filterableColumn: attributes.environment
              fontSize: auto
              valuePrecision: 2
            valueSettings:
            - colorSettings:
                color: '#d92e48'
                type: text
              formatSpecifier: $value cores used
              matchingOperators:
              - operator: greaterThan
                threshold: 5
            - colorSettings:
                color: '#2DD881'
                type: text
              formatSpecifier: $value cores used
              matchingOperators:
              - operator: lessThan
                threshold: 5
          expression:
            metoroQLQuery:
              bucketSize: 60
              query: sum(rate(node_resources_cpu_usage_seconds_total)) by (environment,job)
            reduceAggregation: max
          title: Cores per environment
        type: stat
    metadata:
      id: configmap-dashboards-stat-test1
      title: Stat Table
      folderPath: /dashboards/configmap-examples/
      tags:
        - infrastructure
        - capacity

Both ConfigMap metadata.tags and MetoroDashboard spec.tags use the same tag normalization and limits. Tags are included in exports and survive sync and re-import. Omit the field to preserve the current set during an update, or set it to [] to clear all tags.

You can define multiple dashboards in a single ConfigMap by listing them under dashboards:. Each entry is validated on its own, so one invalid dashboard does not prevent the others from syncing. However, as the dashboard definitions grow larger, consider splitting them into separate ConfigMaps for easier management.

Deploying Kubernetes dashboards

Apply the ConfigMap or MetoroDashboard resource to any namespace within the Kubernetes cluster where Metoro runs.
Wait up to one minute for the automatic fast sync (MetoroDashboard and ConfigMap changes alike).
If the change still has not appeared, click Sync Dashboards in the Metoro UI to force a full reconciliation.
After the workflow completes, reload the Dashboards page to see the imported definitions. Kubernetes-managed dashboards display a badge with the managing resource and show a toast explaining that edits must happen in Kubernetes.

Converting existing dashboards

You can convert any UI-managed dashboard into a Kubernetes-managed one by exporting it as YAML and applying the file as a ConfigMap:

Open the dashboard in Metoro and choose Edit.
Click the Settings (gear) icon and select Export.
Choose YAML (ConfigMap), which downloads a YAML file containing the dashboard definition that matches the ConfigMap schema.
Wrap the exported YAML in a Kubernetes ConfigMap (adding the label and folder path adjustments you need) and deploy it to your cluster.
Trigger a sync or wait for the hourly workflow. The resulting dashboard becomes read-only in the UI, and future edits should flow through the ConfigMap.

Currently, folderPath is not exported. You must manually add it to the ConfigMap under metadata to place the dashboard in a specific folder. If omitted, the dashboard will be placed in the default folder.

Export Dashboard dialog with YAML ConfigMap format selected for Kubernetes deployment

Deleting Kubernetes-managed dashboards

To delete a ConfigMap-managed dashboard, delete the corresponding ConfigMap from your Kubernetes cluster and then delete the dashboard from the Metoro UI. To delete a MetoroDashboard-managed dashboard, delete the MetoroDashboard resource. Metoro normally removes the dashboard within one minute after seeing the Kubernetes delete event. If you delete only the dashboard from the Metoro UI without deleting the Kubernetes source, the dashboard will be recreated during the next sync.

Troubleshooting

If your Kubernetes-managed dashboards do not appear or behave as expected, you can check from your cluster logs for sync errors Make sure to filter the logs by service.name: configmap-to-dashboard to see only relevant entries.

Logs view showing dashboard sync error with invalid folder path message

Some common issues include:

Dashboard does not appear: For ConfigMaps, confirm the label and the dashboard.yaml key. For CRDs, confirm the MetoroDashboard resource exists in the cluster. Invalid or missing values are skipped during the next sync.
Validation errors: Review the sync error in your cluster logs, fix the YAML, and run a new sync. ConfigMap dashboard IDs and folder paths must match the OpenAPI schema. MetoroDashboard resources derive the ID and folder path from the Kubernetes object.
UI edits rejected: Kubernetes-managed dashboards intentionally disable the Save action. Update the Kubernetes resource instead, then sync again to propagate the change.

We are here to help!
If you continue to experience issues, please reach out to Metoro support for assistance.

Get Started

AI SRE

Concepts

Ingestion Settings

Traces

Logs

Metrics

Profiling

Kubernetes Resources

Dashboards

Infrastructure

Advisor

Alerts & Monitoring

Integrations

Uptime Monitoring

User Management

On-Premises

Administration

How synchronization works

ConfigMap requirements

MetoroDashboard CRD requirements

Example MetoroDashboard

Example ConfigMap with a single dashboard

Deploying Kubernetes dashboards

Converting existing dashboards

Deleting Kubernetes-managed dashboards

Troubleshooting

​How synchronization works

​ConfigMap requirements

​MetoroDashboard CRD requirements

​Example MetoroDashboard

​Example ConfigMap with a single dashboard

​Deploying Kubernetes dashboards

​Converting existing dashboards

​Deleting Kubernetes-managed dashboards

​Troubleshooting

​Related Links

How synchronization works

ConfigMap requirements

MetoroDashboard CRD requirements

Example MetoroDashboard

Example ConfigMap with a single dashboard

Deploying Kubernetes dashboards

Converting existing dashboards

Deleting Kubernetes-managed dashboards

Troubleshooting

Related Links