Grafana resources and Terraform on Grafana Labs

Grafana resources and Terraform

Wed, 15 Jul 2026 16:12:13 +0200

Grafana resources and Terraform

What you’ll do in this module:

Resources as code in Grafana. What it means to define Grafana resources in configuration files instead of the UI.
Grafana resources in Terraform. The Grafana Terraform provider and the resources it supports.
Anatomy of an alert rule. How a Grafana alert rule maps to a Terraform resource block.
The alerting pipeline. How alert rules, contact points, and notification policies work together.
Deploy an alert rule learning path. Hands-on deployment of a complete alerting pipeline.

Estimated time: 15 minutes

Resources as code in Grafana

Wed, 15 Jul 2026 16:12:13 +0200

What “resources as code” means

When you manage Grafana resources as code, you define them in configuration files instead of configuring them through the UI. Those files live in version control, go through code review, and deploy through a pipeline.

Manual (UI)	As code (Terraform)
Click through forms to create an alert rule	Write an HCL block that defines the rule
Changes aren’t tracked	Every change is a Git commit
Hard to replicate across environments	Same code deploys to staging and production
No review process	Pull requests catch mistakes before they reach Grafana

What resources can you manage?

Grafana isn’t just dashboards. You can manage a wide range of resources across the entire Grafana ecosystem as code.

Category	Examples
Visualization	Dashboards, folders, library panels, playlists
Alerting	Alert rule groups, contact points, notification policies, mute timings, message templates
Data	Data sources, data source permissions
Access control	Service accounts, teams, users, roles, RBAC
Platform	Organizations, SLOs, plugins, annotations
Grafana Cloud	Cloud stacks, access policies, Fleet Management, IRM/OnCall

Grafana resources in Terraform

Wed, 15 Jul 2026 16:12:13 +0200

The Grafana Terraform provider

Terraform uses HashiCorp Configuration Language (HCL), an open-source toolkit to define infrastructure and resources as code.

The Grafana Terraform provider is the bridge between your Terraform configuration and the Grafana API. It handles authentication, resource lifecycle management, and state tracking. You declare it in your configuration and authenticate with your Grafana instance URL and a service account token.

terraform {
  required_providers {
    grafana = {
      source  = "grafana/grafana"
      version = ">= 2.9.0"
    }
  }
}

provider "grafana" {
  url  = var.grafana_url
  auth = var.grafana_token
}

Core Grafana infrastructure resources with Terraform

The provider manages a wide range of resources. These are the some of the resources used for a Grafana instance.

Terraform resource	What it manages
`grafana_dashboard`	Dashboard definitions from JSON
`grafana_folder`	Organizational folders for dashboards and alerts
`grafana_data_source`	Connections to Prometheus, Loki, Tempo, and other backends
`grafana_library_panel`	Reusable panels shared across dashboards
`grafana_organization`	Grafana organizations (self-managed only)
`grafana_service_account`	API credentials for automated tools
`grafana_team`	Team definitions and memberships
`grafana_slo`	Service Level Objectives with burn rate alerting

Grafana Cloud resources with Terraform

For Grafana Cloud, additional resources manage stack-level configuration.

Terraform resource	What it manages
`grafana_cloud_stack`	Grafana Cloud stack provisioning
`grafana_cloud_access_policy`	Cloud access policies and tokens
`grafana_cloud_stack_service_account`	Service accounts scoped to a Cloud stack

Anatomy of an alert rule in Terraform

Wed, 15 Jul 2026 16:12:13 +0200

Alerting resources

Grafana alerting resources in Terraform include:

Terraform resource	What it manages	Key attributes
`grafana_rule_group`	A group of alert rules with shared evaluation interval	`name`, `folder_uid`, `interval_seconds`, `rule` blocks
`grafana_contact_point`	Notification destinations (email, Slack, PagerDuty, webhooks)	`name`, integration-specific blocks (`email`, `slack`, etc.)
`grafana_notification_policy`	Routing rules that match alerts to contact points	`contact_point`, `group_by`, `matcher` blocks
`grafana_mute_timing`	Time windows when notifications are suppressed	`name`, `intervals` with days, months, times
`grafana_message_template`	Reusable Go templates for notification content	`name`, `template`

An alert rule defines what to watch, what “bad” looks like, and how often to check. In other words, it tells Grafana when something is wrong. Contact points and notification policies tell it what to do about it. Together, these three resources form a complete alerting pipeline.

Alert rule group

In Terraform, alert rules live inside a rule group. A rule group is a named collection of related rules that share the same evaluation interval and folder.

Concept	What it is
Alert rule	The instructions you give Grafana: what to watch, what “bad” looks like, how often to check
Rule group	A named collection of related alert rules that share the same evaluation interval and folder
Evaluation interval	How often Grafana checks the rule’s condition
Condition	An expression that reduces query results to a single value and compares it against a threshold

Example: a CPU usage alert

This HCL block defines a rule group with one alert rule that fires when CPU usage exceeds 80%.

The data blocks form a pipeline: the first block (A) queries the metric, the second (B) reduces the result to a single value, and the third (C) compares that value against a threshold. Blocks B and C use datasource_uid = "__expr__", which is Grafana’s built-in server-side expression engine for transforming and evaluating query results without a separate data source. The condition field on the rule points to the final data block (C), which determines when the alert fires.

Labels on the rule, like severity = "warning", control how notifications are routed. The notification policy you’ll define in the next slide matches on these labels to decide which contact point receives the alert.

resource "grafana_rule_group" "cpu_alerts" {
  name             = "CPU alerts"
  folder_uid       = grafana_folder.alerts.uid
  interval_seconds = 60

  rule {
    name      = "High CPU usage"
    condition = "C"

    data {
      ref_id         = "A"
      datasource_uid = "prometheus"

      relative_time_range {
        from = 600
        to   = 0
      }

      model = jsonencode({
        expr = "100 - (avg(rate(node_cpu_seconds_total{mode=\"idle\"}[5m])) * 100)"
      })
    }

    data {
      ref_id         = "B"
      datasource_uid = "__expr__"

      relative_time_range {
        from = 0
        to   = 0
      }

      model = jsonencode({
        type       = "reduce"
        expression = "A"
        reducer    = "last"
      })
    }

    data {
      ref_id         = "C"
      datasource_uid = "__expr__"

      relative_time_range {
        from = 0
        to   = 0
      }

      model = jsonencode({
        type       = "threshold"
        expression = "B"
        conditions = [{
          evaluator = {
            type   = "gt"
            params = [80]
          }
        }]
      })
    }

    labels = {
      severity = "warning"
    }
  }
}

Alerting pipeline in Terraform

Wed, 15 Jul 2026 16:12:13 +0200

How the alerting pipeline works

The notification policy tree starts with a default route. All alerts enter at the top and flow down through nested policies until they match. The first matching policy determines which contact point receives the notification.

Labels on the alert rule, like severity = "warning", are what the notification policy matches against. This is why consistent labeling matters: it’s the contract between your alert rules and your notification routing.

Example: a Slack contact point

A contact point defines a notification destination. This example sends alerts to a Slack channel.

resource "grafana_contact_point" "slack_alerts" {
  name = "Slack alerts"

  slack {
    url     = var.slack_webhook_url
    title   = "{{ .CommonLabels.alertname }}"
    text    = "{{ .CommonAnnotations.description }}"
  }
}

Example: a notification policy

A notification policy routes alerts to contact points based on label matching. This example routes critical alerts to PagerDuty and everything else to Slack.

resource "grafana_notification_policy" "main" {
  contact_point = grafana_contact_point.slack_alerts.name
  group_by      = ["alertname"]

  policy {
    matcher {
      label = "severity"
      match = "="
      value = "critical"
    }
    contact_point = grafana_contact_point.pagerduty.name
  }
}

Deploy an alert rule learning path

Wed, 15 Jul 2026 16:12:13 +0200

Learning path: Deploy an alert rule with Terraform

The following table describes the steps you’ll work through in the learning path.

Step	What you’ll do	Outcome
1. Why Terraform?	Understand why Terraform is a natural fit for deploying alerting resources	Context for choosing Terraform over manual workflows
2. Create a service account	Set up API credentials in Grafana for Terraform	A service account token for authentication
3. Configure the provider	Declare the Grafana Terraform provider and authenticate	Terraform connected to your Grafana instance
4. Define a folder and an alert rule group	Create a folder to organize your alert rules, anda `grafana_rule_group` with a CPU usage alert	An organizational folder and alert rule ready to deploy in Grafana
5. Add a contact point	Define a `grafana_contact_point` for Slack or email	A notification destination configured
6. Add a notification policy	Route alerts to the contact point based on labels	A complete alerting pipeline
7. Run terraform plan	Preview what Terraform will create in Grafana	Confidence in what will change before applying
8. Apply and verify	Run `terraform apply` and confirm the resources appear in Grafana	A live alerting pipeline deployed from code

Before you start

Have these ready before you open the path:

A Grafana Cloud account or self-managed Grafana instance (version 12 or higher)
Terraform installed (version 1.0 or later)
A data source configured in Grafana (for example, Prometheus or Grafana TestData)
Admin or Editor permissions on your Grafana instance

Learning path

Deploy an alert rule with Terraform

Deploy a complete Grafana alerting pipeline using the Terraform provider.

17 min

Advanced

Docs & blog posts

Open in Grafana Cloud

Complete this learning path directly in your Grafana Cloud stack, or in the Grafana Play stack, with an interactive learning experience.

Open in Grafana Cloud Try in Grafana Play

View on website