[release-12.3.0] Restructure As code and developer resources (#113969)

Co-authored-by: Roberto Jiménez Sánchez <roberto.jimenez@grafana.com> Co-authored-by: Anna Urbiztondo <anna.urbiztondo@grafana.com>
2025-11-16 19:06:56 +00:00
parent 0898ec6045
commit 047da1442e
96 changed files with 8186 additions and 230 deletions
@@ -0,0 +1,50 @@
+---
+description: Overview of Grafana CLI, a command line tool for managing Grafana resources as code.
+keywords:
+  - observability
+  - configuration
+  - as code
+  - as-code
+  - dashboards
+  - git integration
+  - git sync
+  - github
+labels:
+  products:
+    - cloud
+    - enterprise
+    - oss
+cards:
+  items:
+    - description: Learn how to install Grafana CLI
+      height: 24
+      href: ./install-grafana-cli/
+      title: Install Grafana CLI
+    - description: Set up Grafana CLI
+      height: 24
+      href: ./set-up-grafana-cli/
+      title: Set up your Grafana CLI
+    - description: Learn how to manage resources with Grafana CLI
+      height: 24
+      href: ./grafanacli-workflows
+      title: Manage resources with Grafana CLI
+  title_class: pt-0 lh-1
+hero:
+  description: Grafana CLI (`grafanactl`) is a command-line tool designed to simplify interaction with Grafana instances. It enables users to authenticate, manage multiple environments, and perform administrative tasks through Grafana’s REST API, all from the terminal. Whether you're automating workflows in CI/CD pipelines or switching between staging and production environments, Grafana CLI provides a flexible and scriptable way to manage your Grafana setup efficiently.
+  height: 110
+  level: 1
+  title: Grafana CLI
+  width: 110
+title: Introduction to Grafana CLI
+menuTitle: Grafana CLI
+weight: 130
+canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/grafana-cli/
+aliases:
+  - ../../observability-as-code/grafana-cli/ # /docs/grafana/next/observability-as-code/grafana-cli/
+---
+
+{{< docs/hero-simple key="hero" >}}
+
+## Explore
+
+{{< card-grid key="cards" type="simple" >}}
@@ -0,0 +1,224 @@
+---
+description: Learn more about the supported workflows and use cases for Grafana CLI
+keywords:
+  - workflows
+  - Grafana CLI
+  - CLI
+  - command line
+  - grafanactl
+labels:
+  products:
+    - cloud
+    - enterprise
+    - oss
+title: Manage resources with Grafana CLI
+weight: 300
+canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/grafana-cli/grafanacli-workflows/
+aliases:
+  - ../../../observability-as-code/grafana-cli/grafanacli-workflows/ # /docs/grafana/next/observability-as-code/grafana-cli/grafanacli-workflows/
+---
+
+# Manage resources with Grafana CLI
+
+{{< admonition type="note" >}}
+`grafanactl` is under active development. Command-line flags and subcommands described here may change. This document outlines the target workflows the tool is expected to support. You can find a full list of supported commands [in this page](https://grafana.github.io/grafanactl/reference/cli/grafanactl/).
+{{< /admonition >}}
+
+## 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:
+
+{{< admonition type="note" >}}
+Currently, the `serve` command only works with dashboards.
+{{< /admonition >}}
+
+Use these steps to migrate resources between environments:
+
+{{< admonition type="note" >}}
+Resources are pulled and pushed from the `./resources` directory by default.
+This can be configured with the `-p, --path` flags to specify custom paths on disk.
+{{< /admonition >}}
+
+1. Make changes to dashboards and other resources using the Grafana UI in your **development instance**.
+1. Pull those resources from the development environment to your local machine:
+
+   ```bash
+   grafanactl config use-context YOUR_CONTEXT  # for example "dev"
+   grafanactl resources pull --path ./resources/ -o yaml # or json
+   ```
+
+1. (Optional) Preview the resources locally before pushing:
+
+   ```bash
+   grafanactl config use-context YOUR_CONTEXT  # for example "prod"
+   grafanactl resources serve ./resources/
+   ```
+
+1. Switch to the **production instance** and push the resources:
+
+   ```bash
+   grafanactl config use-context YOUR_CONTEXT  # for example "prod"
+   grafanactl resources push -p ./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
+   grafanactl config use-context YOUR_CONTEXT  # for example "prod"
+   grafanactl resources pull --path ./resources/ -o yaml # or json
+   ```
+
+1. Save the exported resources to version control or cloud storage.
+
+## Restore Grafana resources
+
+1. (Optional) Preview the backup locally:
+
+   ```bash
+   grafanactl config use-context YOUR_CONTEXT  # for example "prod"
+   grafanactl resources serve ./resources/
+   ```
+
+1. To restore the resources later or restore them on another instance, push the saved resources:
+
+   ```bash
+   grafanactl config use-context YOUR_CONTEXT  # for example "prod"
+   grafanactl resources push -p ./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](https://github.com/grafana/grafana-foundation-sdk)). You can find an example implementation in the Grafana as code [hands-on lab repository](https://github.com/grafana/dashboards-as-code-workshop/tree/main/part-one-golang-starter).
+
+1. Serve and preview the output of the dashboard generator locally:
+
+   ```bash
+   grafanactl config use-context YOUR_CONTEXT  # for example "dev"
+   grafanactl resources serve --script 'go run scripts/generate-dashboard.go' --watch './scripts'
+   ```
+
+1. When the output looks correct, generate dashboard manifest files:
+
+   ```bash
+   go run scripts/generate-dashboard.go --generate-resource-manifests --output './resources'
+   ```
+
+1. Push the generated resources to your Grafana instance:
+
+   ```bash
+   grafanactl config use-context YOUR_CONTEXT  # for example "dev"
+   grafanactl resources push -p ./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
+   grafanactl config use-context YOUR_CONTEXT  # for example "prod"
+   ```
+
+1. Find dashboards using specific data sources:
+
+   ```bash
+   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.
+
+1. Delete the identified dashboards directly:
+
+   ```bash
+   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
+   grafanactl config use-context YOUR_CONTEXT  # for example "prod"
+   ```
+
+1. List all available resources types and versions:
+
+   ```bash
+   grafanactl resources list
+   ```
+
+   This command returns a list of resources, including their versions, types, and quantities:
+
+   ```bash
+   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
+   ```
+
+1. Find dashboards that are still using a deprecated API version:
+
+   ```bash
+   grafanactl resources get dashboards.v1.dashboard.grafana.app
+   ```
+
+   This command returns a table displaying the resource type, resource name, and associated namespace:
+
+   ```bash
+   KIND         NAME                                   NAMESPACE
+   dashboards   really-old-dashboard                   default
+   ```
+
+1. Edit each of these dashboards to add a `deprecated` tag:
+
+   ```bash
+   grafanactl resources edit dashboards.v1.dashboard.grafana.app/really-old-dashboard -p '{"spec":{"tags":["deprecated"]}}'
+   ```
+
+{{< admonition type="tip" >}}
+You can get help by using the `grafanactl --help` command.
+{{< /admonition >}}
@@ -0,0 +1,49 @@
+---
+description: Installation guide for Grafana CLI, a command line tool for managing Grafana Observability as Code
+keywords:
+  - configuration
+  - Grafana CLI
+  - CLI
+  - command line
+  - grafanactl
+  - installation
+labels:
+  products:
+    - cloud
+    - enterprise
+    - oss
+title: Install Grafana CLI
+weight: 100
+canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/grafana-cli/install-grafana-cli/
+aliases:
+  - ../../../observability-as-code/grafana-cli/install-grafana-cli/ # /docs/grafana/next/observability-as-code/grafana-cli/install-grafana-cli/
+---
+
+# Install Grafana CLI
+
+You can install the project using one of the following supported methods:
+
+## 1. Download a pre-built binary
+
+Download the latest binary for your platform from the [Releases page](https://github.com/grafana/grafanactl/releases).
+
+Prebuilt binaries are available for a variety of operating systems and architectures. Visit the latest release page, and scroll down to the Assets section.
+
+To install the binary, follow the instructions below:
+
+1. Download the archive for the desired operating system and architecture
+1. Extract the archive
+1. Move the executable to the desired directory
+1. Ensure this directory is included in the PATH environment variable
+1. Verify that you have execute permission on the file
+
+## 2. Build from source
+
+To build `grafanactl` from source you must:
+
+- Have `git` installed
+- Have `go` v1.24 (or greater) installed
+
+```bash
+go install github.com/grafana/grafanactl/cmd/grafanactl@latest
+```
@@ -0,0 +1,122 @@
+---
+description: Configuration guide for Grafana CLI, a command line tool for managing Grafana resources as code.
+keywords:
+  - configuration
+  - Grafana CLI
+  - CLI
+  - command line
+  - grafanactl
+labels:
+  products:
+    - cloud
+    - enterprise
+    - oss
+title: Set up Grafana CLI
+weight: 200
+canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/grafana-cli/set-up-grafana-cli/
+aliases:
+  - ../../../observability-as-code/grafana-cli/set-up-grafana-cli/ # /docs/grafana/next/observability-as-code/grafana-cli/set-up-grafana-cli/
+---
+
+# Set up Grafana CLI
+
+You can configure Grafana CLI in two ways: using environment variables or through a configuration file.
+
+- **Environment variables** are ideal for CI environments and support a single context. A full list of supported environment variables is available in the [reference documentation](https://github.com/grafana/grafanactl/blob/main/docs/reference/environment-variables/index.md#environment-variables-reference).
+- **Configuration files** can manage multiple contexts, making it easier to switch between different Grafana instances.
+
+{{< admonition type="note" >}}
+Configuration items may change depending on your set-up. For example, use `org-id` for Grafana on-prem, but use `stack-id` for Grafana Cloud.
+{{< /admonition >}}
+
+## Configure Grafana CLI with environment variables
+
+Grafana CLI communicates with Grafana via its REST API, which requires authentication credentials.
+
+At a minimum, set the URL of your Grafana instance and the organization ID:
+
+```bash
+GRAFANA_SERVER='http://localhost:3000' GRAFANA_ORG_ID='1' grafanactl config check
+```
+
+Depending on your authentication method, you may also need to set:
+
+- A [token](https://github.com/grafana/grafanactl/blob/main/docs/reference/environment-variables/index.md#grafana_token) for a [Grafana service account](https://grafana.com/docs/grafana/latest/administration/service-accounts/) (recommended)
+- A [username](https://github.com/grafana/grafanactl/blob/main/docs/reference/environment-variables/index.md#grafana_user) and [password](https://github.com/grafana/grafanactl/blob/main/docs/reference/environment-variables/index.md#grafana_password) for basic authentication
+
+To persist your configuration, consider [creating a context](#use-configuration-contexts).
+
+### Use configuration contexts
+
+Contexts allow you to easily switch between multiple Grafana instances.
+
+By default, the CLI uses a context named `default`. To configure it use:
+
+```bash
+grafanactl config set contexts.default.grafana.server http://localhost:3000
+grafanactl config set contexts.default.grafana.org-id 1
+
+# Authenticate with a service account token
+grafanactl config set contexts.default.grafana.token service-account-token
+
+# Or use basic authentication
+grafanactl config set contexts.default.grafana.user admin
+grafanactl config set contexts.default.grafana.password admin
+```
+
+You can define additional contexts in the same way:
+
+```bash
+grafanactl config set contexts.staging.grafana.server https://staging.grafana.example
+grafanactl config set contexts.staging.grafana.org-id 1
+```
+
+{{< admonition type="note" >}}
+In these examples, `default` and `staging` are the names of the contexts.
+{{< /admonition >}}
+
+## Configure Grafana CLI with configuration files
+
+Grafana CLI stores its configuration in a YAML file. The CLI determines the configuration file location in the following order:
+
+1. If the `--config` flag is provided, the specified file is used.
+2. If `$XDG_CONFIG_HOME` is set:
+   `$XDG_CONFIG_HOME/grafanactl/config.yaml`
+3. If `$HOME` is set:
+   `$HOME/.config/grafanactl/config.yaml`
+4. If `$XDG_CONFIG_DIRS` is set:
+   `$XDG_CONFIG_DIRS/grafanactl/config.yaml`
+
+{{< admonition type="note" >}}
+Use `grafanactl config check` to display the configuration file currently in use.
+{{< /admonition >}}
+
+## Useful commands
+
+Check the current configuration:
+
+```bash
+grafanactl config check
+```
+
+{{< admonition type="note" >}}
+This command is useful to troubleshoot your configuration.
+{{< /admonition >}}
+
+List all available contexts:
+
+```bash
+grafanactl config list-contexts
+```
+
+Switch to a specific context:
+
+```bash
+grafanactl config use-context staging
+```
+
+View the full configuration:
+
+```bash
+grafanactl config view
+```