Documentation Grafana documentation Observability as Code Grafana CLI Manage resources with Grafana CLI

Manage resources with Grafana CLI

Migrate resources between environments

Using the config and resources options, you can migrate Grafana resources from one environment to another, for example, from a development to production environment. The config option lets you define the configuration context. Using resources with pull, push, and serve lets you pull a defined resource from one instance, and push that resource to another instance. Serve allows you to preview changes locally before pushing.

Use these steps to migrate resources between environments:

Use these steps to migrate resources between environments:

1. Make changes to dashboards and other resources using the Grafana UI in your development instance.

2. Pull those resources from the development environment to your local machine:

   bash Copy

   grafanactl config use-context YOUR_CONTEXT  # for example "dev"
   grafanactl resources pull -d ./resources/ -o yaml  # or json

3. (Optional) Preview the resources locally before pushing:

   bash Copy

   grafanactl config use-context YOUR_CONTEXT  # for example "prod"
   grafanactl resources serve -d ./resources/

4. Switch to the production instance and push the resources:

   bash Copy

   grafanactl config use-context YOUR_CONTEXT  # for example "prod"
   grafanactl resources push -d ./resources/

Back up Grafana resources

This workflow helps you back up all Grafana resources from one instance and later restore them. This is useful to replicate a configuration or perform disaster recovery.

1. Use grafanactl to pull all resources from your target environment:

   bash Copy

   grafanactl config use-context YOUR_CONTEXT  # for example "prod"
   grafanactl resources pull -d ./resources/ -o yaml  # or json

2. Save the exported resources to version control or cloud storage.

Restore Grafana resources

1. (Optional) Preview the backup locally:

   bash Copy

   grafanactl config use-context YOUR_CONTEXT  # for example "prod"
   grafanactl resources serve -d ./resources/

2. To restore the resources later or restore them on another instance, push the saved resources:

   bash Copy

   grafanactl config use-context YOUR_CONTEXT  # for example "prod"
   grafanactl resources push -d ./resources/

Manage dashboards as code

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.

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:

   bash Copy

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

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

   bash Copy

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

4. Push the generated resources to your Grafana instance:

   bash Copy

   grafanactl config use-context YOUR_CONTEXT  # for example "dev"
   grafanactl resources push -d ./resources/

Explore and modify resources from the terminal

This section describes how to use the Grafana CLI to interact with Grafana resources directly from your terminal. These commands allow you to browse, inspect, update, and delete resources without using the Grafana UI. This approach is useful for advanced users who want to manage resources more efficiently or integrate Grafana operations into automated workflows.

Find and delete dashboards using invalid data sources

Use this workflow to identify dashboards that reference incorrect or outdated data sources, and remove them if necessary.

1. Set the context to the appropriate environment:

   bash Copy

   grafanactl config use-context YOUR_CONTEXT  # for example "prod"

2. Find dashboards using specific data sources:

   bash Copy

   grafanactl resources get dashboards -ojson | jq '.items | map({ uid: .metadata.name, datasources: .spec.panels | map(.datasource.uid)  })'
   [
      {
         "uid": "important-production-dashboard",
         "datasources": [
            "mimir-prod"
         ]
      },
      {
         "uid": "test-dashboard-from-dev",
         "datasources": [
            "mimir-prod",
            "mimir-dev"
         ]
      },
      {
         "uid": "test-dashboard-from-stg",
         "datasources": [
            "mimir-prod",
            "mimir-stg",
            "mimir-dev"
         ]
      }
   ]

   This command lists dashboard UIDs along with the data source UIDs used in their panels. You can then identify the dashboards that are using invalid or unexpected data sources.

3. Delete the identified dashboards directly:

   bash Copy

   grafanactl resources delete dashboards/test-dashboard-from-stg,test-dashboard-from-dev
   ✔ 2 resources deleted, 0 errors

Find and deprecate dashboards using the old API version

Use this workflow to locate dashboards using a deprecated API version and mark them accordingly.

1. Set the context to the appropriate environment:

   bash Copy

   grafanactl config use-context YOUR_CONTEXT  # for example "prod"

2. List all available resources types and versions:

   bash Copy

   grafanactl resources list

   This command returns a list of resources, including their versions, types, and quantities:

   bash Copy

   GROUP                               VERSION   KIND
   folder.grafana.app                  v1        folder
   dashboard.grafana.app               v1        dashboard
   dashboard.grafana.app               v1        librarypanel
   dashboard.grafana.app               v2        dashboard
   dashboard.grafana.app               v2        librarypanel
   playlist.grafana.app                v1        playlist

3. Find dashboards that are still using an old API version:

   bash Copy

   grafanactl resources get dashboards.v1.dashboard.grafana.app

   This command returns a table displaying the resource type, resource name, and associated namespace:

   bash Copy

   KIND         NAME                                   NAMESPACE
   dashboards   really-old-dashboard                   default

4. Edit each of these dashboards to add a deprecated tag:

   bash Copy

   grafanactl resources edit dashboards.v1.dashboard.grafana.app/really-old-dashboard -p '{"spec":{"tags":["deprecated"]}}'