Provision Grafana Data Sources and Dashboards from Files

Your team adds a new Prometheus data source to Grafana by clicking through Settings > Data Sources > Add data source. A week later, someone changes the scrape URL in the UI, and staging no longer matches production. When a new engineer asks how observability is configured, the answer is a screen recording and a list of manual steps.

File-based provisioning lets you define Grafana data sources and dashboards in YAML and JSON files. Grafana reads them from a provisioning directory and applies them on startup or when files change. This post shows how to set it up, verify it, and where it falls short.

Takeaway: Treat Grafana configuration like application code: version it, review it, and deploy it through CI/CD instead of clicking it into existence.

Where provisioning files live

Grafana looks for provisioning files under the directory set by GF_PROVISIONING_PATH, commonly /etc/grafana/provisioning. Inside, datasources/ holds YAML files that declare data sources, and dashboards/ holds dashboard JSON files plus a provider YAML file that tells Grafana where to find them. A data source is a backend such as Prometheus or Loki that Grafana queries; a dashboard is a saved JSON layout of panels and variables.

Worked example: Prometheus data source and file-backed dashboard

Use this file tree on the Grafana host:

/etc/grafana/provisioning/
├── datasources/
│   └── prometheus.yaml
└── dashboards/
    ├── provider.yaml
    └── production-overview.json

datasources/prometheus.yaml:

apiVersion: 1
datasources:
  - name: prometheus
    type: prometheus
    access: proxy
    url: http://prometheus:9090
    isDefault: true
    editable: true

The editable field controls whether someone can change the data source in the Grafana UI. Set it to false to make the provisioned version read-only in the browser; Grafana will overwrite manual UI changes on the next refresh.

dashboards/provider.yaml tells Grafana to load dashboards from disk:

apiVersion: 1
providers:
  - name: production-dashboards
    type: file
    disableDeletion: false
    updateIntervalSeconds: 30
    options:
      path: /etc/grafana/provisioning/dashboards

updateIntervalSeconds is how often Grafana checks the filesystem for changed dashboard JSON. Place your dashboard JSON at production-overview.json; Grafana imports it automatically.

Apply the files

Run these commands on the host running Grafana, or through your configuration management tool. You need sudo or root access to write under /etc/grafana, and the files must be readable by the grafana system user.

sudo install -o grafana -g grafana -m 0644 prometheus.yaml /etc/grafana/provisioning/datasources/prometheus.yaml
sudo install -o grafana -g grafana -m 0644 provider.yaml /etc/grafana/provisioning/dashboards/provider.yaml
sudo install -o grafana -g grafana -m 0644 production-overview.json /etc/grafana/provisioning/dashboards/production-overview.json

Restart Grafana, or touch the YAML files so Grafana detects the change:

sudo systemctl restart grafana-server
# or
sudo touch /etc/grafana/provisioning/datasources/prometheus.yaml

Expected checks: the prometheus data source appears in Connections > Data Sources, its health check is green, and production-overview appears in Dashboards > Manage. Risk: if you mark a dashboard non-editable and a teammate edits it in the UI, the next provisioning refresh discards those edits. Never commit passwords or API keys in plain text; use environment variable references such as ${API_KEY} where the field supports it.

Verify the result

Check that Grafana parsed and applied the files:

• curl -s http://localhost:3000/api/health should report a healthy database.
• Watch journalctl -u grafana-server -f for provisioning messages and parse errors.
• Query /api/datasources and confirm prometheus is present with the expected URL.
• Query /api/search?type=dash-db and confirm the dashboard title matches your JSON file.

Field names and provisioning behavior can vary between Grafana major versions. Check the documentation for your installed version before adopting new keys.

Limitations and rollback

File-based provisioning does not manage users, teams, or folder permissions; configure those separately. It also does not stop someone from creating a new data source in the UI unless you restrict UI access. Because writing provisioning files changes Grafana's runtime state, roll back by reverting the YAML or JSON in version control, redeploying the previous file, and restarting Grafana or touching the files to force a reload.

Start small and review diffs

Provision one data source and one dashboard first. Add the files to your repository, require pull requests, and inspect the diff before deploying. Once the pattern is proven, expand to additional environments and data sources, keeping secrets out of the files and verifying through the API after every change.