Skip to main content
Metoro can continuously synchronize dashboard definitions from Kubernetes ConfigMaps. This approach lets you treat dashboards as code while still allowing teams to create and manage additional dashboards in the Metoro UI.
ConfigMap-managed dashboards are read-only in the UI. Changes must be applied through Kubernetes manifests.

​
How synchronization works

  • Metoro checks for configmaps with metoro.io/dashboard: "true" label on all environments and namespaces once an hour and updates the dashboards with any changes it finds.
  • You can trigger an on-demand refresh by clicking Sync Dashboards in the UI whenever you do not want to wait for the automatic run.
  • ConfigMap-managed dashboards display their source ConfigMap and the time of the last sync so you can confirm that changes were applied.
  • If a sync cannot read a ConfigMap or the dashboard definition is invalid, Metoro writes an error to your cluster logs just like it does for ConfigMap-managed alerts.
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:
  1. Include the label metoro.io/dashboard: "true". ConfigMaps without this label are ignored.
  2. Provide the dashboard definition inside data.dashboard.yaml. Each ConfigMap can contain one or more dashboards under this key.
  3. Conform to the public dashboard schema (metadata, content tree, and optional settings) described in the OpenAPI specification.
  4. Use valid resource identifiers and folder paths. IDs must be filesystem-safe, and folder paths have to live under /dashboards/.
  5. id values must be unique across all ConfigMap-managed and UI-managed dashboards. Conflicts cause sync errors.

​
Example ConfigMap with a single dashboard

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
More example dashboards can be found in the metoro-examples GitHub repository.
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 ConfigMap dashboards

  1. Apply the ConfigMap to any namespace within the Kubernetes cluster where Metoro runs.
  2. Wait at least a minute for the resource inventory to ingest the new data (or the ingestion window described above to elapse).
  3. Either wait for the next scheduled hourly sync or click Sync Dashboards in the Metoro UI to trigger reconciliation immediately.
  4. After the workflow completes, reload the Dashboards page to see the imported definitions. ConfigMap-managed dashboards display a badge with the managing ConfigMap and show a toast explaining that edits must happen in Kubernetes.
Sync Dashboards button

​
Converting existing dashboards

You can convert any UI-managed dashboard into a ConfigMap-managed one by exporting it as YAML and applying the file as a ConfigMap:
  1. Open the dashboard in Metoro and choose Edit.
  2. Click the Settings (gear) icon and select Export.
  3. Choose YAML (ConfigMap), which downloads a YAML file containing the dashboard definition that matches the ConfigMap schema.
  4. Wrap the exported YAML in a Kubernetes ConfigMap (adding the label and folder path adjustments you need) and deploy it to your cluster.
  5. 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.
When you export an existing dashboard, make sure to update the id in the metadata section if you want to keep the original dashboard intact. Using the same ID will overwrite the existing dashboard during the sync.
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.
Dashboard Settings - Gear Icon Export dashboard as YAML

​
Deleting configmap managed dashboards

To delete a ConfigMap-managed dashboard, simply delete the corresponding ConfigMap from your Kubernetes cluster and then delete the dashboard from the Metoro UI. The dashboard will no longer be recreated during the next sync since the ConfigMap is gone. If you delete only the dashboard from the Metoro UI without deleting the ConfigMap, the dashboard will be recreated during the next sync.

​
Troubleshooting

If your ConfigMap-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. Dashboard Sync Error log line Some common issues include:
  • Dashboard does not appear: Confirm the ConfigMap label and the dashboard.yaml key. Invalid or missing values are skipped during the next sync.
  • Validation errors: Dashboard IDs and folder paths must match the OpenAPI schema. Review the sync error in your cluster logs, fix the YAML, and run a new sync.
  • UI edits overridden: ConfigMap-managed dashboards intentionally disable the Save action. Update the ConfigMap 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.
⌘I