Skip to content
Tutorials Center
My learning

Topics

Lesson 33 of 37 ยท Administration and Provisioning

Grafana Provisioning: Data Sources, Dashboards and Alerting as Files

Configure Grafana from files instead of clicking: provisioning folders, data source YAML, dashboard providers, alerting provisioning, environment variables and the Terraform and API options.

Clicking through the UI is fine for exploring, but a real installation needs to be repeatable. If a server dies, or you add a staging environment, you want the same data sources, dashboards and alert rules to appear without anyone retyping them. Provisioning is Grafana's answer: you describe resources in files, and Grafana loads them at startup (and periodically for dashboards). The files go into version control, so changes are reviewed like code.

Grafana is not available on this site, so everything here is shown as read-only file examples and shell commands. The runnable blocks are Python stand-ins that validate a provisioning structure the way a reviewer or a CI check might. They are not Grafana, and the file keys below come from our knowledge of Grafana's documented provisioning format; check the documentation for your version before relying on a field.

Where the files live

Grafana reads its configuration from grafana.ini (on Linux typically /etc/grafana/grafana.ini) and provisioning files from the directory named by paths.provisioning, usually /etc/grafana/provisioning. Inside it:

TEXT
provisioning/
  datasources/   *.yaml   data sources
  dashboards/    *.yaml   dashboard providers (where the JSON files are)
  alerting/      *.yaml   alert rules, contact points, policies, templates, mute timings
  plugins/       *.yaml   app plugins
  access-control/ *.yaml  RBAC roles (Enterprise/Cloud)

Grafana reads every .yaml or .yml file in these folders when it starts. Docker users mount the folder as a volume; Kubernetes users put the files in a ConfigMap or Secret and mount it. A restart (or an API reload call for some types) applies changes.

Provisioning data sources

A data source file has apiVersion: 1 and a list of data sources:

YAML
apiVersion: 1

datasources:
  - name: Prometheus
    type: prometheus
    uid: prom-main
    access: proxy
    url: http://prometheus:9090
    isDefault: true
    jsonData:
      timeInterval: 15s
      httpMethod: POST

  - name: Postgres sales
    type: postgres
    uid: pg-sales
    url: db.internal:5432
    user: grafana_ro
    jsonData:
      database: sales
      sslmode: require
    secureJsonData:
      password: ${PG_PASSWORD}

Key points:

  • uid: set it explicitly. Dashboards refer to data sources by UID, so a fixed UID means the same dashboards work in every environment.
  • access: proxy means Grafana's backend makes the requests (the normal choice; browser access mode is deprecated).
  • secureJsonData holds secrets. They are stored encrypted. Never commit real passwords: use environment variables ($VAR or ${VAR}) which Grafana expands when it reads the file.
  • jsonData holds non-secret options, different per plugin type.
  • editable: false blocks changes from the UI so the file stays the source of truth.
  • A deleteDatasources list removes data sources by name and org.

Provisioning dashboards

Dashboard provisioning has two parts: a provider that says where JSON files are, and the JSON files themselves.

YAML
apiVersion: 1

providers:
  - name: "team dashboards"
    orgId: 1
    folder: "Team"
    type: file
    disableDeletion: true
    updateIntervalSeconds: 30
    allowUiUpdates: false
    options:
      path: /var/lib/grafana/dashboards
      foldersFromFilesStructure: true

Grafana scans path every updateIntervalSeconds and imports new or changed .json files into the folder. With foldersFromFilesStructure: true, subdirectories become folders. allowUiUpdates: false means edits in the UI cannot be saved over the provisioned dashboard (you can still save a copy), which prevents drift. A provisioned dashboard is identified by its uid; if the JSON has a uid, updating the file updates the same dashboard. You will see how to produce such JSON in dashboards as code.

Provisioning alerting

Alerting resources can be provisioned too, in provisioning/alerting: alert rules (in groups), contact points, notification policies, mute timings and templates. The structure mirrors what you have seen in the earlier lessons:

YAML
apiVersion: 1

contactPoints:
  - orgId: 1
    name: payments-oncall
    receivers:
      - uid: slack-payments
        type: slack
        settings:
          url: ${SLACK_WEBHOOK_URL}

policies:
  - orgId: 1
    receiver: payments-oncall
    group_by: ["alertname", "service"]
    routes:
      - receiver: payments-oncall
        object_matchers:
          - ["severity", "=", "critical"]

Alert rule provisioning files are long, because each rule includes the query model and expressions (data list with refId, datasourceUid, model). Many teams export an existing rule from the UI (Export in the rule's menu) and keep the file, rather than writing it by hand. Provisioned rules appear read-only in the UI, and the HTTP provisioning API is the alternative when files are not convenient.

Python Stand-in: lint a data source provisioning file

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

A check like this in CI catches the mistakes that are easy to make by hand: missing UIDs, plaintext secrets, two default data sources.

Environment variables

Grafana expands $VAR and ${VAR} in provisioning files. This lets one file work in staging and production and keeps secrets out of Git. To write a literal dollar sign, double it ($$). Variables are also read from the environment for grafana.ini settings: any setting can be overridden with GF_<SECTION>_<KEY>, for example GF_SECURITY_ADMIN_PASSWORD or GF_SERVER_ROOT_URL; this is the usual way to configure Docker deployments.

Python Stand-in: expand ${VAR} like provisioning does

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Other ways to automate

Approach Good for
Provisioning files A single Grafana per environment, GitOps via file mounts
HTTP API Scripts and pipelines that create folders, dashboards, users
Terraform provider Declaring Grafana resources with other infrastructure; state and plan/apply
Grafana Operator (Kubernetes) Dashboards and data sources as Kubernetes custom resources
Git Sync / Observability as Code Newer features that sync dashboards with a Git repository; check availability in your version

Choose provisioning when the files should be the single truth; choose the API when something has to happen dynamically.

flowchart LR
    G["Git repository<br/>YAML + JSON"] --> CI["CI pipeline<br/>lint + review"]
    CI --> D["Deploy<br/>mount provisioning/"]
    D --> GF["Grafana starts<br/>reads files"]
    GF --> U["Data sources, dashboards,<br/>alerts appear"]

Changes flow from a reviewed commit to a running Grafana without clicking.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why should a provisioned data source have a fixed uid?

    A stable UID keeps dashboard JSON portable between environments.
  2. 2. How do you keep a password out of a provisioning file in Git?

    Grafana expands environment variables when it reads the file, so the secret can live outside Git.
  3. 3. What does allowUiUpdates: false do on a dashboard provider?

    The file remains the source of truth, so changes in the UI cannot overwrite it.
  4. 4. Which environment variable overrides the server root URL in grafana.ini?

    Settings use the pattern GF_<SECTION>_<KEY>, here the root_url key in the [server] section.

Summary

  • Provisioning loads data sources, dashboards, alerting resources and plugins from files at startup.
  • Data sources need apiVersion: 1, a fixed uid, and secrets in secureJsonData via environment variables.
  • Dashboard providers point to a path of JSON files and a target folder; allowUiUpdates: false prevents drift.
  • Alerting can be provisioned too; exporting from the UI is the easiest way to get the file format.
  • Terraform, the HTTP API and the Kubernetes operator are alternatives; lint files in CI.

Next: Users, Teams and Permissions