Grafana Terraform provider on Grafana Labs

Create and manage a Grafana Cloud stack using Terraform

Tue, 18 Aug 2026 10:15:08 +0000

Create and manage a Grafana Cloud stack using Terraform

Learn how to add a data source, a dashboard, and a folder to a Grafana Cloud stack using Terraform.

Prerequisites

Before you begin, ensure you have the following:

A Grafana Cloud account, as shown in Get started
Terraform installed on your machine

Note
All of the following Terraform configuration files should be saved in the same directory.

Create a Cloud stack

Create a Terraform configuration file.

This Terraform configuration will create a Grafana Cloud stack and a second token needed for your Grafana instance.

Create a file named cloud-stack.tf and add the following:

terraform {
  required_providers {
    grafana = {
      source  = "grafana/grafana"
      version = ">= 2.9.0"
    }
  }
}
// Step 1: Create a stack
provider "grafana" {
  alias = "cloud"
  cloud_access_policy_token = "<cloud-access-token>"
}


resource "grafana_cloud_stack" "my_stack" {
  provider = grafana.cloud

  name               = "<stack-name>"
  slug               = "<stack-name>"
  region_slug        = "<region>" # Example "us","eu" etc
  delete_protection  = true
}

// Step 2: Create a service account and key for the stack
resource "grafana_cloud_stack_service_account" "cloud_sa" {
  provider   = grafana.cloud
  stack_slug = grafana_cloud_stack.my_stack.slug

  name        = "<service-account-name>"
  role        = "Admin"
  is_disabled = false
}

resource "grafana_cloud_stack_service_account_token" "cloud_sa" {
  provider   = grafana.cloud
  stack_slug = grafana_cloud_stack.my_stack.slug

  name               = "terraform serviceaccount key"
  service_account_id = grafana_cloud_stack_service_account.cloud_sa.id
}

// Step 3: Create resources within the stack
provider "grafana" {
  alias = "my_stack"

  url  = grafana_cloud_stack.my_stack.url
  auth = grafana_cloud_stack_service_account_token.cloud_sa.key
}
resource "grafana_folder" "my_folder" {
  provider = grafana.my_stack

  title = "Test Folder"
}

Replace the following field values:
- <cloud-access-token> with your Grafana Cloud Access Policy Token. To create a new one, refer to Grafana Cloud Access Policies. Add all stacks to the realms list. The scopes needed for the example are:
  - dashboards:read
  - orgs:read
  - stack-dashboards:read
  - stacks:read
  - dashboards:write
  - orgs:write
  - stack-dashboards:write
  - stacks:write
  - stack-service-accounts:write
  - dashboards:delete
  - stack-dashboards:delete
  - stacks:delete
- <stack-name> with the name of your stack.
- <region> with the region in which you want to create the stack. For example us, eu.
- <service-account-name> with a name for the serviceaccount that will be created to use for operations within the stack/instance.

The first provider block, grafana.cloud, uses the Cloud Access Policy Token from the Cloud Portal and is referenced as a parameter when creating the Cloud stack and the token in the Grafana instance to provide the necessary authentication.

The second provider block, grafana.my_stack, is referenced as a parameter when creating resources inside the Grafana instance.

Add a data source

This guide uses the InfluxDB data source. The required arguments for grafana_data_source (Resource) vary depending on the type of data source you select.

Create a file named datasource.tf and add the following:

resource "grafana_data_source" "<data-source-name>" {
  provider = grafana.my_stack

  type          = "influxdb"
  name          = "<data-source-name>"
  url           = "<data-source-url>"
  username      = "<username>"
  password      = "<password>"
  database_name = "<db-name>"
}

Replace the following field values:
- <data-source-name> with the name of the data source to be added in Grafana.
- <data-source-url> with URL of your data source.
- <username> with the username for authenticating with your data source.
- <password> with password for authenticating with your data source.
- <db-name> with name of your database.

Add a folder

This Terraform configuration creates a folder in your Grafana instance using grafana_folder (Resource).

Create a file named folder.tf and add the following:

resource "grafana_folder" "<folder-name>" {
  provider = grafana.my_stack

  title = "<folder-name>"
}

Replace the following field value:
- <folder-name> with a name for the folder.

Add a dashboard to the folder

This Terraform configuration creates a dashboard inside the folder created above in your Grafana instance using grafana_dashboard (Resource).

Create a file named dashboard.tf and add the following:

# Using a JSON file
resource "grafana_dashboard" "dashboard" {
  provider = grafana.my_stack

  config_json = file("<file-name>.json")
  folder = grafana_folder.<folder-name>.id
}

Replace the following field value:
- <file-name> with the name of the JSON file that has the source code for the dashboard.
The dashboard is represented by its JSON source code and referenced in the config_json parameter.

Apply the Terraform configuration

In a terminal, run the following commands from the directory where all of the configuration files are located.

Initialize a working directory containing Terraform configuration files.
shell
```
terraform init
```
Preview the changes that Terraform will make.
shell
```
terraform plan
```
Apply the configuration files.
shell
```
terraform apply
```

Validation

Once you apply the changes in the Terraform configurations, you should be able to verify the following:

The new Grafana stack is created and visible in the Cloud Portal
A service account key token is added in your Grafana instance. In the following image, the service account key token named “terraform serviceaccount key” was added by the grafana_cloud_stack_service_account_token (Resource).
A new data source (InfluxDB in this example) is visible in the grafana instance.
A new folder in Grafana. In the following image, a folder named “Demos” was added by the grafana_folder (Resource).
A new dashboard in the Grafana instance. In the following image a dashboard named “InfluxDB Cloud Demos” was created inside the “Demos” folder.

Summary

In this guide, you created a Grafana Cloud stack along with a data source, folder, and dashboard imported from a JSON file using Terraform.

To learn more about managing Grafana Cloud using Terraform, refer to the Grafana provider documentation.

Create and manage dashboards using Terraform and GitHub Actions

Tue, 18 Aug 2026 10:15:08 +0000

Create and manage dashboards using Terraform and GitHub Actions

Learn how to create and manage multiple dashboards represented as JSON source code for Grafana using Terraform and GitHub Actions.

Prerequisites

Before you begin, ensure you have the following:

A Grafana Cloud account, as shown in Get started
A GitHub repository

Add dashboards to a GitHub repository

This guide shows you how to add dashboards for ElasticSearch, InfluxDB, and AWS EC2. You can use different dashboards according to your configured data sources.

In your GitHub repository, create a folder named dashboards in the root directory.
In the dashboards folder create three sub-folders. For this guide, we will create three sub-folders named elasticsearch, influxdb, and aws.
Add dashboard JSON source code to each of the three sub-folders.

Terraform configuration for Grafana provider

This Terraform configuration configures the Grafana provider to provide necessary authentication when creating folders and dashboards in the Grafana instance.

Create a service account and token in the Grafana instance by following these steps:
1. Create a service account in Grafana
2. Add a token to a service account

Create a file named main.tf in the Git root directory and add the following code block:

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

provider "grafana" {
   alias = "cloud"

   url   = "<Grafana-instance-url>"
   auth  = "<Grafana-Service-Account-token>"
}

Replace the following field values:
- <Grafana-instance-url> with the URL of your Grafana instance, for example "https://my-stack.grafana.net/".
- <Grafana-Service-Account-token> with a Service Account token from the Grafana instance.

Terraform configuration for folders

This Terraform configuration creates three folders named ElasticSearch, InfluxDB and AWS in the Grafana instance using grafana_folder (Resource).

Create a file named folders.tf in the Git root directory and add the following code block:

resource "grafana_folder" "ElasticSearch" {
  provider = grafana.cloud

  title = "ElasticSearch"
}

resource "grafana_folder" "InfluxDB" {
  provider = grafana.cloud

  title = "InfluxDB"
}

resource "grafana_folder" "AWS" {
  provider = grafana.cloud

  title = "AWS"
}

Terraform configuration for dashboards

This Terraform configuration iterates through the JSON files in the three folders (elasticsearch, influxdb and aws) you created in the GitHub repository and adds them to the respective folders in the Grafana instance using a Grafana dashboard resource. Available resources include:

grafana_dashboard (Resource).
For Kubernetes-style dashboards in Grafana v13 or later, use the appropriate resource depending on your dashboard’s Kubernetes version. Refer to Grafana resources for details on the available resources, such as grafana_apps_dashboard_dashboard_v1beta1, grafana_apps_dashboard_dashboard_v1, or grafana_apps_dashboard_dashboard_v2.

For example, the dashboard represented as JSON source code in the elasticsearch folder in the GitHub repository will be created in the ElasticSearch folder in the Grafana instance.

Create a file named dashboards.tf in the Git root directory and add the following code block:

resource "grafana_dashboard" "elasticsearch" {
  provider = grafana.cloud

  for_each    = fileset("${path.module}/dashboards/elasticsearch", "*.json")
  config_json = file("${path.module}/dashboards/elasticsearch/${each.key}")
  folder      = grafana_folder.ElasticSearch.id
}

resource "grafana_dashboard" "influxdb" {
  provider = grafana.cloud

  for_each    = fileset("${path.module}/dashboards/influxdb", "*.json")
  config_json = file("${path.module}/dashboards/influxdb/${each.key}")
  folder      = grafana_folder.InfluxDB.id
}

resource "grafana_dashboard" "aws" {
  provider = grafana.cloud

  for_each    = fileset("${path.module}/dashboards/aws", "*.json")
  config_json = file("${path.module}/dashboards/aws/${each.key}")
  folder      = grafana_folder.AWS.id
}

GitHub workflow for managing dashboards using Terraform

This GitHub workflow consists of the following steps:

Using the actions/checkout@v3 action, The GitHub repository is checked out so that the GitHub workflow can access it.
The Terraform CLI is installed on the GitHub runner using the hashicorp/setup-terraform@v1 action.
terraform init is run as a bash command in the GitHub runner to initialize a working directory containing Terraform configuration files.
terraform fmt -check is run as a bash command in the GitHub runner to check if the Terraform configuration files are properly formatted. If the Terraform configuration files are not properly formatted, the workflow will fail at this step.
terraform plan is run as a bash command in the GitHub runner to preview the changes that Terraform will make.
Using mshick/add-pr-comment@v1 action, the preview from Terraform plan is posted as a comment on the pull request. This helps in reviewing the changes that Terraform will make before the pull request is merged.
terraform apply -auto-approve is run as a bash command in the GitHub runner to apply the Terraform configuration files. -auto-approve flag is added to the command to skip interactive approval of plan before applying and make the workflow automated. This step is run only when changes are committed to main branch. When a pull request is merged, the merge action creates a commit to the main branch which triggers the terraform apply -auto-approve step to execute.

In your GitHub repository, create a folder named .github in the root directory .
In the .github folder create a sub-folder named workflows.

To add the GitHub workflow to your GitHub repository, create a file named terraform.yml in the workflows directory and add the following code block:

name: Terraform

on:
  push:
    branches:
      - 'main'
  pull_request:

jobs:
  terraform:
    runs-on: ubuntu-latest

    steps:
      # Checkout the repository to the GitHub Actions runner
      - name: Checkout
        uses: actions/checkout@v3

      # Install the latest version of Terraform CLI
      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v1

      # Initialize a new or existing Terraform working directory by creating initial files, loading any remote state, downloading modules, etc.
      - name: Terraform Init
        run: terraform init

      # Checks that all Terraform configuration files adhere to a canonical format
      - name: Terraform Format
        run: terraform fmt -check

      # Previews the changes that Terraform will make
      - name: Plan Terraform
        id: plan
        continue-on-error: true
        run: terraform plan -input=false -no-color

      # Post the preview (terraform plan) from the previous step as a GitHub pull request comment
      - name: Post Plan to GitHub PR
        if: github.ref != 'refs/heads/main'
        uses: mshick/add-pr-comment@v1
        with:
          repo-token: ${{ secrets.GITHUB_TOKEN }}
          repo-token-user-login: 'github-actions[bot]'
          message: |
            Applying:

            ```
            ${{ steps.plan.outputs.stdout }}
            ```

      # Applies the terraform configuration files when the branch is `main`
      - name: Apply Terraform
        if: github.ref == 'refs/heads/main'
        id: apply
        continue-on-error: true
        run: |
          terraform apply -auto-approve

Commit the changes made to the terraform.yml in the previous step to the main branch in your GitHub repository. Once the changes are committed, The GitHub workflow you created should start to run automatically as the workflow we defined in the previous step runs when a pull request is created or when changes are committed to main branch.

Managing the Terraform state

If you are not using a Terraform backend to store the .tfstate file, add the following code block to the end of the GitHub workflow file to make sure the Terraform state file is stored in Git.

- name: commit the terraform state
  if: github.ref == 'refs/heads/main'
  uses: stefanzweifel/git-auto-commit-action@v4
  with:
    commit_message: Updating Terraform state
    file_pattern: terraform.tfstate

When you run terraform apply, Terraform automatically manages and updates the terraform.tfstate file to store state about your infrastructure and configuration. This step uses the stefanzweifel/git-auto-commit-action@v4 action to auto-commit the terraform.tfstate file for changes made by running the terraform apply step.

Note
The Terraform state file (terraform.tfstate) shouldn’t be stored in Git to avoid leakage of sensitive data. Instead, store Terraform state files using a remote backend like AWS S3 with proper RBAC. For more information, refer to Terraform state.

Validation

Once the GitHub workflow run is successful, you should be able to verify the following:

ElasticSearch, InfluxDB and AWS folders are created in the Grafana instance.
Dashboard represented as JSON source code from elasticsearch folder in GitHub are added under the ElasticSearch folder in the Grafana instance.
Dashboard source code from the influxdb folder in GitHub is added under the InfluxDB folder in the Grafana instance.
Dashboards from aws folder in GitHub are added under the AWS folder in the Grafana instance.

Summary

In this guide, you created a GitHub workflow using Terraform to manage dashboard source code. Using this workflow, the dashboards in the Grafana instance are synchronized with the JSON source code files for dashboards in GitHub.

To learn more about managing Grafana Cloud using Terraform, refer to the Grafana provider documentation.

Manage Grafana IRM in Grafana Cloud using Terraform

Tue, 18 Aug 2026 10:15:08 +0000

Manage Grafana IRM in Grafana Cloud using Terraform

Learn how to use Terraform to manage Grafana IRM resources. This guide shows you how to connect an integration, configure escalation policies, and add on-call schedules using Terraform.

To illustrate the use of IRM across multiple teams, this guide features examples with two teams: Devs and SREs. Additionally, it includes the necessary steps to configure Slack for IRM.

Note
Grafana IRM supports Terraform-based configuration for a limited set of resources, primarily those related to OnCall functionality. These resources use the grafana_oncall_ naming convention in Terraform. Additional IRM components are not yet configurable via Terraform.

Before you begin

Before you begin, ensure you have the following:

A Grafana Cloud account, as shown in Get started
Terraform installed on your machine
Administrator permissions in your Grafana instance
(Optional) Administrator permissions in your Slack workspace, if you plan to integrate Slack with Grafana IRM

Note
All of the following Terraform configuration files should be saved in the same directory.

Connect Slack to Grafana IRM

Before including Slack settings in your Terraform setup, you must first configure the Slack integration with Grafana IRM.

To connect your Slack workspace to Grafana IRM, refer to the Slack integration for Grafana IRM documentation.

Configure the Grafana provider

This Terraform configuration sets up the Grafana provider to provide necessary authentication when managing resources for Grafana IRM.

You can reuse a similar setup to the one described in Creating and managing a Grafana Cloud stack using Terraform to set up a service account and a token.

Create a Service account and token in Grafana. To create a new one, refer to Service account tokens.

Create a file named main.tf and add the following:

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

provider "grafana" {
  alias = "oncall"

  url  = "<Stack-URL>"
  auth = "<Service-account-token>"
  oncall_url = "<OnCall-URL>"
}

Replace the following field values:
- <Stack-URL> with the URL of your Grafana stack
- <Service-account-token> with the service account token that you created
- <OnCall-URL> with the API URL found on the Admin & API tab of the IRM Settings page

Note
If the service account has the right permissions, this provider setup also allows you to manage other Grafana resources.

Authentication via OnCall API tokens (deprecated)

OnCall API tokens are being deprecated. While existing tokens will continue to work, we recommend using Grafana Cloud service account tokens for all new API authentication.

To use an existing OnCall API token:

Log into your Grafana Cloud instance
Select Alerts & IRM > IRM
Click Settings, and then select Admin & API
Locate the Grafana IRM API section
View, copy or revoke existing OnCall API tokens

Create a file named main.tf and add the following:

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

provider "grafana" {
  alias = "oncall"

  oncall_access_token = "<OnCall-API-Token>"
  oncall_url = "<OnCall-URL>"
}

Replace the following field values:
- <OnCall-API-Token> with your existing OnCall API Token
- <OnCall-URL> with the API URL found on the Admin & API tab of the IRM Settings page

Add on-call schedules

This Terraform configuration sets up two on-call schedules, SREs and Devs, using the grafana_oncall_schedule resource to define the schedules within Grafana IRM. Additionally, this configuration includes Slack channels to receive notifications for the on-call schedules of each team.

To learn more about managing on-call schedules, refer to the On-call schedules documentation.

Create two new calendars in your calendar service, one for Devs and one for SREs
Locate and save the secret iCal URLs. For example, in a Google calendar, these URLs can be found in Settings > Settings for my calendars > Integrate calendar

Create a file named schedule.tf and add the following:

# Name of the Slack channel to notify about on-call schedules for Devs
data "grafana_oncall_slack_channel" "Devs" {
  provider = grafana.oncall

  name = "<Devs-channel-name>"
}

# Name of the Slack channel to notify about on-call schedules for SREs
data "grafana_oncall_slack_channel" "SREs" {
  provider = grafana.oncall

  name = "<SREs-channel-name>"
}

resource "grafana_oncall_schedule" "schedule_Devs" {
  provider = grafana.oncall

  name             = "Devs"
  type             = "ical"
  ical_url_primary = "<secret-iCal-URL-for-devs-calendar>"
  slack {
    channel_id = data.grafana_oncall_slack_channel.Devs.slack_id
  }
}

resource "grafana_oncall_schedule" "schedule_SREs" {
  provider = grafana.oncall

  name             = "SREs"
  type             = "ical"
  ical_url_primary = "<secret-iCal-URL-for-SREs-calendar>"
  slack {
    channel_id = data.grafana_oncall_slack_channel.SREs.slack_id
  }
}

Replace the following field values:
- <Devs-channel-name> with name of the Slack channel to notify about on-call schedules for Devs
- <SREs-channel-name> with name of the Slack channel to notify about on-call schedules for SREs
- <secret-iCal-URL-for-devs-calendar> with the secret iCal URL created in the first step for Devs Calendar
- <secret-iCal-URL-for-SREs-calendar> with the secret iCal URL created in the first step for SREs Calendar

Add escalation chains

This Terraform configuration creates two escalation chains named SREs and Devs in Grafana IRM using the grafana_oncall_escalation_chain (Resource). The configuration also adds the following three steps to each escalation chain using the grafana_oncall_escalation (Resource):

Notify users from on-call schedule
Wait for 5 minutes
Notify default Slack channel

Create a file named escalation-devs.tf and add the following:

resource "grafana_oncall_escalation_chain" "Devs" {
  provider = grafana.oncall

  name = "Devs"
}

// Notify users from on-call schedule
resource "grafana_oncall_escalation" "notify_schedule_step_Devs" {
  provider = grafana.oncall

  escalation_chain_id          = grafana_oncall_escalation_chain.Devs.id
  type                         = "notify_on_call_from_schedule"
  notify_on_call_from_schedule = grafana_oncall_schedule.schedule_Devs.id
  position                     = 0
}

// Wait step for 5 Minutes
resource "grafana_oncall_escalation" "wait_step_Devs" {
  provider = grafana.oncall

  escalation_chain_id = grafana_oncall_escalation_chain.Devs.id
  type                = "wait"
  duration            = 300
  position            = 1
}

// Notify default Slack channel step
resource "grafana_oncall_escalation" "notify_step_Devs" {
  provider = grafana.oncall

  escalation_chain_id = grafana_oncall_escalation_chain.Devs.id
  type                = "notify_whole_channel"
  important           = true
  position            = 2
}

Create a file named escalation-sre.tf and add the following:

resource "grafana_oncall_escalation_chain" "SREs" {
  provider = grafana.oncall

  name = "SREs"
}

// Notify users from on-call schedule
resource "grafana_oncall_escalation" "notify_schedule_step_SREs" {
  provider = grafana.oncall

  escalation_chain_id          = grafana_oncall_escalation_chain.SREs.id
  type                         = "notify_on_call_from_schedule"
  notify_on_call_from_schedule = grafana_oncall_schedule.schedule_SREs.id
  position                     = 0
}

// Wait step for 5 Minutes
resource "grafana_oncall_escalation" "wait_step_SREs" {
  provider = grafana.oncall

  escalation_chain_id = grafana_oncall_escalation_chain.SREs.id
  type                = "wait"
  duration            = 300
  position            = 1
}

// Notify default Slack channel step
resource "grafana_oncall_escalation" "notify_step_SREs" {
  provider = grafana.oncall

  escalation_chain_id = grafana_oncall_escalation_chain.SREs.id
  type                = "notify_whole_channel"
  important           = true
  position            = 2
}

Connect an integration to Grafana IRM

This Terraform configuration connects Alertmanager to Grafana IRM using the grafana_oncall_integration (Resource). It also adds the Devs escalation chain as the default route for alerts.

Create a file named integrations.tf and add the following:

resource "grafana_oncall_integration" "AlertManager" {
  provider = grafana.oncall

  name = "AlertManager"
  type = "alertmanager"
  default_route {
    escalation_chain_id = grafana_oncall_escalation_chain.Devs.id
  }
}

To configure Alertmanager, refer to the Alertmanager integration for Grafana OnCall documentation.

Set up a route to configure escalation behavior for alert group notifications

This Terraform configuration sets up a route to the Alertmanager integration using the grafana_oncall_route (Resource). This route ensures that notifications for alerts with \"namespace\" *: *\"ops-.*\" in the payload are escalated to the SREs escalation chain.

Create a file named routes.tf and add the following:

resource "grafana_oncall_route" "route_SREs" {
  provider = grafana.oncall

  integration_id      = grafana_oncall_integration.AlertManager.id
  escalation_chain_id = grafana_oncall_escalation_chain.SREs.id
  routing_regex       = "\"namespace\" *: *\"ops-.*\""
  position            = 0
}

Apply the Terraform configuration

In a terminal, run the following commands from the directory where all of the configuration files are located.

Initialize a working directory containing Terraform configuration files.
shell
```
terraform init
```
Preview the changes that Terraform will make.
shell
```
terraform plan
```
Apply the configuration files.
shell
```
terraform apply
```

Validation

After you apply the changes in the Terraform configurations, you can verify the following:

Two new Schedules named Devs and SREs are created in Grafana IRM:
New Escalation chain named SREs is created in Grafana IRM:
New Escalation chain named Devs is created in Grafana IRM:
The Alertmanager integration is added and configured with escalation policies:

Summary

In this guide, you learned how to use Terraform to manage Grafana IRM by connecting an integration, configuring escalation policies, and setting up on-call schedules.

To learn more about managing Grafana Cloud using Terraform, refer to the Grafana provider documentation.

Manage Knowledge Graph in Grafana Cloud using Terraform

Tue, 18 Aug 2026 10:15:08 +0000

Manage Knowledge Graph using Terraform

Use Terraform to manage Grafana Cloud Knowledge Graph resources as code. Configure the Knowledge Graph stack, notification alerts, suppressed assertions, custom model rules, log configurations, and threshold configurations using infrastructure as code best practices.

Overview

Terraform enables you to manage Grafana Cloud Knowledge Graph resources using infrastructure as code. With Terraform, you can define, version control, and deploy Knowledge Graph configurations including stack onboarding, alert rules, suppression policies, entity models, log, trace, and profile correlations, and thresholds.

Explore

Manage secrets in Grafana Cloud using Terraform

Tue, 06 Oct 2026 19:16:37 +0000

Manage secrets in Grafana Cloud using Terraform

Use the Terraform Grafana provider to create and manage secure values in Grafana Secrets Management as code. With Terraform, you keep secrets such as API keys, tokens, passwords, and certificates in version-controlled, declarative infrastructure alongside the rest of your Grafana stack.

This guide covers secure values, which you manage with the grafana_apps_secret_securevalue_v1beta1 resource. By default, Grafana stores secure values in the built-in system keeper, which requires no setup. If you configure an additional keeper and set it as the active keeper for your namespace, Grafana stores new secure values there automatically. For more information, refer to Activate and use the keeper. To store secure values in an external secret manager instead, provision a keeper.

To create and manage secure values with Terraform, you complete the following tasks:

Create a service account token to authenticate the Terraform provider.
Configure the Grafana provider.
Define one or more secure values.
Run terraform apply to provision your secure values.

Before you begin

To provision secure values with Terraform, you need the following:

A Grafana Cloud instance that you can reach from the machine that runs Terraform.
Permission to create service account tokens.

You also need the following tools at the minimum supported versions:

Tool	Minimum version
Terraform CLI	1.11, for write-only arguments
`grafana/grafana` Terraform provider	4.26.0

If you don’t have the Terraform CLI, refer to the Terraform install documentation. The grafana/grafana provider downloads automatically when you run terraform init in Provision the secure value with Terraform.

Note
All of the following Terraform configuration files should be saved in the same directory.

Create a service account token

Terraform authenticates against Grafana with a service account token.

To create a service account and token, follow these steps:

Create a service account and token in Grafana. To create them, refer to Service account tokens. You can also refer to Create and manage a Grafana Cloud stack using Terraform to set up a service account and token.
Make sure the service account has the role-based access control (RBAC) actions needed to manage secure values:
- secret.securevalues:create
- secret.securevalues:read
- secret.securevalues:write
- secret.securevalues:delete
If you also provision a keeper (refer to Provision a keeper), the service account also needs the keeper actions, which cover activating a keeper:
- secret.keepers:create
- secret.keepers:read
- secret.keepers:write
- secret.keepers:delete
Copy the token and store it securely, because you can’t view it again after you leave the page.

Configure the Grafana provider

In your Terraform working directory, create a main.tf file:

terraform {
  required_version = ">= 1.11.0"

  required_providers {
    grafana = {
      source  = "grafana/grafana"
      version = ">= 4.26.0"
    }
  }
}

variable "grafana_auth" {
  type      = string
  sensitive = true
}

provider "grafana" {
  url  = "<GRAFANA_URL>"
  auth = var.grafana_auth

  # Required for app-platform resources, including secure values.
  stack_id = <STACK_ID>
}

Replace the placeholders as follows:

<GRAFANA_URL> is the URL of your Grafana instance, for example https://my-org.grafana.net.
<STACK_ID> is your numeric Grafana Cloud stack ID, for example 123456.

To find your stack ID, open the Grafana Cloud Portal, select your stack, and read the numeric Instance ID. That value is your stack_id.

You can also retrieve it with a GET request to https://grafana.com/api/orgs/<ORG_SLUG>/instances, where <ORG_SLUG> is your Grafana Cloud organization name. The numeric id field in the response is the stack ID. This Cloud API endpoint authenticates with a Cloud Access Policy token, which is separate from the service account token that Terraform uses.

Provide each input variable through a matching environment variable that follows the Terraform TF_VAR_<variable_name> naming convention. The part after TF_VAR_ is the name of the variable in your configuration: Terraform maps TF_VAR_grafana_auth to the grafana_auth variable, TF_VAR_external_api_key to external_api_key, and so on. You can also use a secrets manager or a terraform.tfvars file. Don’t set variables in a file that you commit.

For other authentication options, refer to the Grafana provider documentation. For end-to-end stack management, refer to Create and manage a Grafana Cloud stack using Terraform.

Define a secure value

The following example stores an API key as a secure value and authorizes Synthetic Monitoring to decrypt it. Add it to main.tf, or to any other .tf file in the same working directory. Terraform loads all .tf files in the directory together.

variable "external_api_key" {
  type      = string
  sensitive = true
  ephemeral = true # Keeps the value out of state and plan files.
}

resource "grafana_apps_secret_securevalue_v1beta1" "external_api_key" {
  metadata {
    uid = "external-api-key" # The secure value's name.
  }

  spec {
    description = "External API key"
    value       = var.external_api_key
    decrypters  = ["synthetic-monitoring"]
  }
}

Keep the following points in mind for this example:

metadata.uid is the secure value’s name in Grafana. The resource also exposes a separate, read-only metadata.uuid, which is the Grafana-generated identifier rather than the name.
spec.description is required and limited to 25 characters. Longer values fail at plan with a Terraform length validation error.
spec.value is a write-only argument that requires Terraform 1.11 or later. Terraform sends the plaintext to Grafana on apply, but never writes it to state, plan output, or any other on-disk artifact. Combine it with an ephemeral, sensitive variable, as in the preceding example, so the value also stays out of terraform plan output.
You don’t pass a namespace. The provider derives it from stack_id.
You don’t pass a keeper name. Grafana stores the value in whichever keeper is the active keeper for your namespace, which is the system keeper by default.

Schema reference

The full schema is on the Terraform Registry. The following tables describe the fields you use for secure values.

The metadata block contains the following fields:

Field	Required	Description
`uid`	Yes	The secure value’s name. Up to 253 characters, DNS-compatible, and immutable.
`folder_uid`	No	Not used for secure values. Leave it unset.
`uuid`, `version`, `url`, `annotations`	No	Read-only. Grafana populates these fields.

The spec block contains the following fields:

Field	Required	Description
`description`	Yes, enforced server-side	1 to 25 characters.
`value`	Conditional	Plaintext secret value, 1 to 24,576 bytes. Sensitive and write-only in Terraform 1.11 or later. Sent to Grafana on apply but never written to state or plan files. Set exactly one of `value` or `ref`.
`ref`	Conditional	Reference to a secret already stored in a third-party keeper, 1 to 1,024 characters. Valid only when the active keeper for the namespace isn’t the system keeper. Set exactly one of `value` or `ref`.
`decrypters`	No	List of services permitted to decrypt this secure value. Up to 64 unique entries. Each entry must be a valid Kubernetes label value: letters, numbers, and the characters `.`, `-`, and `_`, with no slashes or spaces. For more information, refer to Decrypters.
`value_hash`	Computed	Read-only SHA-256 hash of the stored value. The provider uses it to detect rotation. Don’t set it yourself.

The options block is optional and contains the following fields:

Field	Required	Description
`manager_identity`	No	Overrides the manager identity stamped on this resource. The default is `grafana-terraform-provider`. Useful when multiple Terraform workspaces manage resources in the same Grafana instance.
`overwrite`	No	Set to `true` to overwrite an existing resource with the same UID when applicable.

At the top level, the resource exposes a read-only id field, which Grafana derives from the secure value’s UUID.

Decrypters

The decrypters list controls which Grafana services can decrypt a secret. If a service isn’t in the list, it can’t read the plaintext value, even if it has access to the secure value’s metadata. An empty or unset list means no service can decrypt the value.

Grafana supports the following decrypters:

Decrypter	Consumer
`k6-cloud`	Grafana Cloud k6
`synthetic-monitoring`	Synthetic Monitoring checks

Grant the minimum set of decrypters required for your use case.

Provision the secure value with Terraform

To apply the configuration, follow these steps:

Initialize the working directory. This downloads the Grafana provider.
shell
```
terraform init
```
Set the environment variables, then preview and apply the changes:
shell
```
export TF_VAR_grafana_auth='<TOKEN>'
export TF_VAR_external_api_key='<SECRET>'
terraform plan
terraform apply
```
Replace the placeholders as follows:
- <TOKEN> is the service account token you created in Create a service account token.
- <SECRET> is the plaintext secret value that Terraform stores as the secure value.
This keeps secrets out of Terraform files. If your shell writes history, prefer a secure secret-injection flow, such as CI/CD secrets, a secret manager, or a nested shell with history disabled.

Terraform shows the execution plan and asks for confirmation:
console
```
Plan: 1 to add, 0 to change, 0 to destroy.

Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value:
```
After you confirm, Terraform creates the secure value:
console
```
Apply complete! Resources: 1 added, 0 changed, 0 destroyed.
```

If a secure value with the same metadata.uid already exists in the namespace, for example from a previous apply or one created outside Terraform, the apply fails with HTTP 409 - AlreadyExists. To bring the existing secure value under Terraform management instead of recreating it, import it. To replace it on apply, set overwrite = true in the resource’s options block.

Verify that the plaintext stays out of state

Because spec.value is write-only, Terraform never writes the plaintext to state. It writes only the value_hash. To confirm this, search your local state file for the plaintext:

grep -c '<SECRET_VALUE>' terraform.tfstate

Replace <SECRET_VALUE> with the plaintext secret you provisioned. The search returns no matches:

The stored spec shows value as null and retains only the hash:

"spec": {
  "decrypters": ["synthetic-monitoring"],
  "description": "External API key",
  "ref": null,
  "value": null,
  "value_hash": "65f087ba121c13dec3fa0cb7697d4309ed5e624ba528a758bb9071bee220825a"
}

To verify the result, open Administration > Secrets Management in Grafana, or call the Secrets Management HTTP API directly. The namespace is stacks-<STACK_ID>:

curl -H "Authorization: Bearer <TOKEN>" \
  "<GRAFANA_URL>/apis/secret.grafana.app/v1beta1/namespaces/stacks-<STACK_ID>/securevalues/external-api-key"

The response includes the secure value’s metadata, its spec with description and decrypters, and the keeper that stores it. It never includes the plaintext value:

{
  "kind": "SecureValue",
  "apiVersion": "secret.grafana.app/v1beta1",
  "metadata": {
    "name": "external-api-key",
    "namespace": "stacks-<STACK_ID>",
    "annotations": {
      "grafana.app/managedBy": "terraform",
      "grafana.app/managerId": "grafana-terraform-provider"
    }
  },
  "spec": {
    "description": "External API key",
    "decrypters": ["synthetic-monitoring"]
  },
  "status": {
    "version": 1,
    "keeper": "system"
  }
}

There is no value field in the response. The API doesn’t return decrypted secret contents.

Rotate a secure value

To rotate a secret, change the value, or the variable that feeds it, and run terraform apply again.

The provider computes a SHA-256 hash of your configured spec.value at plan time and stores it in value_hash. When the hash changes, Terraform plans an update. When the hash doesn’t change, Terraform plans no change. This lets you rotate secrets without storing plaintext in state.

resource "grafana_apps_secret_securevalue_v1beta1" "external_api_key" {
  metadata {
    uid = "external-api-key"
  }

  spec {
    description = "External API key"
    value       = var.external_api_key # Supply the new value here.
    decrypters  = ["synthetic-monitoring"]
  }
}

When the value changes, the recomputed value_hash drives an in-place update:

  ~ spec {
      ~ value_hash = (sensitive value)
    }

Plan: 0 to add, 1 to change, 0 to destroy.

If you apply again without changing the value, the hash matches and Terraform plans no change:

No changes. Your infrastructure matches the configuration.

Rotation considerations

Keep the following points in mind when you rotate secure values:

value is write-only. The Grafana API never returns the plaintext, and the provider never reads it back. Only value_hash is stored in state.
Out-of-band value changes aren’t directly detectable. Because the plaintext is write-only, Terraform can’t read the current secret contents from Grafana. Keep Terraform as your source of truth for rotations.
You can’t switch a secure value between value and ref after creation. The API rejects updates that try to change mode. To change mode, destroy and recreate the resource.
metadata.uid is immutable. Changing it forces Terraform to destroy and recreate the secure value.
decrypters ordering is significant in Terraform. Keep a stable order in your configuration to avoid noisy plans.
An update is a full replace with PUT, not a patch. Always provide description and decrypters together with value or ref on update. If you omit them, the new spec replaces the old one in full.

Handle the secret value safely

Warning
Never check plaintext secret values into Terraform configuration.

Instead, use one of the following approaches:

A sensitive or ephemeral Terraform variable populated from a TF_VAR_* environment variable.
A CI/CD secret injected at apply time.
A dedicated secret store, such as HashiCorp Vault or AWS Secrets Manager, referenced from Terraform with the appropriate provider data source.

Import an existing secure value

The grafana_apps_secret_securevalue_v1beta1 resource supports import. The import ID is the secure value name, which is the value of metadata.uid:

terraform import grafana_apps_secret_securevalue_v1beta1.external_api_key external-api-key

After you import a secure value, keep the following points in mind:

spec.value is still write-only, and Terraform never imports it into state.
For value-backed secure values, set spec.value in configuration before you apply. The first managed apply sets or rotates the value to whatever you configure.
For reference-backed secure values, set spec.ref in configuration to match the existing reference.
Because you must set exactly one of value or ref, your configuration must include one of them after import.

Provision a keeper

A keeper defines where Grafana stores the encrypted material for your secure values. By default, Grafana uses the built-in system keeper, which encrypts values at rest in the Grafana database and requires no setup.

To store secrets in an external secret manager instead, provision a keeper with the grafana_apps_secret_keeper_v1beta1 resource. Grafana currently supports AWS Secrets Manager as a keeper.

Grafana connects to AWS Secrets Manager through cross-account role assumption with AWS Security Token Service, and never stores your AWS credentials. You create an AWS Identity and Access Management (IAM) role in your AWS account that Grafana can assume, and the keeper references that role.

Keeper requirements

In addition to the requirements for secure values, you need the following:

An AWS account with AWS Secrets Manager enabled in your target region.
An IAM role named exactly grafana-secrets-manager that Grafana can assume, along with its role ARN and external ID. Grafana can assume only a role with that name. For the IAM role and trust policy that the role requires, refer to Configure an AWS Secrets Manager keeper.

Define a keeper

The following example provisions an AWS Secrets Manager keeper. Add it to main.tf, or to any other .tf file in the same working directory.

resource "grafana_apps_secret_keeper_v1beta1" "aws_secrets_manager" {
  metadata {
    uid = "aws-secrets-manager" # The keeper's name.
  }

  spec {
    description = "AWS Secrets Manager keeper"

    aws {
      region = "<REGION>"

      assume_role {
        assume_role_arn = "arn:aws:iam::<ACCOUNT_ID>:role/grafana-secrets-manager"
        external_id     = "<EXTERNAL_ID>"
      }
    }
  }
}

Replace the placeholders as follows:

<REGION> is the AWS region that hosts your secrets, for example us-east-1.
<ACCOUNT_ID> is the ID of the AWS account that hosts your secrets.
<EXTERNAL_ID> is the external ID that your IAM role’s trust policy requires.

The role name in assume_role_arn must be grafana-secrets-manager. Grafana can’t assume a role with any other name.

Apply the keeper with the same terraform apply workflow you use for a secure value, described in Provision the secure value with Terraform. Unlike a secure value, a keeper has no secret value, so it needs no ephemeral variable of its own: TF_VAR_grafana_auth for the provider is the only variable you export. Creating a keeper doesn’t make it active, so don’t create secure values in the same apply until you add the activation resource in Activate and use the keeper and make new secrets depend on it.

Keeper schema reference

The full schema is on the Terraform Registry. The following tables describe the fields you use for a keeper.

The metadata block contains the following fields:

Field	Required	Description
`uid`	Yes	The keeper’s name. Up to 253 characters, DNS-compatible, and immutable.

The spec block contains the following fields:

Field	Required	Description
`description`	Yes	Short description for the keeper, 1 to 253 characters.
`aws`	Yes	AWS Secrets Manager configuration. Grafana currently supports only AWS, so this block is required. For the fields, refer to the following `aws` table.

The aws block contains the following fields:

Field	Required	Description
`region`	Yes	AWS region that hosts your secrets, for example `us-east-1`.
`assume_role`	Yes	Role that Grafana assumes to access AWS Secrets Manager. Required for AWS. `assume_role_arn` and `external_id` are both required.

The assume_role block contains the following fields:

Field	Required	Description
`assume_role_arn`	Yes	ARN of the IAM role that Grafana assumes.
`external_id`	Yes	External ID that the IAM role’s trust policy requires.

At the top level, the resource exposes a read-only active status that’s true when the keeper is the active keeper for the namespace.

Activate and use the keeper

Creating a keeper with Terraform doesn’t make it active. Each namespace has at most one active keeper, which determines where Grafana stores new secure values.

To set a keeper as active, use the grafana_apps_secret_keeper_activation_v1beta1 resource and reference the keeper’s uid:

resource "grafana_apps_secret_keeper_activation_v1beta1" "aws_secrets_manager" {
  metadata {
    uid = grafana_apps_secret_keeper_v1beta1.aws_secrets_manager.metadata.uid
  }
}

The activation resource already depends on the keeper because it references the keeper’s uid. Any secure value that should use this keeper must depend on the activation, otherwise Terraform can create the secret while the system keeper is still active:

resource "grafana_apps_secret_securevalue_v1beta1" "external_api_key" {
  metadata {
    uid = "external-api-key"
  }

  spec {
    description = "External API key"
    value       = var.external_api_key
    decrypters  = ["synthetic-monitoring"]
  }

  depends_on = [grafana_apps_secret_keeper_activation_v1beta1.aws_secrets_manager]
}

Keep the following points in mind for this resource:

Because a namespace has only one active keeper, applying an activation for a different keeper switches which keeper is active.
Running terraform destroy on the activation resource reverts the namespace to the built-in system keeper. Destroying the keeper resource doesn’t deactivate it first; destroy the activation resource as well.

You can also set the active keeper outside Terraform, in the Grafana UI under Administration > Secrets Management.

After the keeper is active, Grafana routes new secure values to it automatically. A value-backed secure value like the one in Define a secure value needs no field changes to use the active keeper, but it still needs depends_on if you create it in the same configuration as the activation. Destroying a value-backed secure value that lives in AWS Secrets Manager deletes the AWS secret immediately, with no recovery window.

To reference a secret that already exists in AWS Secrets Manager instead of sending a new value, use ref in place of value. Set ref to the AWS secret name or the full ARN, not a path inside Grafana:

resource "grafana_apps_secret_securevalue_v1beta1" "db_password" {
  metadata {
    uid = "db-password"
  }

  spec {
    description = "Production DB password"
    ref         = "grafana-secrets-manager/stacks-<STACK_ID>/db-password/1"
    decrypters  = ["synthetic-monitoring"]
  }

  depends_on = [grafana_apps_secret_keeper_activation_v1beta1.aws_secrets_manager]
}

Replace <STACK_ID> with the same numeric stack ID you set on the provider. You can also set ref to the full secret ARN, for example arn:aws:secretsmanager:<REGION>:<ACCOUNT_ID>:secret:grafana-secrets-manager/stacks-<STACK_ID>/db-password/1-AbCdEf.

If you use ref while the system keeper is active, the API returns the following error:

tried to create secure value using reference with system keeper, references can only be used with 3rd party keepers

Summary

In this guide, you created a service account token, configured the Grafana provider, and provisioned a secure value with Terraform. You also learned how to rotate and import secure values, and how to provision and activate a keeper to store secrets in an external secret manager.

To learn more about managing Grafana Cloud using Terraform, refer to the Grafana provider documentation.

Next steps

For the full secure value schema and more examples, refer to grafana_apps_secret_securevalue_v1beta1 on the Terraform Registry.
For the full keeper schema, refer to grafana_apps_secret_keeper_v1beta1 on the Terraform Registry.
For the keeper activation resource, refer to grafana_apps_secret_keeper_activation_v1beta1 on the Terraform Registry.
For concepts, permissions, and limits, refer to Manage secrets.
For the underlying HTTP API, refer to the Secrets Management API.
For more about write-only arguments, refer to Ephemeral values in the Terraform documentation.

Manage Fleet Management in Grafana Cloud using Terraform

Tue, 18 Aug 2026 10:15:08 +0000

Manage Fleet Management in Grafana Cloud using Terraform

Learn how to create Grafana Fleet Management collectors and pipelines in Grafana Cloud using Terraform. This guide shows you how to create an access policy and a token for Fleet Management and Grafana Alloy, a collector with remote attributes, and a pipeline for profiling Alloy.

Before you begin

Before you begin, ensure you have the following:

A Grafana Cloud account, as shown in Get started
Terraform installed on your machine
Alloy installed on your machine
Administrator permissions in your Grafana instance

Note
All of the following Terraform configuration files should be saved in the same directory.

Configure a provider for Grafana Cloud

This Terraform configuration configures the Grafana provider to provide necessary authentication when interacting with the Cloud API. The grafana_cloud_stack (Data Source) is used to retrieve the user ID and URL details of your instance.

Create a Grafana Cloud access policy and token. To create a new one, refer to Grafana Cloud Access Policies. Add your stack to the realms list. The scopes needed for the examples in this guide are:
- accesspolicies:read
- accesspolicies:write
- accesspolicies:delete
- stacks:read

Create a file named cloud-provider.tf and add the following code block:

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

provider "grafana" {
  alias = "cloud"

  cloud_access_policy_token = "<CLOUD_ACCESS_POLICY_TOKEN>"
}

data "grafana_cloud_stack" "stack" {
  provider = grafana.cloud

  slug = "<STACK_SLUG>"
}

Replace the following field values:
- <CLOUD_ACCESS_POLICY_TOKEN> with the access policy token you created in the first step
- <STACK_SLUG> with your stack slug, which is the subdomain where your Grafana Cloud instance is available: https://<STACK_SLUG>.grafana.net

Create an access policy and token for Fleet Management

This Terraform configuration creates the following:

An access policy named fleet-management-policy with fleet-management:read and fleet-management:write scopes, using grafana_cloud_access_policy (Resource)
A token named fleet-management-token, using grafana_cloud_access_policy_token (Resource)

Create a file named fm-access-policy.tf and add the following code block:

resource "grafana_cloud_access_policy" "fm_policy" {
  provider = grafana.cloud

  name   = "fleet-management-policy"
  region = data.grafana_cloud_stack.stack.region_slug

  scopes = [
    "fleet-management:read",
    "fleet-management:write"
  ]

  realm {
    type       = "stack"
    identifier = data.grafana_cloud_stack.stack.id
  }
}

resource "grafana_cloud_access_policy_token" "fm_token" {
  provider = grafana.cloud

  name             = "fleet-management-token"
  region           = grafana_cloud_access_policy.fm_policy.region
  access_policy_id = grafana_cloud_access_policy.fm_policy.policy_id
}

Configure a provider for Fleet Management

This Terraform configuration configures the Grafana provider to provide necessary authentication when interacting with the Fleet Management API.

Create a file named fm-provider.tf and add the following code block:

locals {
  fm_id    = data.grafana_cloud_stack.stack.fleet_management_user_id
  fm_token = grafana_cloud_access_policy_token.fm_token.token
  fm_url   = data.grafana_cloud_stack.stack.fleet_management_url
}

provider "grafana" {
  alias = "fm"

  fleet_management_auth = "${local.fm_id}:${local.fm_token}"
  fleet_management_url  = local.fm_url
}

Create a Fleet Management collector

This Terraform configuration creates a collector with a remote attribute, using grafana_fleet_management_collector (Resource).

This configuration only preregisters the collector. You must complete the Run Alloy step for the collector to register with Fleet Management and be assigned remote attributes.

Create a file named fm-collector.tf and add the following code block:

resource "grafana_fleet_management_collector" "fm_collector" {
  provider = grafana.fm

  id = "prod_collector"
  remote_attributes = {
    "env" = "PROD"
  }
  enabled = true
}

Create a Fleet Management pipeline

This Terraform configuration creates a pipeline for Alloy profiling with a matcher for the collector declared in the previous step, using grafana_fleet_management_pipeline (Resource). The pipeline writes the profiles to Grafana Cloud Profiles.

Create a file named profiling.alloy.tftpl and add the following content:

// This pipeline scrapes pprof Go profiles from Alloy and sends them to Pyroscope.
//
// It requires the following environment variables to be set where Alloy is running:
//   Required:
//     * GCLOUD_RW_API_KEY: The Grafana Cloud API key with write access to Pyroscope.
//   Optional:
//     * ALLOY_ADDRESS: The address Alloy listens on. Defaults to 127.0.0.1:12345.
pyroscope.scrape "alloy" {
    targets = [
        {
            "__address__" = coalesce(
                sys.env("ALLOY_ADDRESS"),
                "127.0.0.1:12345",
            ),
            "service_name" = "alloy",
        },
    ]
    forward_to = [pyroscope.write.grafana_cloud.receiver]

    profiling_config {
        profile.process_cpu {
            enabled = true
        }

        profile.memory {
            enabled = true
        }

        profile.mutex {
            enabled = true
        }

        profile.block {
            enabled = true
        }

        profile.goroutine {
            enabled = true
        }
    }
}

pyroscope.write "grafana_cloud" {
    endpoint {
        url = "${profiles_url}"

        basic_auth {
            username = "${profiles_id}"
            password = sys.env("GCLOUD_RW_API_KEY")
        }
    }
}

Create a file named fm-pipeline.tf and add the following code block:

locals {
  profiles_id  = data.grafana_cloud_stack.stack.profiles_user_id
  profiles_url = data.grafana_cloud_stack.stack.profiles_url
}

resource "grafana_fleet_management_pipeline" "pipeline" {
  provider = grafana.fm

  name = "profiling"
  contents = templatefile(
    "profiling.alloy.tftpl",
    {
      profiles_id  = local.profiles_id,
      profiles_url = local.profiles_url,
    },
  )
  matchers = [
    "env=\"PROD\""
  ]
  enabled = true
}

Create an access policy and token for Alloy

This Terraform configuration creates the following:

An access policy named alloy-policy with set:alloy-data-write scope, using grafana_cloud_access_policy (Resource)
A token named alloy-token, using grafana_cloud_access_policy_token (Resource)

Create a file named alloy-access-policy.tf and add the following code block:

resource "grafana_cloud_access_policy" "alloy_policy" {
  provider = grafana.cloud

  name   = "alloy-policy"
  region = data.grafana_cloud_stack.stack.region_slug

  scopes = [
    "set:alloy-data-write"
  ]

  realm {
    type       = "stack"
    identifier = data.grafana_cloud_stack.stack.id
  }
}

resource "grafana_cloud_access_policy_token" "alloy_token" {
  provider = grafana.cloud

  name             = "alloy-token"
  region           = grafana_cloud_access_policy.alloy_policy.region
  access_policy_id = grafana_cloud_access_policy.alloy_policy.policy_id
}

output "alloy_token" {
  value     = grafana_cloud_access_policy_token.alloy_token.token
  sensitive = true
}

Create a configuration file for Alloy

This Terraform configuration creates an Alloy configuration file with the remotecfg block for Fleet Management, using local_file (Resource).

Create a file named config.alloy.tftpl and add the following content:

remotecfg {
    id             = "${collector_id}"
    url            = "${fm_url}"
    poll_frequency = "60s"

    basic_auth {
        username = "${fm_id}"
        password = sys.env("GCLOUD_RW_API_KEY")
    }
}

Create a file named alloy-config.tf and add the following code block:

resource "local_file" "alloy_config" {
  filename = "<ALLOY_CONFIG_PATH>"
  content = templatefile(
    "config.alloy.tftpl",
    {
      collector_id = "prod_collector",
      fm_id        = local.fm_id,
      fm_url       = local.fm_url,
    },
  )
  directory_permission = "0644"
  file_permission      = "0644"
}

Replace the following field values:
- <ALLOY_CONFIG_PATH> with the path the Alloy configuration file should be written to, for example config.alloy

Apply the Terraform configuration

In a terminal, run the following commands from the directory where all of the configuration files are located.

Initialize a working directory containing Terraform configuration files:
shell
```
terraform init
```
Preview the Terraform changes:
shell
```
terraform plan
```
Apply the configuration:
shell
```
terraform apply
```

Run Alloy

To learn how to start or restart Alloy, refer to Run Grafana Alloy.

Note
The variable GCLOUD_RW_API_KEY must be set in the environment where Alloy is running for the remote configuration in this example to work.

Run the following command to view the Alloy token:
shell
```
terraform output -raw alloy_token
```
Set the environment variable GCLOUD_RW_API_KEY to the value from the first step.
Run Alloy.

Validation

After you apply the changes in the Terraform configurations and run Alloy, you should be able to verify the following:

A collector is added to the Fleet Management Inventory tab:
A pipeline is added to the Fleet Management Remote configuration tab:
Alloy profiles are being exported to Grafana Cloud Profiles:

Summary

In this guide, you created an access policy and a token for Fleet Management and Alloy, a collector with remote attributes, and a pipeline for profiling Alloy, all using Terraform.

To learn more about managing Grafana Cloud using Terraform, refer to the Grafana provider documentation.

Manage Frontend Observability in Grafana Cloud with Terraform

Tue, 18 Aug 2026 10:15:08 +0000

Manage Frontend Observability in Grafana Cloud with Terraform

Learn how to use Terraform to manage Grafana Frontend Observability resources, such as your applications. This guide shows you how to create an access policy and a token for Frontend Observability so that you can connect to the Frontend Observability API.

Before you begin

Before you begin, ensure you have the following:

A Grafana Cloud account, as shown in Get started
Terraform installed on your machine
Administrator permissions in your Grafana instance

Note
All of the following Terraform configuration files should be saved in the same directory.

Configure a provider for Grafana Cloud

Create a Grafana Cloud access policy and token. To create a new one, refer to Grafana Cloud Access Policies. Add your stack to the realms list. The scopes needed for the examples in this guide are:
- accesspolicies:read
- accesspolicies:write
- accesspolicies:delete
- dashboards:read
- dashboards:write
- dashboards:delete
- orgs:read
- orgs:write
- stacks:read
- stacks:write
- stacks:delete
- stack-dashboards:read
- stack-dashboards:write
- stack-dashboards:delete
- stack-service-accounts:write

Create a file named cloud-provider.tf and add the following code block:

terraform {
  required_providers {
    grafana = {
      source  = "grafana/grafana"
    }
  }
}

provider "grafana" {
  alias = "cloud"

  cloud_access_policy_token = "<CLOUD_ACCESS_POLICY_TOKEN>"
}

data "grafana_cloud_stack" "stack" {
  provider = grafana.cloud

  slug = "<STACK_SLUG>"
}

Replace the following field values:
- <CLOUD_ACCESS_POLICY_TOKEN> with the access policy token you created in the first step
- <STACK_SLUG> with your stack slug, which is the subdomain where your Grafana Cloud instance is available: https://<STACK_SLUG>.grafana.net

Create an access policy and token for Frontend Observability

You must create a Terraform configuration with the following:

An access policy with frontend-observability:read, frontend-observability:write, and frontend-observability:delete scopes, using grafana_cloud_access_policy (Resource)
A token named frontend_o11y_api_access_token, using grafana_cloud_access_policy_token (Resource)

Configure the provider to use the Frontend Observability API

After you have created the token, you can configure the provider as follows:

provider "grafana" {
  frontend_o11y_api_access_token = "<access token from previous step>"
}

Summary

In this guide, you created an access policy and a token for Frontend Observability using Terraform.

To learn more about managing Grafana Cloud using Terraform, refer to the Grafana provider documentation.

Manage Cloud Provider Observability in Grafana Cloud using Terraform

Tue, 18 Aug 2026 10:15:08 +0000

Manage Cloud Provider Observability in Grafana Cloud using Terraform

Manage Cloud Provider Observability, including Amazon CloudWatch and Microsoft Azure resources, in Grafana Cloud using Terraform. For more information on Cloud Provider Observability, refer to the Cloud Provider Observability documentation.

Before you begin

Before you begin, ensure you have the following:

A Grafana Cloud account
- For more information on setting up a Grafana Cloud account, refer to Get started.
Terraform installed on your machine
- For more information on how to install Terraform, refer to the Terraform install documentation.
Administrator permissions in your Grafana instance
- For more information on assigning Grafana RBAC roles, refer to Assign RBAC roles.

Note
Save all of the following Terraform configuration files in the same directory.

Configure authentication for the Grafana Provider

The Grafana Provider is a logical abstraction of an upstream API that you can use to interact with Grafana Cloud resources. You must configure it with the following information:

A Grafana Cloud access policy token that includes the permissions the provider needs to access the Grafana Cloud Provider API.
A regional cloud provider API endpoint to establish which Grafana Cloud stack you are accessing.

To configure authentication for the Grafana Provider:

Create a Grafana Cloud access policy and token.
- To create an access policy for your organization, refer to the Create an access policy for a stack steps and use the following scopes listed for the supported Amazon CloudWatch or Microsoft Azure resources:
  - Amazon CloudWatch
    - Metrics scrape or resource metadata scrape
      - integration-management:read
      - integration-management:write
      - stacks:read
    - Metric streams
      - metrics:write
    - ALB access logs, logs with Lambda, or logs with Amazon Data Firehose
      - logs:write
- Microsoft Azure
  - Serverless metrics
    - integration-management:read
    - integration-management:write
    - stacks:read
  - Logs with Azure functions
    - logs:write
Obtain the regional Cloud Provider API endpoint.
- To obtain the regional Cloud provider API endpoint, use your access policy token and the following command to return a list of all of the Grafana stacks you own, along with their respective Cloud Provider API hostnames:
Bash
```
curl -sH "Authorization: Bearer @@@GRAFANA_CLOUD_ACCESS_POLICY_TOKEN@@@" "https://grafana.com/api/instances" | \
jq '[.items[]|{stackName: .slug, clusterName:.clusterSlug, cloudProviderAPIURL: "https://cloud-provider-api-\(.clusterSlug).grafana.net"}]'
```
Note
If this endpoint does not work, your Grafana Cloud Provider API endpoint may be using the new URL format. For more information on Grafana Cloud URLs, refer to Determine Grafana Cloud URLs based on region.

Create a file named cloud-provider.tf and add the following code block:

terraform {
    required_providers {
    grafana = {
        source  = "grafana/grafana"
    }
  }
}

provider "grafana" {
    cloud_api_url      = "<@@@CLOUD_PROVIDER_API_URL@@@"
    cloud_access_policy_token     = "@@@CLOUD_ACCESS_POLICY_TOKEN@@@>"
}

Create a variables.tf file and paste the CLOUD_ACCESS_POLICY_TOKEN and CLOUD_PROVIDER_API_URL variables with your values.
Run the following Terraform command:
tf
```
terraform apply -var-file="variables.tf"
```

Configure your resources

To find instructions for configuring specific Amazon CloudWatch and Microsoft Azure resources in Cloud Provider Observability using Terraform, refer to the following documents:

Amazon CloudWatch
- Metrics scrape: Pull CloudWatch metrics from multiple regions for your AWS account, without needing to install Grafana Alloy.
- Metric streams: Push metrics with CloudWatch metric streams using Amazon Data Firehose, providing real-time insights and scalability while simplifying configuration and reducing cost and manual effort.
- ALB access logs: Send application load balancer access logs from AWS to Grafana Cloud using a Lambda function.
- Logs with Lambda: Send logs to Grafana Cloud from multiple AWS services using a lambda-promtail function.
- Logs with Amazon Data Firehose: Send logs from AWS to Grafana Cloud with Amazon Data Firehose and minimal infrastructure.
Microsoft Azure
- Serverless metrics: Monitor your Azure resources without the need to configure or deploy a collector by using Cloud Provider Observability.
- Logs with Azure functions: Send Azure event logs to a Loki endpoint using an Azure function that subscribes to an Azure event hub.

Grafana cloud provider resources

You can define the following Cloud Provider Observability resources and data sources using Terraform:

Resource name	Description
`grafana_cloud_provider_aws_account`	Represents an AWS IAM role that authorizes Grafana Cloud to pull Amazon CloudWatch metrics for a set of regions. Usually, there’s one of these resources per configured AWS account. For a full reference of this resource, refer to the Terraform Grafana Provider reference documentation.
`grafana_cloud_provider_aws_cloudwatch_scrape_job`	Represents a Grafana AWS scrape job. This configures Grafana to fetch a list of metrics and statistics for one or many AWS services, and for a given `grafana_cloud_provider_aws_account`. For a full reference of this resource, refer to the Terraform Grafana Provider reference documentation.
`grafana_cloud_provider_aws_resource_metadata_scrape_job`	Represents a Grafana AWS Resource Metadata scrape job. This resource configures Grafana to fetch resource metadata for one or multiple AWS services, for a given `grafana_cloud_provider_aws_account`. For a full reference of this resource, refer to the Terraform Grafana Provider reference documentation.
`grafana_cloud_provider_azure_credential`	A resource representing an Azure Service Principal credential used by Grafana Cloud to pull Azure Monitor metrics from one or more subscriptions. For a full reference of this resource, refer to the Terraform Grafana Provider resource documentation.

Install plugins in Grafana Cloud using Terraform

Tue, 18 Aug 2026 10:15:08 +0000

Install plugins in Grafana Cloud using Terraform

This guide shows you how to install plugins in Grafana Cloud using Terraform. For more information about Grafana plugins, refer to the Find and use Grafana plugins documentation.

Before you begin

Before you begin, ensure you have the following:

A Grafana Cloud account; for more information on setting up a Grafana Cloud account, refer to Get started.
Terraform installed on your machine; for more information on how to install Terraform, refer to the Terraform install documentation.
Administrator permissions in your Grafana instance; for more information on assigning Grafana RBAC roles, refer to Assign RBAC roles.

Note
Save all of the following Terraform configuration files in the same directory.

Configure the Grafana provider

Use this Terraform configuration to set up the Grafana provider to provide the authentication required to manage plugin resources.

Create a service account and token in Grafana. For more information on creating a service account and token, refer to Service account tokens. You can also refer to Creating and managing a Grafana Cloud stack using Terraform to set up a service account and a token.
Make sure that the token has the following permissions:

stack-plugins:read
stack-plugins:write
stack-plugins:delete

Next, create a file named main.tf and add the following:

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

   provider "grafana" {
     cloud_api_url      = "<Stack-URL>"
     cloud_access_policy_token     = "<Service-account-token>"
   }

Replace the following field values:

Stack-URL with the URL of your Grafana stack, for example https://my-stack.grafana.net/
Service-account-token with the service account token that you created

Create new plugin resource

Create a file named plugins.tf and add the following:

resource "grafana_cloud_plugin_installation" "grafana-clock-panel" {
  stack_slug   = "<Your-Stack-Slug>"
  slug         = "grafana-clock-panel"
  version      = "latest"
}

Summary

In this guide, you learned how to install a plugin in Grafana Cloud using Terraform.

To learn more about plugin installation, refer to the Grafana provider documentation.

Manage saved queries using Terraform

Tue, 18 Aug 2026 10:15:08 +0000

Manage saved queries using Terraform

This guide shows you how to manage saved queries, also known as the query library, using the Grafana Terraform provider. Managing saved queries as code lets you version-control your query library and keep it consistent across Grafana instances.

Note
Saved queries are only available on Grafana Enterprise and Grafana Cloud.

Before you begin

Before you begin, ensure you have the following:

A Grafana Enterprise or Grafana Cloud instance. For more information on setting up a Grafana Cloud account, refer to Get started.
Terraform installed on your machine. For more information on how to install Terraform, refer to the Terraform install documentation.
A service account token with the Writer role for saved queries. For more information, refer to Roles, permissions, and RBAC and Service account tokens.

Configure the Grafana provider

Create a file named main.tf and add the following to set up the Grafana provider with the authentication required to manage saved queries:

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

provider "grafana" {
  url  = "<Grafana-URL>"
  auth = "<Service-account-token>"
}

Replace the following field values:

Grafana-URL with the URL of your Grafana instance, for example https://my-stack.grafana.net/
Service-account-token with the service account token that you created

Create a saved query resource

Create a file named saved-queries.tf and add the following:

resource "grafana_apps_queries_query_v1" "example" {
  metadata {
    uid = "example-saved-query"
  }

  spec {
    title       = "Requests per second"
    description = "Prometheus rate of HTTP requests"
    is_visible  = true
    tags        = ["http", "prometheus"]

    targets {
      properties_json = jsonencode({
        refId = "A"
        expr  = "rate(http_requests_total[$__rate_interval])"
        datasource = {
          type = "prometheus"
          uid  = "my-prometheus-uid"
        }
      })
    }
  }
}

Because the shape of a data source query depends on the data source, the query stored in each target (properties_json), a target’s variable replacements (variables_json), and a variable’s value list (value_list_definition_json) are passed as raw JSON strings. Use jsonencode() to construct them.

The spec block supports the following fields:

Field	Description
`title`	The display name of the saved query. Required.
`description`	A longer description of the saved query.
`is_visible`	Whether the saved query is visible in the query library.
`is_locked`	Whether the saved query is locked and can’t be edited in the UI. This is for UI display only, not for security.
`tags`	The tags used to filter the saved query.
`targets`	The query targets that make up the saved query. At least one target is required.
`vars`	The template variables that can be interpolated into the query targets.

For the complete schema, refer to the grafana_apps_queries_query_v1 resource documentation.

Import an existing saved query

To bring an existing saved query under Terraform management, import it using its UID:

terraform import grafana_apps_queries_query_v1.example example-saved-query

Summary

In this guide, you learned how to create and import saved queries using Terraform.

To learn more about saved queries, refer to Saved queries.

Grafana Terraform provider on Grafana Labs

Create and manage a Grafana Cloud stack using Terraform

Create and manage a Grafana Cloud stack using Terraform

Prerequisites

Create a Cloud stack

Add a data source

Add a folder

Add a dashboard to the folder

Apply the Terraform configuration

Validation

Summary

Create and manage dashboards using Terraform and GitHub Actions

Create and manage dashboards using Terraform and GitHub Actions

Prerequisites

Add dashboards to a GitHub repository

Terraform configuration for Grafana provider

Terraform configuration for folders

Terraform configuration for dashboards

GitHub workflow for managing dashboards using Terraform

Managing the Terraform state

Validation

Summary

Manage Grafana IRM in Grafana Cloud using Terraform

Manage Grafana IRM in Grafana Cloud using Terraform

Before you begin

Connect Slack to Grafana IRM

Configure the Grafana provider

Authentication via OnCall API tokens (deprecated)

Add on-call schedules

Add escalation chains

Connect an integration to Grafana IRM

Set up a route to configure escalation behavior for alert group notifications

Apply the Terraform configuration

Validation

Summary

Manage Knowledge Graph in Grafana Cloud using Terraform

Manage Knowledge Graph using Terraform

Overview

Explore

Related resources

Manage secrets in Grafana Cloud using Terraform

Manage secrets in Grafana Cloud using Terraform

Before you begin

Create a service account token

Configure the Grafana provider

Define a secure value

Schema reference

Decrypters

Provision the secure value with Terraform

Verify that the plaintext stays out of state

Rotate a secure value

Rotation considerations

Handle the secret value safely

Import an existing secure value

Provision a keeper

Keeper requirements

Define a keeper

Keeper schema reference

Activate and use the keeper

Summary

Next steps

Manage Fleet Management in Grafana Cloud using Terraform

Manage Fleet Management in Grafana Cloud using Terraform

Before you begin

Configure a provider for Grafana Cloud

Create an access policy and token for Fleet Management

Configure a provider for Fleet Management

Create a Fleet Management collector

Create a Fleet Management pipeline

Create an access policy and token for Alloy

Create a configuration file for Alloy

Apply the Terraform configuration

Run Alloy

Validation

Summary

Manage Frontend Observability in Grafana Cloud with Terraform

Manage Frontend Observability in Grafana Cloud with Terraform

Before you begin

Configure a provider for Grafana Cloud

Create an access policy and token for Frontend Observability