Skip to content

Terraform: document checkly_check_group_v2, safe migration, and that deleting a group deletes its checks - #795

Merged
hlenke merged 4 commits into
mainfrom
docs/terraform-check-group-v2
Nov 7, 2026
Merged

hlenke merged 4 commits into
mainfrom
docs/terraform-check-group-v2

Conversation

@hlenke

@hlenke hlenke commented Nov 7, 2026

Copy link
Copy Markdown
Member

What changed

Terraform checks and groups page

  • Groups now use checkly_check_group_v2 (provider 1.20.0+): a minimal example, and an example that overrides check settings with an enforce_* block. Lists the available blocks.
  • "Adding checks to groups" references the v2 resource. The existing note about group settings overriding check settings now explains the v1/v2 difference.
  • New Migrating to checkly_check_group_v2 section: terraform state rm + terraform import, so the group and its checks stay in place. A warning explains why only changing the resource type is destructive.
  • New Deleting a group warning: deleting a group deletes its checks, so remove group_id from them and apply before removing the group.

Groups page

  • Notes that deleting a group deletes every check in it.

Why

Users asked how to move to the v2 group resource, and the docs only showed v1. The obvious migration, changing the resource type, makes Terraform delete the old group first. Deleting a group deletes its checks, so the checks are lost and recreated with new IDs and no result history.

Verification

Tested on a local instance of the product with the published provider (v1.32.0, run with OpenTofu):

  • Migration steps: the group and both checks stayed in place, the plan showed only an in-place update of the group, and the next plan was empty.
  • Changing only the resource type: Terraform destroyed the old group first, both checks were deleted with it, and the next plan recreated them.
  • Deleting a group through the public API and through the app also deleted its checks.
  • Examples: all three on the page validate and apply.

Checks

frontmatter, anchors, internal links, redirects, sitemap and mint broken-links: all pass.

🤖 Generated with Claude Code

…tion

Recommend checkly_check_group_v2 with enforce_* blocks, document a
migration from checkly_check_group that keeps the group and its checks
(state rm + import), and warn that deleting a group deletes its checks.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@mintlify

mintlify Bot commented Nov 7, 2026 •

Copy link
Copy Markdown
Contributor

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated
checkly-422f444a 🟢 Ready View Preview Nov 7, 2026, 9:13 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

@hlenke hlenke left a comment

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Needs changes · The v2 content is accurate and the migration steps match the provider, but the other Terraform pages still show only checkly_check_group, so a reader who follows this page's advice gets examples that don't fit; update them in this PR or link a follow-up.

Every claim I could check against source holds. The checkly_check_group_v2 attributes and blocks in both examples exist in the provider schema, the import is a plain numeric-ID passthrough, groups v2 shipped in provider v1.20.0, and the public API and web app delete a group's checks together with the group.

Not tied to a line

  • Important: sibling Terraform pages still describe v1 groups only. This page now tells readers to use checkly_check_group_v2, but:

    • integrations/iac/terraform/alerting.mdx lines 50 and 117 set alert_settings and alert_channel_subscription directly on a checkly_check_group. On a v2 group these belong inside enforce_alert_settings, and copying the top-level blocks into a v2 resource fails validation.
    • integrations/iac/terraform/environment-variables.mdx line 44 uses checkly_check_group.
    • integrations/iac/terraform/troubleshooting.mdx line 18 and the last section say group-level locations and alert subscriptions always override the check's. That holds only for v1 and for v2 groups with the matching enforce_* block.

    Either switch these to v2, with the same "v1 always overrides" caveat used here, or say in the PR description that a follow-up handles them.

  • FYI, outside this PR: the API reference page Delete a check group (api-reference/check-groups/delete-a-check-group.mdx, from api-reference/openapi.json) says a group can't be deleted while it still contains checks. That contradicts this PR, admin/team-management/permissions.mdx line 50, ai/mcp-server/tools.mdx line 119, and the source: the public API's delete deletes the checks first (monorepo apps/backend/api/src/modules/public-api/check-groups/check-group-write-service.ts). The spec text comes from the API's own description strings (apps/backend/api/src/modules/public-api/notes.ts), so the fix belongs in the API, not in this PR.

  • CI and merge state: all checks pass. The PR is mergeable (CLEAN), and main hasn't touched either file since the merge base.

  • Overlap: draft #774 (sentence case) changes headings in both files. This PR adds headings but doesn't edit existing ones, so whichever lands second has at most a small rebase.

Inline comments

1 important, 3 wording.

What I checked
  • Read the full diff from merge base 7da4a043 to head 89ee50d1 (2 files), plus the whole PR version of both pages.
  • Provider schema: terraform-provider-checkly origin/main@91c35ba, checkly/resource_check_group_v2.go and docs/resources/check_group_v2.md:
    • name is required; activated, muted and concurrency are optional.
    • The four enforce_* blocks exist, each with a required enabled.
    • enforce_locations.locations is valid.
    • The importer is ImportStatePassthroughContext on the numeric group ID.
    • On read, each enforce_* block is set to enabled when the group has that setting. When the config leaves a block out, CustomizeDiff plans it as enabled = false, which is why step 5 sees an in-place update.
  • Provider version: the v1.20.0 release notes list "add groups v2 support" (https://github.com/checkly/terraform-provider-checkly/releases/tag/v1.20.0). gh release view was refused, so I read the release page instead.
  • Group deletion: read monorepo origin/main@2d79b98589, apps/backend/api/src/modules/public-api/check-groups/check-group-write-service.ts. Deleting a group first deletes every check with that group ID, then the group, in one transaction, and its comment says this matches the web app. The delete route also needs checks:delete permission (apps/backend/api/src/modules/public-api/check-groups/routes.ts).
  • terraform state rm only removes the binding and doesn't destroy the object: https://developer.hashicorp.com/terraform/cli/commands/state/rm
  • Destroy-first on a type change: I couldn't verify it here, because the local app wasn't started for this run. It's consistent with Terraform treating the two resource types as separate addresses, and with the PR's own test notes.
  • Siblings: searched the Terraform integration pages for check_group and group_id (alerting, environment-variables, troubleshooting). Checked constructs/check-group-v2.mdx and the Pulumi pages: neither says anything about deleting a group, so nothing contradicts this PR.
  • Placement: the new ### sections land after Adding checks to groups and before the registry link, which is the right place for them. The note on platform/groups.mdx sits in Check membership, next to the related warning.
  • pr_impact.py flagged only that the edited registry-link line is a near-duplicate of the closing lines in dashboards.mdx and maintenance-windows.mdx. Those are unrelated boilerplate, so no action is needed.
  • gh pr checks 795, gh pr view 795 --json mergeable,mergeStateStatus, git log on the touched files since the merge base, and the diff of #774 on both files.
  • No end-to-end test: the local app wasn't started for this run, and the claims are about the Terraform provider, which the e2e harness doesn't drive.

## Groups

Once you start having more than just a handful of checks, it makes sense to start looking into [groups](/platform/groups) to keep things tidy:
Once you start having more than just a handful of checks, it makes sense to start looking into [groups](/platform/groups) to keep things tidy. Use the `checkly_check_group_v2` resource (available since provider version 1.20.0). A v2 group doesn't override any settings of its checks unless you ask it to, so it can be as simple as a name:

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wording · New prose avoids parentheticals, and the version reads better as its own sentence.

Suggested change
Once you start having more than just a handful of checks, it makes sense to start looking into [groups](/platform/groups) to keep things tidy. Use the `checkly_check_group_v2` resource (available since provider version 1.20.0). A v2 group doesn't override any settings of its checks unless you ask it to, so it can be as simple as a name:
Once you start having more than just a handful of checks, it makes sense to start looking into [groups](/platform/groups) to keep things tidy. Use the `checkly_check_group_v2` resource, available since provider version 1.20.0. A v2 group doesn't override any settings of its checks unless you ask it to, so it can be as simple as a name:

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

', available since provider version 1.20.0' drop this

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Dropped in a86cd8e. The sentence is now: Use the checkly_check_group_v2 resource.

</Warning>

You can see all the configuration options for groups, as well as more examples, on the official Terraform registry [documentation page](https://registry.terraform.io/providers/checkly/checkly/latest/docs/resources/check_group).
You can see all the configuration options for groups, as well as more examples, on the Terraform registry documentation pages for [`checkly_check_group_v2`](https://registry.terraform.io/providers/checkly/checkly/latest/docs/resources/check_group_v2) and [`checkly_check_group`](https://registry.terraform.io/providers/checkly/checkly/latest/docs/resources/check_group).

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wording · This paragraph now sits under Deleting a group, where it reads as part of that warning. Move it to the end of the ## Groups intro, after "See migrating to checkly_check_group_v2 below.", where it points readers to the full v2 options. Optional: since you rewrote the blockquote on line 296, it could also become a <Note>, because the editing rules avoid > callouts.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

move it as suggested

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Moved to the end of the Groups intro, right after the link to the migration section, in a86cd8e. I left the blockquote as is.

…ntro

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@hlenke
hlenke merged commit 3abcc8c into main Nov 7, 2026
6 checks passed
@hlenke
hlenke deleted the docs/terraform-check-group-v2 branch November 7, 2026 21:26

This branch was successfully deployed

1 active deployment
staging — a86cd8e8 Deployed Nov 7, 2026 by mintlify[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant