Checkly Terraform provider

Your infrastructure is in Terraform. Put your monitors there too.

The Checkly provider adds checks, groups, alert channels, status pages, and private locations to the HCL you already review, plan, and apply. Same pull request, same state, same pipeline as the services they watch.

Start for freeRead the docs
checks.tfcheckly/checkly ~> 1.0
1resource "checkly_check" "orders_api" {
2 name = "GET /v1/orders"
3 type = "API"
4 activated = true
5 frequency = 1
6 use_global_alert_settings = true
7 degraded_response_time = 3000
8 max_response_time = 10000
9 locations = ["eu-central-1", "us-east-1"]
10 tags = ["checkout", "terraform"]
11
12 retry_strategy {
13 type = "LINEAR"
14 max_retries = 2
15 same_region = false
16 }
17
18 request {
19 url = "https://api.acme.dev/v1/orders"
20 follow_redirects = true
21
22 assertion {
23 source = "STATUS_CODE"
24 comparison = "EQUALS"
25 target = "200"
26 }
27
28 assertion {
29 source = "JSON_BODY"
30 property = "$.orders"
31 comparison = "NOT_EMPTY"
32 }
33 }
34}

Trusted by engineering teams that manage everything as code

Vercel
Carhartt
CrowdStrike
Airbus
Fanatics
Mistral
ServiceNow
GoFundMe
Hopper
1Password
Fastly
Total Wine
“We chose Checkly because of the Terraform provider that was available out of the box. Another important thing for us was the fact that we could automate the generation of the checks from Terraform.”
Alessio Casco·Head of DevOps, TrueLayer

Your app's code lives in source control. Your monitoring should too.

Monitoring configured by hand drifts behind the product. Monitoring declared in Terraform ships with the release, rolls back with the release, and documents itself in the process.

terraform plan

Monitors show up in the same diff as the service

A new endpoint and the check that watches it land in one pull request. Reviewers see the assertion next to the route, and terraform plan tells everyone what changes before anything runs.

terraform state

State owns the lifecycle

Rename a check, move it into a group, or delete the service it covered, and apply reconciles the account to match. No orphaned monitors paging for an API that no longer exists.

checkly_*

The whole setup, not just checks

Groups, alert channels, status pages, dashboards, maintenance windows, private locations, snippets, and environment variables are all resources. One apply stands up the full account.

Resources in the provider

checkly_checkcheckly_check_groupcheckly_alert_channelcheckly_playwright_check_suitecheckly_url_monitorcheckly_tcp_monitorcheckly_dns_monitorcheckly_icmp_monitorcheckly_heartbeat_monitorcheckly_status_pagecheckly_dashboardcheckly_maintenance_windowscheckly_private_locationcheckly_snippetcheckly_environment_variablefull list on the registry →

Check, group, alert channel. Three resources.

Managing checks, groups, and alert channels should never be the bottleneck for shipping more code. Declare them once, reference them by name, and let Terraform work out the order.

  • Browser checks reference a Playwright file in your repo
  • Groups own locations, retries, and alert settings for every check inside
  • Alert channels are standalone resources you subscribe groups to
  • Dependencies resolve from references, no IDs copied out of the UI
checks.tfhcl
1resource "checkly_check" "add_to_cart" {
2 name = "Add to cart"
3 type = "BROWSER"
4 activated = true
5 frequency = 5
6 locations = ["us-west-1", "eu-central-1"]
7
8 retry_strategy {
9 type = "LINEAR"
10 }
11
12 # Plain Playwright. Run it locally with npx playwright test.
13 script = file("${path.module}/scripts/add-to-cart.spec.js")
14}

A browser check is a Playwright script in your repo, referenced by path. Frequency, locations, and retries are arguments on the resource.

Review the diff before it pages anyone

terraform plan shows exactly which monitors are created, changed, or destroyed. Apply from your laptop, from CI, or from Terraform Cloud on every push to main, with state kept in the remote backend you already run.

  • Every monitor change is a reviewable plan in the pull request
  • Apply creates channels, groups, and checks in dependency order
  • Remote state keeps teammates and pipelines from creating duplicates
  • Terraform Cloud auto-apply turns a merge into live monitoring

When a check fails, the same Checkly alerting applies: retries, escalation, and 18+ channels. How alerting works.

ci · terraform3 resources
$ terraform plan
Terraform used the selected providers to generate the following execution plan.
Resource actions are indicated with the following symbols:
+ create
Terraform will perform the following actions:
# checkly_alert_channel.pagerduty_oncall will be created
+ resource "checkly_alert_channel" "pagerduty_oncall" {
+ id = (known after apply)
+ send_failure = true
+ send_recovery = true
...
}
# checkly_check_group.checkout will be created
+ resource "checkly_check_group" "checkout" {
+ concurrency = 5
+ locations = ["eu-central-1", "us-west-1"]
...
}
# checkly_check.add_to_cart will be created
+ resource "checkly_check" "add_to_cart" {
+ frequency = 5
+ group_id = (known after apply)
+ type = "BROWSER"
...
}
Plan: 3 to add, 0 to change, 0 to destroy.
$ terraform apply -auto-approve
checkly_alert_channel.pagerduty_oncall: Creating...
checkly_alert_channel.pagerduty_oncall: Creation complete after 1s [id=48213]
checkly_check_group.checkout: Creating...
checkly_check_group.checkout: Creation complete after 1s [id=9107]
checkly_check.add_to_cart: Creating...
checkly_check.add_to_cart: Creation complete after 2s [id=7f3c9a4e-1b2d-4c8e-9f0a-2d6b8e4c1a57]
Apply complete! Resources: 3 added, 0 changed, 0 destroyed.
“Everything scaffolds out based on a configuration, so we just update a configuration file which specifies the environments, what services are there, what the URLs are, and from that, we just generate all the groups and their checks.”
Tobias Deekens·Principal Frontend Engineer, commercetools

Get started in three steps

From an empty folder to a running check in one apply. Or clone the getting-started repository and skip the typing.

01

Add the provider

Pin checkly/checkly from the Terraform Registry and pass your credentials through variables, so nothing sensitive lands in the repo.

main.tf
1terraform {
2 required_providers {
3 checkly = {
4 source = "checkly/checkly"
5 version = "~> 1.0"
6 }
7 }
8}
9
10variable "checkly_api_key" {}
11variable "checkly_account_id" {}
12
13provider "checkly" {
14 api_key = var.checkly_api_key
15 account_id = var.checkly_account_id
16}
02

Export your credentials

A user API key and the target account ID, both from your Checkly settings. TF_VAR_ prefixes feed them straight into the variables above.

shell
# User API key: app.checklyhq.com/settings/user/api-keys
$ export TF_VAR_checkly_api_key=cu_xxx
# Account ID: app.checklyhq.com/settings/account/general
$ export TF_VAR_checkly_account_id=xxx
03

Init and apply

terraform init installs the provider. terraform apply shows the plan, waits for your yes, and creates the resources in your Checkly account.

shell
$ terraform init
Initializing provider plugins...
- Finding checkly/checkly versions matching "~> 1.0"...
- Installing checkly/checkly v1.28.0...
- Installed checkly/checkly v1.28.0 (signed by a HashiCorp partner)
Terraform has been successfully initialized!
$ terraform apply
Plan: 1 to add, 0 to change, 0 to destroy.
Do you want to perform these actions?
Only 'yes' will be accepted to approve.
Enter a value: yes
checkly_check.orders_api: Creating...
checkly_check.orders_api: Creation complete after 1s [id=cc143901-fbae-4942-91fe-4b99b0250567]
Apply complete! Resources: 1 added, 0 changed, 0 destroyed.

Terraform or the Checkly CLI?

Both are monitoring as code against the same account. The honest answer depends on where the rest of your configuration already lives.

npx checkly deploy

The Checkly CLI

The primary path. Monitors are TypeScript constructs next to your Playwright tests, you run them against any environment with npx checkly test before they deploy, and the project layout is built for monitoring first.

Start here if monitoring is a new codebase for your team. Monitoring as code with the CLI

terraform apply

The Terraform provider

For teams whose infrastructure is already declared in Terraform. Monitors join the same state, the same plan, and the same pipeline, and the Playwright scripts they run still test locally with npx playwright test.

Pick one owner per resource. Checkly resources should be managed either through Terraform or through the UI, not both.

Frequently asked questions

Everything you need to know about the Checkly Terraform provider, its resources, and how it fits next to the CLI.

It is the official checkly/checkly provider on the Terraform Registry, published under the HashiCorp partner tier. It lets you declare Checkly checks, groups, alert channels, and the rest of your monitoring account as HCL resources, then create and update them with terraform plan and terraform apply. The current major version is 1.x, so a version constraint of "~> 1.0" tracks it.

API, browser, and multistep checks (checkly_check), Playwright check suites, URL, TCP, DNS, ICMP, and heartbeat monitors, check groups, alert channels, status pages, dashboards, maintenance windows, private locations, code snippets, environment variables, and command line triggers. The full resource list with every argument is on the Terraform Registry documentation for the provider.

The Checkly CLI is the primary monitoring-as-code path: TypeScript constructs, a local test run before deploy, and a project structure built for monitors. Pick Terraform when your team already manages infrastructure in Terraform and wants monitors in the same state, plan, and pipeline. Both talk to the same Checkly account and expose the same check types.

You should not. Checkly resources should be managed either through Terraform or through the UI, not both. Changing a Terraform-managed check in the app puts it out of sync with your state, and the next apply will either revert the change or fail. Keep each resource in one place.

When a check has a group_id, the group settings decide which locations it runs from and which alert channels it is subscribed to. Group-level alert channel subscriptions override check-level ones, so the simplest setup is to subscribe the group once and let every check inside it inherit the subscription.

Yes. The provider runs anywhere Terraform does. If more than one machine or person applies the configuration, use a remote backend so the state stays in sync; Terraform Cloud handles that for you and can auto-apply on every push to your default branch.

Browser check scripts are plain Playwright, so run them locally with npx playwright test before referencing them from a checkly_check resource with file(). If the script imports shared helpers, declare those files as checkly_snippet resources so they are available when the check runs on Checkly.

One apply away from monitored

Add the provider, export two variables, and your first check is running from the plan you just reviewed. No credit card required.

Start for freeBook a demo