Table of contents

Terraform

You can use Hashicorp’s Terraform to create and manage your checks. This allows you to:

1. Specify your monitoring infrastructure as code, and have it live in source control.
2. Manage large numbers of checks efficiently and without manual intervention.

If you have a complex active monitoring setup that often need updating, Terraform is our recommended solution.

Following is a short introduction to using the Checkly Terraform provider; for in-depth information, please see the official documentation.

To get started, install the latest version of the Checkly Terraform provider from the Terraform registry.

Your main.tf file will look similar to the following:

terraform {
  required_providers {
    checkly = {
      source = "checkly/checkly"
      version = "1.3.0"
    }
  }
}

variable "checkly_api_key" {}
variable "checkly_account_id" {}

provider "checkly" {
  api_key = var.checkly_api_key
  account_id = var.checkly_account_id
}

To use the provider with your Checkly account, you will need an API Key for your Checkly user. Go to the User Settings: API Keys page and click ‘Create API Key’. Get your User API Key and add it to your env:

$ export TF_VAR_checkly_api_key=cu_xxx

You also need to set your target Account ID, which you can find under your account settings. If you don’t have access to account settings, please contact your account owner/admin.

$ export TF_VAR_checkly_account_id=xxx

⚠️ If you are still using legacy Account API Keys, you can skip this step. Notice that Account API keys will be deprecated soon.

After running terraform init, you can now start adding resources to your file. You can check the official documentation to see available parameters for each resource type. You can also find examples in the following sections on this page.

There are three different kinds of resources you can manage on Checkly:

1. API checks
2. Browser checks
3. Check groups

A simple API check could look as follows:

resource "checkly_check" "example-api-check" {
  name                      = "Example API check"
  type                      = "API"
  activated                 = true
  frequency                 = 1
  double_check              = true
  use_global_alert_settings = true

  locations = [
    "us-west-1",
    "eu-central-1"
  ]

  request {
    url              = "https://api.example.com/"
    follow_redirects = true
    assertion {
      source     = "STATUS_CODE"
      comparison = "EQUALS"
      target     = "200"
    }
  }
}

The above creates an API check named Example API check, which will run every minute against https://api.example.com/ from two locations, asserting for a 200 response status code and retrying in case of failure, sending alerts using the global alerting configuration on your account.

Browser checks have less options:

resource "checkly_check" "example-browser-check" {
  name                      = "Example browser check"
  type                      = "BROWSER"
  activated                 = true
  frequency                 = 10
  double_check              = true
  use_global_alert_settings = true
  locations = [
    "us-west-1",
    "us-east-1",
    "eu-central-1"
  ]

  script = <<EOT
const assert = require("chai").assert;
const puppeteer = require("puppeteer");

const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto("https://google.com/");
const title = await page.title();

assert.equal(title, "Google");
await browser.close();

EOT
}

The above will create a browser check named Example browser check, which will run the included puppeteer script every 10 minutes from three locations, for a 200 response status code and retrying in case of failure, sending alerts using the global alerting configuration on your account.

Notice the multi line string syntax with EOT. An alternative syntax for adding the script is by referencing an external file:

data "local_file" "browser-script" {
  filename = "${path.module}/browser-script.js"
}

resource "checkly_check" "browser-check-1" {
  ...
  script = data.local_file.browser-script.content
}

Checkly’s groups feature allows you to group together a set of related checks, which can also share default settings for various attributes. Here is an example check group:

resource "checkly_check_group" "example-group" {
  name      = "Example group"
  activated = true

  locations = [
    "eu-west-1",
    "eu-central-1"
  ]
  concurrency = 2
  environment_variables = {
    ENV1 = "somevalue",
  }
  double_check              = true
  use_global_alert_settings = true
}

The above will create a group running from two locations, which will run two checks at a time when triggered from CI, with one environment variable and global alert settings.

To add a check to a group, set its group_id attribute to the ID of the group. For example:

resource "checkly_check" "test-check" {
  name                      = "My test check"
  ...
  group_id    = checkly_check_group.example-group.id
  group_order = 1
}

The group_order attribute specifies in which order the checks will be executed: 1, 2, 3, etc.

After each change to your Terraform file, you will need to run both following commands:

1. terraform plan -out tf.plan - to plan the necessary actions that Terraform will need to make.
2. terraform apply "tf.plan" - to apply the plan and have the changes reflected on Checkly.

If you are using Terraform Cloud, the above will be run for you automatically every time a pull request is merged into a main branch.

We often publish in-depth articles on how to use Terraform with Checkly on our blog:

1. Managing Checkly checks with Terraform
2. Scaling Puppeteer & Playwright on Checkly with Terraform

If you want to get your hands dirty on the very last in development version, you can:

1. Checkout the Checkly Terraform provider in this GitHub repo.
2. Build the provider and add it to your Terraform installation.
3. Write your first Checkly resource and apply it.