Grafana is an open source platform for visualizing and alerting on metrics, logs, and traces from many data sources. Most people meet it through its web UI, but everything that matters in a Grafana installation can also be described in files: server settings, data sources, dashboards, alert rules, contact points, and notification policies. This series focuses on that second way of working, so a Grafana instance can be rebuilt from Git at any time and nobody has to remember what someone clicked last month.

How it works

Grafana reads its configuration from layers that you can control without opening the UI:

1. Server configuration (grafana.ini and GF_* environment variables) controls ports, database, authentication, SMTP, and feature toggles.
2. Provisioning files (YAML in a provisioning/ folder) create data sources, dashboard providers, alerting resources, and plugin settings at startup.
3. Dashboard JSON files on disk are loaded by a dashboard provider and re-scanned while Grafana runs.
4. APIs and operators (Terraform, the Grafana Operator, Git Sync, the gcx CLI) manage things that files alone can’t, such as teams, service accounts, and folder permissions.

Because all of these are plain text, they fit the same GitOps workflow as the rest of your infrastructure, including Flux and Argo CD.

Core concepts

• Data source — a connection to a backend such as Prometheus, Loki, or PostgreSQL. Dashboards and alert rules query data sources by name or UID.
• Dashboard — a JSON document made of panels and variables. Grafana now uses a newer dashboard schema internally, and older JSON is migrated automatically when loaded.
• Folder — organizes dashboards and alert rules, and carries permissions.
• Provisioning — loading resources from files at startup, so they exist before anyone logs in.
• Alerting — alert rules, contact points, notification policies, mute timings, and templates, all of which can be provisioned.
• Organization — a tenant boundary inside one Grafana server; most files take an orgId.

Why operate Grafana as code

• Reproducible. A lost or new instance comes back identical from the repository.
• Reviewable. A dashboard or alert change is a pull request with a diff, not an untracked edit.
• Consistent across environments. Dev, staging, and production share definitions and differ only in values.
• Drift is visible. Provisioned resources can be locked against UI edits, so Git stays the source of truth.

Getting started

Run Grafana in a container with a provisioning/ folder mounted, add a data source file and a dashboard provider, and drop dashboard JSON next to them. The guides below start there and move on to alerting, secrets, Kubernetes, Terraform, and the Operator. They were written against Grafana 13; check the Grafana documentation for the version you install, since some as-code features are still marked alpha.