docs: add Terraform drift detection tutorial#300
Conversation
|
Claude finished @gsavage's task in 2m 22s —— View job Review of PR #300 — Terraform drift detection tutorials
SummaryThis PR replaces the single hands-on What looks good
Remaining findingsAll minor — nothing blocking.
VerdictSolid restructuring. The two pages are well-written, cross-linked, and correctly wired into nav and redirects. Previous review feedback has been incorporated. No critical or blocking issues remain. |
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
Makes the caller workflow snippet a complete, copy-pasteable file, matching the sibling example in detecting_non_terraform_changes.mdx.
The latest implementation avoids the race entirely, so the caveat no longer applies.
authorized-iac-change.png and unauthorized-iac-change.png were only used in the outdated drift detection page deleted earlier on this branch.
| @@ -0,0 +1,134 @@ | |||
| --- | |||
| title: Detecting unexpected statefile changes | |||
| description: Detect Terraform applies that bypass CI by attesting statefile provenance into a Kosli Environment — the class of drift a scheduled plan can never see. | |||
There was a problem hiding this comment.
Suggestion: Same as the sibling page — an icon field in frontmatter (e.g. icon: "file-shield") would add visual polish in the nav.
| <Tooltip tip="Drift occurs when infrastructure diverges from the desired state defined in your version-controlled Terraform config.">Terraform drift</Tooltip> comes in two distinct types, and each is invisible to a detector built for the other: | ||
|
|
||
| 1. **Unexpected statefile changes** — someone runs `terraform apply` outside your pipeline, so the statefile and the world still agree and a plan comes back empty. See [Detecting unexpected statefile changes](/tutorials/detecting_unexpected_statefile_changes). | ||
| 2. **Non-Terraform changes** — someone edits the world directly via the cloud console, API, or CLI: a hotfix in the console, a partial apply failure, an out-of-band automation. Reality no longer matches the statefile, so a `terraform plan` catches it. This page covers detecting this type. | ||
|
|
||
| Both pages implement Kosli's [Drift Detection](https://sdlc.kosli.com/controls/runtime/drift_detection/) control (SDLC-CTRL-0018), a detective control that mitigates configuration drift risk under our secure SDLC framework. |
There was a problem hiding this comment.
Suggestion: The intro block (lines 6–11) is nearly identical across both new pages. Fine for standalone reading, but if maintenance surface is a concern, a snippets/ fragment could DRY it up. Minor — the cross-referencing is well done either way.
| { | ||
| "source": "/tutorials/terraform_drift_detection", | ||
| "destination": "/tutorials/detecting_non_terraform_changes" | ||
| }, |
There was a problem hiding this comment.
Improvement: The redirect from the intermediate URL (/tutorials/terraform_drift_detection) lands on the "non-Terraform changes" page. A reader who bookmarked the old single-page tutorial might expect to see the statefile-provenance content too. Consider whether a short landing page or a redirect to a parent group would be friendlier — or at minimum, the target page's intro already cross-links to the sibling, which mitigates this. Noting for awareness.
2 participants
Adds a new tutorial covering Terraform drift detection with Kosli, based on the source Google Doc.
What's new
tutorials/terraform_drift_detection.mdx— full tutorial covering:kosli-dev/tfreference wrapper and reusable workflowsLive page will be at
/tutorials/terraform_drift_detection.Generated by Mintlify Agent.
Requested by: graham@kosli.com via Slack
Mintlify session: slack_1775036725.228749_D0AM66349C1