Grafana's unified alerting can be delivered from files in the provisioning directory alongside dashboards and data sources. What rules does that delivery mechanism impose — object identity, what is replaced versus merged, and what happens to those objects in the UI?

## What can be delivered as files Grafana's provisioning directory has an `alerting/` subdirectory whose files declare, at `apiVersion: 1`: - **`groups`** — evaluation groups, each bound to a folder and an interval, containing alert rules. Each rule carries a `uid`, a title, a condition, its query/expression stages, `for` duration, labels and annotations, and its no-data/error handling. - **`contactPoints`** — named receivers with their integration settings; secrets inside them follow the same secure-field and interpolation rules as data source secrets. - **`policies`** — the notification policy tree. - **`muteTimings`** — named time intervals. - **`templates`** — notification message templates. Each has a corresponding deletion section (for example `deleteRules`, listing uid + orgId) so that removal is expressible as code rather than a manual UI action. Note the asymmetry with dashboards: for dashboards, removing the file removes the object; for alerting, you generally state the deletion explicitly. ## Identity: uid discipline An alert rule's `uid` is its identity. Provisioning matches on it to decide update-versus-create. If a rule's uid is regenerated — most often because someone rebuilt the rule in the UI and re-exported it, or because a generator derives uids from a name that changed — the result is not an update: the old rule is removed and a new rule appears. Everything attached to the old identity goes with it, including its current evaluation state (so a firing alert resolves and re-fires, paging people again), existing silences that matched by rule uid, and the historical annotations tied to it. Generating uids deterministically from a stable key, and treating a uid change as a breaking change in review, is the discipline that avoids this. ## Replace versus merge This is the sharpest edge in alerting-as-code. Rules and contact points are addressable individually, so multiple files can each own their own set. **The notification policy tree cannot be.** It is a single hierarchical object with one root, so a provisioning file that declares `policies` supplies the *whole* tree; applying it replaces what was there. Practical consequences: - You cannot let each team own a file that adds a branch for its own labels. Either one central file owns routing and teams contribute changes to it through review, or routing is expressed at the rule/label level and the tree stays deliberately generic. - A partial file applied by accident can wipe routing for everyone at once. This makes the policy file a high-blast-radius artefact that deserves stricter review and, ideally, a test that renders the tree and asserts key routes still match. ## Provenance and the read-only UI Provisioned alerting objects are tagged with a provenance value. As with dashboards, this makes them **read-only in the UI**: editing is refused so the files stay authoritative and a UI change cannot be silently overwritten at the next apply. When you genuinely want the UI to own an object — handing a rule over to a team, or migrating away from files — you disable provenance, either through a flag in the file or by calling the provisioning API with the header that suppresses the provenance marker. Do that deliberately; a mixed estate where nobody knows which rules are code-owned is worse than either pure model. ## The authoring loop Hand-writing alert rule YAML is unpleasant: the query and expression stages are verbose and easy to get subtly wrong. The workflow that actually works is to build and validate the rule in the UI, then use the **provisioning export** — an API endpoint that returns YAML (or JSON), also surfaced as an export action in the UI — to emit exactly what Grafana would accept back. Review that output, set the uid deliberately, and commit it. The same export path exists for contact points and policies, which is the fastest way to bootstrap a routing file that is already valid. ## Alternative delivery The Terraform provider exposes the same objects as resources, which some teams prefer because deletions and drift are handled by state rather than by explicit delete sections, and because it works against a hosted Grafana where you cannot mount files. The trade is state ownership and a destroy blast radius. The Grafana Operator covers similar ground in Kubernetes with reconciled custom resources. The choice does not change the semantics above: uid identity, tree replacement and provenance behave the same whichever delivery path writes them. ## Scope note All of the above is about *delivery*: how alerting objects get into Grafana and what that mechanism guarantees. How to design a rule condition, choose the `for` duration, handle no-data, or structure routing for humans is alerting design, a separate topic.