Grafana Labs

How to manage synthetic monitoring checks as code with Terraform and Grafana Cloud

7.5内容质量

TL;DR · AI 摘要

核心要点

  • 随着监控规模扩大，手动在UI配置合成监控易出错且难维护，采用Terraform实现基础设施即代码是更优解。
  • 推荐“UI原型验证→配置Provider→导出为Terraform资源→代码化管理”的标准工作流，兼顾效率与规范。
  • 将监控检查代码化可实现版本控制、多环境一致性、PR协作审查及批量部署，显著提升可观测性工程的可维护性。
#Terraform#Grafana Cloud#合成监控#可观测性#基础设施即代码
打开原文

As teams scale, managing synthetic monitoring checks manually in the UI becomes difficult and error-prone. When you're dealing with dozens of checks across multiple environments, teams experience inconsistent configurations, lack of version control, and difficulty tracking changes.

This is where managing your Grafana Cloud Synthetic Monitoring checks as code using Terraform can be valuable, allowing you to define checks programmatically, maintain version control, and deploy consistent configurations across environments. This helps you scale your synthetic monitoring strategy while ensuring reproducible setups.

In this blog post, we'll show you how to export a Grafana Cloud Synthetic Monitoring check from the UI, configure the Terraform provider, and deploy and update checks using Terraform. You can also learn more by watching the video below.

Why manage checks as code?

Grafana Cloud Synthetic Monitoring is a blackbox monitoring solution that lets you run a variety checks such as browser checks,HTTP checks, and DNS checks from globally distributed public probes or self-hosted private probes to proactively measure the availability, latency, and correctness of your service.

As your monitoring needs grow beyond a handful of checks, the manual UI-based approach becomes unsustainable. With each change to a check, you risk environments drifting out of sync, and there's no audit trail for modifications. While tools like Grizzly or the Grafana CLIcan also help manage checks at scale, Terraform is our recommended approach

Terraform offers mature state management and broad ecosystem support for scalable monitoring operations. Managing checks as code with Terraform provides a consistent, scalable, and repeatable foundation for synthetic monitoring as your system grows, with key benefits including:

  • Version control:Track every change to your monitoring configuration in Git
  • Consistency: Ensure checks are configured identically across dev, staging, and production
  • Collaboration: Review changes through pull requests before deployment
  • Scalability:Deploy and manage hundreds of checks with a single command
  • Reusability:Template similar checks and modify parameters as needed

The Terraform workflow for synthetic monitoring checks

A common Terraform workflow for synthetic monitoring checks looks like this:

1. Prototype in the Grafana UI: Start by creating your check in the UI to validate the configuration, test functionality, and explore available options. This prototyping approach is faster than writing configuration files from scratch.

2. Configure the Terraform provider:This tells Terraform which Grafana Cloud stack to manage.

3. Export the check to Terraform: Once exported, the check becomes a Terraform resource that you can modify and reuse.

4. Deploy and manage updates with Terraform: from this point forward, Terraform becomes the source of truth for modifying and managing checks.

Let's walk through each step.

Prototype in the Grafana UI

Start by creating your check in the UI. Once it has been created, we will collect our dedicated access token and probe API server URL.

  1. In Grafana Cloud, navigate to Synthetic Monitoring and click Config.
  1. Click Generate access token and copy the value.
Image 1: A screenshot of a Config page, with a yellow box around a button that says "Generate access token."
Image 1: A screenshot of a Config page, with a yellow box around a button that says "Generate access token."
  1. Note the API endpoint URL shown on this page, as you'll need it when configuring the Terraform provider.
Image 2: A screenshot of a UI that says "Config" at the top and has a yellow box around the Probe API Server URL section.
Image 2: A screenshot of a UI that says "Config" at the top and has a yellow box around the Probe API Server URL section.

Configure the Terraform provider

We'll create a terraform.tfvars file to store our credentials:

code
sm_access_token = "your-synthetic-monitoring-access-token"
sm_url = "https://synthetic-monitoring-api.grafana.net"

Note: The Synthetic Monitoring provider uses a separate URL and access token from the standard Grafana Terraform provider. If you're managing other Grafana resources in the same Terraform workspace, you'll need both configured separately.

Next, we'll configure the provider in main.tf:

Image 3: A screenshot of the main.tf file.
Image 3: A screenshot of the main.tf file.

With that in place, we can initialize the Terraform provider:

terraform init

Export your check as Terraform HCL

Rather than writing the resource config from scratch, Grafana can generate it for us directly from an existing check.

  1. In Grafana Cloud, go to Synthetic Monitoring and click Config.
  1. Select the Terraform tab and find the check you want to manage.
  1. Choose HCL format and copy the resource block.

The exported HCL will look something like this:

Image 4: A screenshot of the exported HCL.
Image 4: A screenshot of the exported HCL.

We'll paste this into a checks.tf file. From this point on, Terraform is the source of truth for this check.

Image 5: A screenshot of the checks.tf file.
Image 5: A screenshot of the checks.tf file.

Deploy multiple checks

One of the key advantages of managing checks as code is being able to define multiple checks with consistent configuration. Here's an example with two team-specific checks, where one targets a dev environment and one enforces SSL validation for a security team endpoint.

To deploy both checks, we run:

terraform apply

Terraform will display a plan showing exactly what it's about to create and prompt us to confirm before making any changes. Once we approve, the new checks will appear in Grafana Cloud Synthetic Monitoring.

Image 6: A screenshot show two synthetic monitoring checks: one for dev-synth app and one for security-synth app.
Image 6: A screenshot show two synthetic monitoring checks: one for dev-synth app and one for security-synth app.

Update checks over time

Once our checks are in Terraform, making updates is straightforward. We edit the relevant fields in the .tf file and run terraform apply again. For example, to update the dev check to run every two minutes and reassign it to the dev-2 team, we update the frequency and label.

This makes it straightforward to review and audit changes, and integrates cleanly into a CI/CD pipeline where terraform plan output can be part of a pull request review process.

Note: Once you move to Terraform, avoid editing checks in the Grafana UI. After the first terraform apply, Terraform owns the state, and any changes made directly in the UI will be overwritten on the next apply.

Wrapping up

Managing synthetic monitoring checks as code with Terraform provides a consistent, scalable, and repeatable foundation for your checks as your system grows. By leveraging Grafana Cloud Synthetic Monitoring with Terraform, you can version, review, and deploy changes to your checks using the same workflows you already use for the rest of your infrastructure.

To learn more about provisioning Grafana Cloud Synthetic Monitoring resources, refer to our[](https://grafana.com/docs/grafana-cloud/testing/synthetic-monitoring/set-up/provision-synthetic-monitoring-resources/?pg=how-to-manage-synthetic-monitoring-checks-as-code-with-terraform-and-grafana-cloud&plcmt=in-text)technical documentation. For a full Terraform reference on available check settings, including DNS, TCP, ping, and scripted checks, visit the Terraform Registry.

_Grafana Cloud_ _is the easiest way to get started with synthetic monitoring. We have a generous free tier that includes 100k test executions per month and more._ _Sign up for free now!_

Tags