Grafana datasources don’t have to be clicked into existence one by one.
Let’s see it in action. Imagine we have a Grafana instance running, and we want to add a Prometheus datasource. Instead of logging into the Grafana UI, navigating to "Configuration" -> "Data Sources" -> "Add data source," and filling out the form, we can define this in a YAML file.
Here’s a sample datasource.yaml for Prometheus:
apiVersion: 1
datasources:
- name: Prometheus
type: prometheus
access: proxy
url: http://prometheus.example.com:9090
isDefault: true
editable: false
jsonData:
httpMethod: GET
When Grafana starts up, it scans a specific directory (usually /etc/grafana/provisioning/datasources/) for YAML files like this. If it finds one, it will automatically configure the datasource defined within. This means that every time Grafana restarts, or even starts for the first time with this file present, the Prometheus datasource will be ready to go, pre-configured with the correct URL and name.
This is part of Grafana’s "provisioning" system, designed to manage configuration declaratively. The core idea is to treat your Grafana setup, just like your applications, as code. You define the desired state in configuration files, and Grafana handles the rest. This covers not just datasources, but also dashboards, users, and even alerts.
Internally, Grafana has a provisioning service. When Grafana boots, this service reads configuration files from designated directories. For datasources, it looks for YAML files. It parses these files, validates the structure, and then uses its internal APIs to create or update the datasources. The apiVersion: 1 and datasources: keys are standard for this system. Each entry under datasources describes a single datasource: its name (what you’ll see in the UI), its type (e.g., prometheus, influxdb, mysql), and importantly, its url. The access mode (proxy means Grafana itself will make requests to the datasource, direct means the browser will) is crucial for security and network routing. isDefault: true makes this the primary datasource, and editable: false prevents users from changing it via the UI.
The jsonData field is where you put datasource-specific settings. For Prometheus, this might include the httpMethod or authentication details. For other datasources, it could be tlsSkipVerify, authType, or specific query parameters. This allows for fine-grained control over how Grafana interacts with each backend.
The real power here is in automation and consistency. Imagine you have multiple Grafana instances – staging, production, and for different teams. Instead of manually configuring each one, you can use a single set of YAML files managed in a Git repository. When you need to add a new datasource, you update the YAML, commit it, and your CI/CD pipeline can deploy that change to all your Grafana instances simultaneously. This eliminates configuration drift and ensures that every Grafana environment has the exact same datasources set up.
When you define a datasource in YAML, Grafana doesn’t just create it; it manages its lifecycle. If you update the URL in the YAML and restart Grafana, the datasource will be updated. If you remove the entry from the YAML and restart, the datasource will be deleted. This makes managing your Grafana configuration as dynamic and automated as managing your application deployments.
The next step is to see how you can provision dashboards alongside your datasources.