From 7edaf76de49737f2a889e5f434e799d5bc8b086d Mon Sep 17 00:00:00 2001 From: Anna Urbiztondo Date: Tue, 25 Nov 2025 09:28:20 +0100 Subject: [PATCH] Docs: asCode - export resources (#114244) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * WIP * Edits * Fixes * New title * Update docs/sources/as-code/observability-as-code/provision-resources/export-resources.md Co-authored-by: Roberto Jiménez Sánchez * Feedback * Prettier * Link * Added cli option * Prettier * Update docs/sources/as-code/observability-as-code/provision-resources/export-resources.md Co-authored-by: Roberto Jiménez Sánchez * Update docs/sources/as-code/observability-as-code/provision-resources/export-resources.md Co-authored-by: Roberto Jiménez Sánchez * Update docs/sources/as-code/observability-as-code/provision-resources/export-resources.md Co-authored-by: Roberto Jiménez Sánchez * Update docs/sources/as-code/observability-as-code/provision-resources/export-resources.md Co-authored-by: Roberto Jiménez Sánchez * Feedback * Fixes * Prettier * Fix? * Prettier --------- Co-authored-by: Roberto Jiménez Sánchez --- .../provision-resources/export-resources.md | 101 ++++++++++++++++++ .../provision-resources/git-sync-setup.md | 3 +- .../provisioned-dashboards.md | 78 ++++++++------ .../provision-resources/use-git-sync.md | 3 +- 4 files changed, 149 insertions(+), 36 deletions(-) create mode 100644 docs/sources/as-code/observability-as-code/provision-resources/export-resources.md diff --git a/docs/sources/as-code/observability-as-code/provision-resources/export-resources.md b/docs/sources/as-code/observability-as-code/provision-resources/export-resources.md new file mode 100644 index 00000000000..96bf299df08 --- /dev/null +++ b/docs/sources/as-code/observability-as-code/provision-resources/export-resources.md @@ -0,0 +1,101 @@ +--- +description: Export non-provisioned resources from Grafana. +keywords: + - dashboards + - resources + - git sync + - github + - export +labels: + products: + - enterprise + - oss + - cloud +title: Add non-provisioned resources from Grafana +menuTitle: Add non-provisioned resources +weight: 300 +canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/provision-resources/export-resources/ +--- + +# Export non-provisioned resources from Grafana + +{{< admonition type="caution" >}} + +Git Sync is available in [private preview](https://grafana.com/docs/release-life-cycle/) for Grafana Cloud. Support and documentation is available but might be limited to enablement, configuration, and some troubleshooting. No SLAs are provided. You can sign up to the private preview using the [Git Sync early access form](https://forms.gle/WKkR3EVMcbqsNnkD9). + +Git Sync and local file provisioning are [experimental features](https://grafana.com/docs/release-life-cycle/) introduced in Grafana v12 for open source and Enterprise editions. Engineering and on-call support is not available. Documentation is either limited or not provided outside of code comments. No SLA is provided. + +{{< /admonition >}} + +Git Sync is under development, and traditional operations like `import`, `copy`, `move`, or `save` to a provisioned folder are not yet supported for dashboards already existing in Grafana. To use Git Sync with existing dashboards you must export them to the repository first. + +Currently, Git Sync doesn't offer any built-in functionality to easily export resources from Grafana in bulk. However, the following options are available: + +- [Export the dashboard with Grafana CLI](#add-a-dashboard-with-grafana-cli) (recommended) +- [Copy the dashboard as JSON and commit to the repository](#add-a-dashboard-via-json-export) + +{{< admonition type="caution" >}} + +Refer to [Known limitations](https://grafana.com/docs/grafana//observability-as-code/provision-resources/intro-git-sync#known-limitations/) before using Git Sync. + +{{< /admonition >}} + +## Add a dashboard with Grafana CLI + +You can export an existing dashboard with the [Grafana CLI](https://grafana.com/docs/grafana//as-code/observability-as-code/grafana-cli/) and commit it to your Git repository. + +Use `grafanactl` to download the resources you want to sync from Grafana, and then commit and push those files to the repository. Git Sync will then detect the commit, and synchronize with Grafana. To do so, follow these steps: + +1. Set up the `grafanactl` context to point to your instance as documented in [Defining contexts](https://grafana.github.io/grafanactl/configuration/#defining-contexts). +1. Pull the resources you want to sync from the instance to your local repository: + +``` +grafanactl resources pull dashboards --path +``` + +Next, commit and push the resources to your Git repository: + +``` +git add +git commit -m "Add dashboards from Grafana" +git push +``` + +Where: + +- __: The path to the repository synced with Git Sync +- __: The path where the dashboards you want to export are located. The dashboards path must be under the repository + +See more at [Manage resources with Grafana CLI](https://grafana.github.io/grafanactl/guides/manage-resources/). + +## Add a dashboard via JSON export + +To add an existing dashboard to Git Sync via JSON export, you need to: + +1. Export the dashboard as JSON +1. Convert it to the Custom Resource Definition (CRD) format required by the Grafana App Platform +1. Commit the converted file to your Git repository + +### Required JSON format + +To export a dashboard as a JSON file it must follow this CRD structure: + +```yaml +{ + 'apiVersion': 'dashboard.grafana.app/v1beta1', + 'kind': 'Dashboard', + 'metadata': { 'name': 'dcf2lve9akj8xsd' }, + 'spec': { /* Original dashboard JSON goes here */ }, +} +``` + +The structure includes: + +- `apiVersion`: Specifies the API version (currently `v1beta1`) +- `kind`: Identifies the resource type (Dashboard) +- `metadata`: Contains the dashboard identifier `uid`. You can find the identifier in the dahsboard's URL or in the exported JSON +- `spec`: Wraps your original dashboard JSON + +## Edit Git-managed dashboards + +After you've saved a dashboard in Git, it'll be synchronized automatically, and you'll be able to work with it as any other provisioned resource. Refer to [Work with provisioned dashboards](https://grafana.com/docs/grafana//as-code/observability-as-code/provision-resources/provisioned-dashboards/) for more information. diff --git a/docs/sources/as-code/observability-as-code/provision-resources/git-sync-setup.md b/docs/sources/as-code/observability-as-code/provision-resources/git-sync-setup.md index 0a7bd7be28b..f6113fe428d 100644 --- a/docs/sources/as-code/observability-as-code/provision-resources/git-sync-setup.md +++ b/docs/sources/as-code/observability-as-code/provision-resources/git-sync-setup.md @@ -9,8 +9,9 @@ labels: products: - enterprise - oss + - cloud title: Set up Git Sync -weight: 100 +weight: 110 canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/provision-resources/git-sync-setup/ aliases: - ../../../observability-as-code/provision-resources/git-sync-setup/ # /docs/grafana/next/observability-as-code/provision-resources/git-sync-setup/ diff --git a/docs/sources/as-code/observability-as-code/provision-resources/provisioned-dashboards.md b/docs/sources/as-code/observability-as-code/provision-resources/provisioned-dashboards.md index cc4964ff9e1..83ec3869927 100644 --- a/docs/sources/as-code/observability-as-code/provision-resources/provisioned-dashboards.md +++ b/docs/sources/as-code/observability-as-code/provision-resources/provisioned-dashboards.md @@ -10,7 +10,7 @@ labels: - enterprise - oss title: Work with provisioned dashboards -weight: 300 +weight: 350 canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/provision-resources/provisioned-dashboards/ aliases: - ../../../observability-as-code/provision-resources/provisioned-dashboards/ # /docs/grafana/next/observability-as-code/provision-resources/provisioned-dashboards/ @@ -26,33 +26,30 @@ Git Sync and local file provisioning are [experimental features](https://grafana {{< /admonition >}} -Using Provisioning, you can choose to store your dashboard JSON files in either GitHub repositories using Git Sync or a local file path. +Using provisioning, you can choose to store your dashboard JSON files in either GitHub repositories using Git Sync or a local path, and manage them through the Grafana interface. Dashboards and folders synchronized using Git Sync or a local path are referred to as _provisioned_ resources. For more information, refer to the [Dashboards](https://grafana.com/docs/grafana//dashboards/) documentation. ## Provisioning methods -Dashboards and folders synchronized using Git Sync or a local file path are referred to as "provisioned" resources. - ### Git Sync provisioning -Of the two experimental options, **Git Sync** is the recommended method for provisioning your dashboards. +Of the two options, **Git Sync** is the recommended method for provisioning your dashboards. You can synchronize any new dashboards and changes to existing dashboards to your configured GitHub repository. If you push a change in the repository, those changes are mirrored in your Grafana instance. -For more information on configuring Git Sync, refer to [Introduction to Git Sync](https://grafana.com/docs/grafana//observability-as-code/provision-resources/intro-git-sync/). +For more information on configuring Git Sync, refer to [Introduction to Git Sync](https://grafana.com/docs/grafana//as-code/observability-as-code/provision-resources/intro-git-sync/). ### Local path provisioning Local path provisioning makes files from a specified path available within Grafana, and any changes made in the configured local path are updated in Grafana. Note that these provisioned resources can only be modified in the local files and not within Grafana. -Refer to [Set up file provisioning](https://grafana.com/docs/grafana//observability-as-code/provision-resources/file-path-setup) to learn more about the version of local file provisioning in Grafana 12. +Refer to [Set up file provisioning](https://grafana.com/docs/grafana//as-code/observability-as-code/provision-resources/file-path-setup) to learn more about the version of local file provisioning in Grafana 12. {{< admonition type="note" >}} -The experimental local path provisioning using **Administration** > **Provisioning** will replace the file provisioning methods Grafana uses for referencing local file. +The **Administration** > **Provisioning** local path provisioning will replace the file provisioning methods Grafana uses for referencing local files. -For production systems, use the established methods for provisioning file systems in Grafana. -Refer to [Provision Grafana](https://grafana.com/docs/grafana//administration/provisioning/#provision-folders-structure-from-filesystem-to-grafana) for more information. +For production systems, use the established methods for provisioning file systems in Grafana. Refer to [Provision Grafana](https://grafana.com/docs/grafana//administration/provisioning/#provision-folders-structure-from-filesystem-to-grafana) for more information. {{< /admonition >}} ## Manage dashboards provisioned with Git Sync @@ -61,9 +58,9 @@ Using Git Sync, you can manage your dashboards in the UI and synchronize them wi Git Sync changes the behavior in Grafana for dashboards that are saved in Git Sync: -- Dashboards saved in your repository or local folder configured with Git Sync appear in a provisioned folder in Grafana. -- Any dashboard folders saved with Git Sync have a **Provisioned** label in the UI. -- Any changes to a provisioned resources have to be saved to the repository by opening a pull request or committing directly to the `main` branch. +- Dashboards saved in your repository or local folder configured with Git Sync appear in a provisioned folder in Grafana +- Any dashboard folders saved with Git Sync have a **Provisioned** label in the UI +- Any changes to a provisioned resources have to be saved to the repository by opening a pull request or committing directly to the `main` branch You can set a single folder, or multiple folders to a different repository, with up to 10 connections. @@ -71,18 +68,29 @@ You can set a single folder, or multiple folders to a different repository, with By default, Git version control uses a branch-based workflow for changes. This means that you can: -- Commit changes to an existing branch (such as `main`) or save them to a new branch in your GitHub repository. -- Use pull requests to review changes to dashboards. -- Preview the changes before merging. +- Commit changes to an existing branch (such as `main`) or save them to a new branch in your GitHub repository +- Use pull requests to review changes to dashboards +- Preview the changes before merging To learn more about Git, refer to [Getting Started - About Version Control](https://git-scm.com/book/en/v2/Getting-Started-About-Version-Control) of the [Pro Git book](https://git-scm.com/book/en/v2) in the official Git documentation. ### Add and save a new dashboard +{{< admonition type="note" >}} + +If you want to add an existing dashboard to your provisioned resources, refer to [Export non-provisioned resources from Grafana](https://grafana.com/docs/grafana//as-code/observability-as-code/provision-resources/export-resources/). + +{{< /admonition >}} + +You have two options for creating **new** dashboards or folders in Git Sync: + +- Create them directly within Git Sync-managed folders in the Grafana UI +- Add them by committing JSON files to your Git repository + When you create a new dashboard in a provisioned folder associated with a GitHub repository, you follow the same process you use for any new dashboard. Refer to [Create a dashboard](http://grafana.com/docs/grafana//dashboards/build-dashboards/create-dashboard/) for more information. -After you create the dashboard, the steps are similar to [Save dashboard changes to GitHub](#save-dashboard-changes-to-github). +After you create the dashboard, follow these steps: 1. Select **Save** to preserve the new dashboard. 1. Enter a title for the dashboard and a description. @@ -94,26 +102,27 @@ After you create the dashboard, the steps are similar to [Save dashboard changes ### Save dashboard changes to GitHub -When you edit a provisioned resource, you are prompted to save or discard those changes. -Saving changes requires opening a pull request in your GitHub repository. +When you edit a provisioned resource, you're prompted to save or discard those changes. Saving changes requires opening a pull request in your GitHub repository. + +To save dashboard changes: 1. Select **Edit** to update a provisioned dashboard. Make your desired changes. 1. Click **Save dashboard**. 1. On the **Provisioned dashboard** panel, choose the options you want to use: - - **Update default refresh value**: Check this box to make the current refresh the new default. - - **Update default variable values**: Check this box to make the current values the new default. - - **Path**: Provide the path for your repository, ending in a JSON or YAML file. - - **Workflow:** Select **Push to main** to make a Git commit directly to the repository or **Push to a new branch** to create a pull request. - - **Branch**: Specify the branch name in GitHub (for example, main). This option only appears if you select **Push to a new branch**. - - **Comment**: Add a comment describing your changes. + - **Update default refresh value**: Check this box to make the current refresh the new default + - **Update default variable values**: Check this box to make the current values the new default + - **Path**: Provide the path for your repository, ending in a JSON or YAML file + - **Workflow:** Select **Push to main** to make a Git commit directly to the repository or **Push to a new branch** to create a pull request + - **Branch**: Specify the branch name in GitHub (for example, main). This option only appears if you select **Push to a new branch** + - **Comment**: Add a comment describing your changes 1. Optional: Select the **Changes** tab to view the differences between the updates you made and the original resource. 1. Select **Save**. -1. If you chose **Push to a new branch**, select **Open a pull request in GitHub** to open a new PR to your repository. GitHub opens with your dashboard’s code as the contents of the PR. +1. If you chose **Push to a new branch**, select **Open a pull request in GitHub** to open a new PR to your repository. GitHub opens with your dashboard's code as the contents of the PR. 1. Follow your usual GitHub workflow to save and merge the PR to your repository. @@ -121,18 +130,19 @@ Saving changes requires opening a pull request in your GitHub repository. You can remove a provisioned dashboard by deleting the dashboard from the repository. The Grafana UI updates when the changes from the GitHub repository sync. -To restore a deleted dashboard, raise a PR directly in your GitHub repository. Restoring resources from the UI is currently not possible. +To restore a deleted dashboard, raise a PR directly in your GitHub repository. Restoring resources from the UI isn't currently possible. -### Tips +### Best practices -- Use GitHub pull requests for changes to maintain review processes. -- Provide clear commit messages describing your changes. -- Regularly sync your repository to keep Grafana up to date. -- Review the **Events** tab to monitor sync status. +Follow these recommendations when working with provisioned dashboards: + +- **Use GitHub pull requests for changes**: Maintain review processes for dashboard modifications +- **Provide clear commit messages**: Describe your changes to help with tracking and collaboration +- **Regularly sync your repository**: Keep Grafana up to date with the latest changes +- **Review the Events tab**: Monitor sync status to ensure changes are applied correctly ## Manage dashboards provisioned with file provisioning -To update any resources in the local path, you need to edit the files directly and then save them locally. -These changes are synchronized to Grafana. However, you can't create, edit, or delete these resources using the Grafana UI. +To update any resources in the local path, you need to edit the files directly and then save them locally. These changes are synchronized to Grafana. However, you can't create, edit, or delete these resources using the Grafana UI. Refer to [Set up file provisioning](https://grafana.com/docs/grafana//observability-as-code/provision-resources/file-path-setup/) for configuration instructions. diff --git a/docs/sources/as-code/observability-as-code/provision-resources/use-git-sync.md b/docs/sources/as-code/observability-as-code/provision-resources/use-git-sync.md index 257e83c41ed..f7d37d4b94e 100644 --- a/docs/sources/as-code/observability-as-code/provision-resources/use-git-sync.md +++ b/docs/sources/as-code/observability-as-code/provision-resources/use-git-sync.md @@ -11,9 +11,10 @@ labels: products: - enterprise - oss + - cloud title: Manage provisioned repositories with Git Sync menuTitle: Manage repositories with Git Sync -weight: 400 +weight: 120 canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/provision-resources/use-git-sync/ aliases: - ../../../observability-as-code/provision-resources/use-git-sync/ # /docs/grafana/next/observability-as-code/provision-resources/use-git-sync/