Docs: OaC/Git Sync updates for Obs Con (#111792)
* Changes for Obs Con * Edits * Minor renderer tweak * Renderer, caution notes * Prettier * Public * Update docs/sources/observability-as-code/provision-resources/git-sync-setup.md Co-authored-by: Jack Baldry <jack.baldry@grafana.com> * Jack's feedback * Link text * Messaging * Notes * Prettier --------- Co-authored-by: Jack Baldry <jack.baldry@grafana.com>
This commit is contained in:
Anna Urbiztondo
co-authored by
Jack Baldry
Jack Baldry
parent
510b86450c
commit
6e47fefc63
@@ -16,9 +16,12 @@ weight: 100
|
||||
# Introduction to Git Sync
|
||||
|
||||
{{< admonition type="caution" >}}
|
||||
Git Sync is an [experimental feature](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. Enable the `provisioning` and `kubernetesDashboards` feature toggles in Grafana to use this feature. This feature is not publicly available in Grafana Cloud yet. Only the cloud-hosted version of GitHub (GitHub.com) is supported at this time. GitHub Enterprise is not yet compatible.
|
||||
|
||||
Sign up for Grafana Cloud Git Sync early access using [this form](https://forms.gle/WKkR3EVMcbqsNnkD9).
|
||||
Git Sync is available in [private preview](https://grafana.com/docs/release-life-cycle/) for Grafana Cloud, and is an [experimental feature](https://grafana.com/docs/release-life-cycle/) in Grafana v12 for open source and Enterprise editions.
|
||||
|
||||
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).
|
||||
|
||||
{{< /admonition >}}
|
||||
|
||||
@@ -28,55 +31,65 @@ Using Git Sync, you can:
|
||||
- Manage dashboard configuration outside of Grafana instances
|
||||
- Replicate dashboards across multiple instances
|
||||
|
||||
Whenever a dashboard is modified, Grafana can commit changes to Git upon saving. Users can configure settings to either enforce PR approvals before merging or allow direct commits.
|
||||
|
||||
Users can push changes directly to GitHub and see them in Grafana. Similarly, automated workflows can do changes that will be automatically represented in Grafana by updating Git.
|
||||
|
||||
Because the dashboards are defined in JSON files, you can enable as-code workflows where the JSON is output from Go, TypeScript, or another coding language in the format of a dashboard schema.
|
||||
|
||||
To learn more about creating dashboards in a coding language to provision them for Git Sync, refer to the [Foundation SDK](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/foundation-sdk) documentation.
|
||||
|
||||
## How it works
|
||||
|
||||
Git Sync is bidirectional and also works with changes done directly in GitHub as well as within the Grafana UI.
|
||||
Grafana periodically polls GitHub at a regular internal to synchronize any changes.
|
||||
With the webhooks feature enabled, repository notifications appear almost immediately.
|
||||
Without webhooks, Grafana polls for changes at the specified interval.
|
||||
The default polling interval is 60 seconds.
|
||||
Because dashboards are defined in JSON files, you can enable as-code workflows where the JSON file is an output from Go, TypeScript, or another coding language in the format of a dashboard schema. To learn more about creating dashboards in a coding language to provision them for Git Sync, refer to the [Foundation SDK](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/foundation-sdk) documentation.
|
||||
|
||||
Any changes made in the provisioned files stored in the GitHub repository are reflected in the Grafana database.
|
||||
The Grafana UI reads the database and updates the UI to reflect these changes.
|
||||
Git Sync is bidirectional and works both with changes done directly in GitHub as well as in the Grafana UI.
|
||||
|
||||
### Make changes in Grafana
|
||||
|
||||
Whenever you modify a dashboard directly from the UI, Grafana can commit changes to Git upon saving. You can configure settings to either enforce PR approvals before merging in your repository, or allow direct commits.
|
||||
|
||||
Grafana periodically polls GitHub at a regular internal to synchronize any changes. The default polling interval is 60 seconds.
|
||||
|
||||
- If you enable the [webhooks feature](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/provision-resources/git-sync-setup/#configure-webhooks-and-image-rendering), repository notifications appear almost immediately.
|
||||
- Without webhooks, Grafana polls for changes at the specified interval.
|
||||
|
||||
### Make changes in your GitHub repositories
|
||||
|
||||
With Git Sync, you can make changes in your provisioned files in GitHub and see them in Grafana. Automated workflows ensure those changes are automatically represented in the Grafana database by updating Git. The Grafana UI reads the database and updates the UI to reflect these changes.
|
||||
|
||||
## Known limitations
|
||||
|
||||
Git Sync is under development and the following limitations apply:
|
||||
|
||||
- You can only authenticate using your GitHub token.
|
||||
- Support for native Git and other providers, such as GitLab or Bitbucket, is scheduled.
|
||||
- If you're using Git Sync in Grafana Cloud you can only sync specific folders for the moment. Git Sync will be available for your full instance soon.
|
||||
- Restoring resources from the UI is currently not possible. As an alternative, you can restore dashboards directly in your GitHub repository by raising a PR, and they will be updated in Grafana.
|
||||
|
||||
## Common use cases
|
||||
|
||||
Git Sync in Grafana lets you manage dashboards as code.
|
||||
Because your dashboard JSON files are stored in GitHub, you and your team can version control, collaborate, and automate deployments efficiently.
|
||||
Git Sync in Grafana lets you manage your dashboards as code as JSON files stored in GitHub. You and your team can version control, collaborate, and automate deployments efficiently.
|
||||
|
||||
### Version control and auditing
|
||||
|
||||
Organizations can maintain a structured, version-controlled history of Grafana dashboards.
|
||||
The version control lets you revert to previous versions when necessary, compare modifications across commits, and ensure transparency in dashboard management.
|
||||
Organizations can maintain a structured, version-controlled history of Grafana dashboards. The version control lets you revert to previous versions when necessary, compare modifications across commits, and ensure transparency in dashboard management.
|
||||
|
||||
Additionally, having a detailed history of changes enhances compliance efforts, as teams can generate audit logs that document who made changes, when they were made, and why.
|
||||
|
||||
### Automated deployment and CI/CD integration
|
||||
|
||||
Teams can streamline their workflow by integrating dashboard updates into their CI/CD pipelines.
|
||||
By pushing changes to GitHub, automated processes can trigger validation checks, test dashboard configurations, and deploy updates programmatically using the `grafanactl` CLI and Foundation SDK.
|
||||
Teams can streamline their workflow by integrating dashboard updates into their CI/CD pipelines. By pushing changes to GitHub, automated processes can trigger validation checks, test dashboard configurations, and deploy updates programmatically using the `grafanactl` CLI and Foundation SDK.
|
||||
|
||||
This reduces the risk of human errors, ensures consistency across environments, and enables a faster, more reliable release cycle for dashboards used in production monitoring and analytics.
|
||||
|
||||
### Collaborative dashboard development
|
||||
|
||||
With Git Sync, multiple users can work on dashboards simultaneously without overwriting each other’s modifications.
|
||||
By leveraging pull requests and branch-based workflows, teams can submit changes for review before merging them into the main branch. This process not only improves quality control but also ensures that dashboards adhere to best practices and organizational standards. Additionally, GitHub’s built-in discussion and review tools facilitate effective collaboration, making it easier to address feedback before changes go live.
|
||||
By leveraging pull requests and branch-based workflows, teams can submit changes for review before merging them into the main branch. This process not only improves quality control but also ensures that dashboards adhere to best practices and organizational standards.
|
||||
|
||||
Additionally, GitHub’s built-in discussion and review tools facilitate effective collaboration, making it easier to address feedback before changes go live.
|
||||
|
||||
### Multi-environment synchronization
|
||||
|
||||
Enterprises managing multiple Grafana instances, such as development, staging, and production environments, can seamlessly sync dashboards across these instances.
|
||||
This ensures consistency in visualization and monitoring configurations, reducing discrepancies that might arise from manually managing dashboards in different environments.
|
||||
Enterprises managing multiple Grafana instances, such as development, staging, and production environments, can seamlessly sync dashboards across these instances. This ensures consistency in visualization and monitoring configurations, reducing discrepancies that might arise from manually managing dashboards in different environments.
|
||||
|
||||
By using Git Sync, teams can automate deployments across environments, eliminating repetitive setup tasks and maintaining a standardized monitoring infrastructure across the organization.
|
||||
|
||||
### Disaster recovery and backup
|
||||
|
||||
By continuously syncing dashboards to GitHub, organizations can create an always-updated backup, ensuring dashboards are never lost due to accidental deletion or system failures.
|
||||
If an issue arises--such as a corrupted dashboard, unintended modification, or a system crash--teams can quickly restore the latest functional version from the Git repository.
|
||||
This not only minimizes downtime but also adds a layer of resilience to Grafana monitoring setups, ensuring critical dashboards remain available when needed.
|
||||
|
||||
If an issue arises, such as a corrupted dashboard, unintended modification, or a system crash, teams can quickly restore the latest functional version from the Git repository. This not only minimizes downtime but also adds a layer of resilience to Grafana monitoring setups, ensuring critical dashboards remain available when needed.
|
||||
|
||||
Reference in New Issue
Block a user