Grafana Provisioning: Automate Dashboards and Data Sources

Introduction

Grafana provisioning is a powerful feature designed for DevOps engineers and SREs who need to automate the configuration of dashboards, data sources, alerting, and more in their observability stack. By leveraging provisioning, you can define Grafana resources as code using declarative YAML or JSON files, enabling version control, repeatable deployments, and seamless integration with GitOps workflows.

Why Provisioning Matters

Manual configuration of dashboards and data sources is error-prone, time-consuming, and hard to reproduce across environments. Provisioning addresses these challenges by allowing you to:

• Automate setup and updates for Grafana resources
• Version control configurations alongside your code
• Promote consistency across development, staging, and production
• Rollback changes quickly if needed
• Integrate with CI/CD pipelines and GitOps workflows

What Can You Provision in Grafana?

Grafana supports provisioning for a range of resources, including:

• Dashboards
• Data sources
• Alerting resources
• RBAC (role-based access control) settings
• Plugins (applications)

Note that installation of data source plugins and visualizations must be handled outside the provisioning process[7].

How Grafana Provisioning Works

Provisioning uses configuration files stored on disk, typically in YAML or JSON format. When Grafana starts, it reads these files and loads the specified resources automatically. This makes it easy to manage changes declaratively and ensure your instance is always in a known-good state[1][7].

Directory Structure and Configuration Paths

Provisioning files are placed under the conf/provisioning/ directory in your Grafana installation. This directory includes subfolders for each resource type:

• conf/provisioning/datasources/
• conf/provisioning/dashboards/
• conf/provisioning/notifiers/
• conf/provisioning/alerting/

The location of these directories can be customized via the grafana.ini configuration file, using the permitted_provisioning_paths setting[4].

[paths]
permitted_provisioning_paths = /etc/grafana/provisioning/ | conf/provisioning/

Practical Example: Provisioning a Data Source

To provision a Prometheus data source, create a YAML file in conf/provisioning/datasources/prometheus.yaml:

apiVersion: 1

datasources:
  - name: Prometheus
    type: prometheus
    access: proxy
    url: http://prometheus:9090
    isDefault: true
    editable: false

This configuration will create a non-editable, default Prometheus data source pointing to http://prometheus:9090 upon Grafana startup.

Practical Example: Provisioning Dashboards

To automate dashboard setup, use a YAML file in conf/provisioning/dashboards/main.yaml:

apiVersion: 1

providers:
  - name: 'default'
    orgId: 1
    folder: ''
    type: file
    disableDeletion: false
    editable: true
    options:
      path: /etc/grafana/dashboards

Next, place your dashboard JSON files in the directory /etc/grafana/dashboards/. Grafana will automatically load and update these dashboards during startup or when files change.

Enabling File Provisioning Features

To allow Grafana to use file provisioning, ensure the following settings are enabled in your grafana.ini:

[feature_toggles]
provisioning = true
kubernetesDashboards = true

These toggles are required from Grafana 10 onwards to activate new provisioning features, including local file and Kubernetes-based dashboard management[4].

Provisioning Alerting Resources

Alerting resources can also be provisioned via configuration files, making it easy to share and version alert rules across teams and environments. Place your alerting YAML files in conf/provisioning/alerting/ as described in Grafana's documentation[6].

Best Practices for Grafana Provisioning

• Store provisioning files in version control (e.g., Git) to track changes and enable rollbacks.
• Use environment-specific directories to separate configurations for dev, staging, and production.
• Test provisioning updates in a non-production environment before rollout.
• Combine provisioning with CI/CD pipelines to automate deployments and updates.
• Document your directory structure and configuration standards for team clarity.

Common Pitfalls and Troubleshooting

• Incorrect file paths: Ensure your provisioning files are in permitted directories as defined by permitted_provisioning_paths.
• YAML/JSON syntax errors: Use a linter to validate files before deploying.
• Permissions: Grafana must have read access to provisioning files and directories.
• Grafana restart required: Some changes (especially data sources) require a Grafana restart to take effect.

Conclusion: Streamline Observability with Provisioning

Grafana provisioning empowers teams to manage observability resources as code, improving reliability, scalability, and collaboration. Adopting provisioning is a key step toward modern, automated, and reproducible observability workflows in any DevOps or SRE environment.