TopolearnClicked-together dashboards get lost and drift between environments; code makes them reviewable and reproducible.
File provisioning configures Grafana at startup from YAML files in /etc/grafana/provisioning/:
datasources/*.yaml: data sources with name, type, URL, a fixeduidand secure settings taken from environment variables.dashboards/*.yaml: providers that load dashboard JSON files from a directory into a folder, and optionally reload on change (updateIntervalSeconds).alerting/*.yaml: alert rules, contact points and policies.
Every dashboard is a JSON model (Dashboard settings, JSON Model, or Export). Key fields: a stable uid (used in URLs and links), title, panels, templating (variables), time and schemaVersion. Use data source UIDs or variables in panels, not environment-specific names, so the same JSON works in staging and production.
Other ways to manage Grafana as code:
- The HTTP API with a service account token, used by scripts and CI.
- The Terraform provider for dashboards, folders, data sources, alerting and permissions.
- SDKs that generate dashboard JSON from code (the Grafana Foundation SDK, Jsonnet with Grafonnet).
- Git Sync, generally available since Grafana 13, connects dashboards and folders to a GitHub, GitLab, Bitbucket or plain Git repository, so UI edits become commits or pull requests.
Provisioned dashboards can't be saved over in the UI by default; changes go through the files.
Example
# /etc/grafana/provisioning/datasources/prometheus.yaml
apiVersion: 1
datasources:
- name: Prometheus
uid: prom-main # stable id referenced by dashboards
type: prometheus
access: proxy
url: http://prometheus:9090
isDefault: true
jsonData:
timeInterval: 15s # = Prometheus scrape interval
---
# /etc/grafana/provisioning/dashboards/default.yaml
apiVersion: 1
providers:
- name: services
folder: Services
type: file
allowUiUpdates: false
updateIntervalSeconds: 30
options:
path: /var/lib/grafana/dashboards # *.json dashboard modelsRemember
- Provisioning YAML defines data sources, dashboards and alerting at startup
- Dashboards are JSON models; give them and data sources stable UIDs
- Automate with the API, Terraform or Git-based workflows
Watch out for
- Hard-coding data source names in dashboard JSON so it breaks in other environments.