Documentation Grafana documentation As code Observability as code Grafana CLI gcx CLI User guides Dashboards as code

Manage dashboards as code with gcx

With this workflow, you can define and manage dashboards as code, saving them to a version control system like Git. This is useful for teams that want to maintain a history of changes, collaborate on dashboard design, and ensure consistency across environments.

Before you begin

In order to use the gcx dev serve functionality, you need to enable a feature toggle in your configuration file:

ini Copy

[feature_toggles]
kubernetesDashboards = true

Refer to Configure Grafana to learn more about enabling feature toggles.

Although the local preview proxy supports service account token, Basic, and mTLS contexts, use a service account token instead of OAuth for gcx dev serve. OAuth is rejected before startup until refresh-token rotation can be persisted safely by the long-running server.

Workflow

To manage dashboards as code with gcx follow these steps:

1. Use a dashboard generation script (for example, with the Foundation SDK). You can find an example implementation in the Grafana as code hands-on lab repository.
2. Serve and preview the output of the dashboard generator locally:
   shell Copy

   gcx config use-context YOUR_CONTEXT  # for example "dev"
   gcx dev serve --script 'go run scripts/generate-dashboard.go' --watch './scripts'

3. When the output looks correct, generate dashboard manifest files:
   shell Copy

   go run scripts/generate-dashboard.go --generate-resource-manifests --output './resources'

4. Push the generated resources to your Grafana instance:
   shell Copy

   gcx config use-context YOUR_CONTEXT  # for example "dev"
   gcx resources push -p ./resources/