Creating and managing 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, you should have the following available:

A Grafana Cloud account, as shown in Quickstarts
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 Grafana Cloud API key. You’ll need this for the Terraform configuration. See Create a Grafana Cloud API key.

Create a Terraform configuration file.

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

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

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

# Declaring the first provider to be only used for creating the cloud-stack
provider "grafana" {
  alias         = "first"

  cloud_api_key = "<API-Key>"
}

resource "grafana_cloud_stack" "<stack-name>" {
  provider    = grafana.first

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

# Creating an API key in Grafana instance to be used for creating resources in Grafana instance
resource "grafana_api_key" "<API-key-name>" {
  provider = grafana.first

  cloud_stack_slug = grafana_cloud_stack.<stack-name>.slug
  name             = "<API-key-name>"
  role             = "<Role>"
}

# Declaring the second provider to be used for creating resources in Grafana
provider "grafana" {
  alias         = "second"

  url  = grafana_cloud_stack.<stack-name>.url
  auth = grafana_api_key.<API-key-name>.key
}

Replace the following field values:
- <API-Key> with the API key you created in the Cloud portal.
- <stack-name> with the name of your stack.
- <region> with the region in which you want to create the stack. For example us, eu.
- <API-key-name> with a name for the 2nd API key that will be created to use for operations within the stack/instance.
- <Role> with either the Admin or Editor role to be associated with this API key.

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

The second provider block, grafana.second 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.second

  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.second

  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.second

  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.
```
terraform init
```
Preview the changes that Terraform will make.
```
terraform plan
```
Apply the configuration files.
```
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
An API key is added in your Grafana instance. In the following image, the API key named “terraform” was added by the grafana_api_key (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.