docs: document EXPERIMENT_AUTO_UNLOCK_STATE_LOCK#3083
Open
ZachGoldberg wants to merge 2 commits into
Open
Conversation
Documents the new Pipelines experiment that automatically force-unlocks a stale Terraform/OpenTofu state lock when an AWS session timeout causes the lock-release step to fail mid-apply. Currently single-unit only (no run --all support). Default OFF.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Repository UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
✅ Files skipped from review due to trivial changes (1)
WalkthroughDocuments a new feature flag, Changes
Sequence Diagram(s)sequenceDiagram
autonumber
participant Pipelines
participant Terragrunt
participant AWS_StateBackend
Pipelines->>Terragrunt: run apply (original credentials)
Terragrunt->>AWS_StateBackend: attempt release state lock
AWS_StateBackend-->>Terragrunt: Error releasing the state lock + ExpiredTokenException
Terragrunt-->>Pipelines: return apply error (original)
Pipelines->>Terragrunt: run terragrunt plan -- -lock-timeout=0s with fresh creds
Terragrunt->>AWS_StateBackend: detect stale lock ID
Terragrunt->>AWS_StateBackend: terragrunt force-unlock (clear lock)
Terragrunt-->>Pipelines: recovery attempted (apply error still returned)
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
2 tasks
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
🧹 Nitpick comments (3)
docs/2.0/reference/pipelines/feature-flags.md (3)
129-133: Consider adding a safety warning about force-unlock.Force-unlocking state locks is a powerful operation that, if misused, can lead to state corruption if multiple operations run concurrently. While the feature is designed to handle a specific safe scenario (expired AWS session), users should understand the risks.
Suggested note to add: "Note: This feature only unlocks when it's safe to do so (when the session that held the lock has expired). Manual force-unlock operations should be used with caution."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/2.0/reference/pipelines/feature-flags.md` around lines 129 - 133, Add a concise safety warning after the paragraph that describes automatic force-unlock (the list item mentioning "terragrunt plan -- -lock-timeout=0s" and "terragrunt force-unlock") clarifying that force-unlocking is powerful and can corrupt state if used during concurrent operations; include the suggested sentence: "Note: This feature only unlocks when it's safe to do so (when the session that held the lock has expired). Manual force-unlock operations should be used with caution." and ensure the note also reiterates that the feature only applies to single-unit commands and is not supported with "run --all".
129-130: Consider restructuring for better readability.The main description is a single complex sentence covering detection logic, workflow steps, and behavior. Breaking this into a bulleted list or shorter sentences would improve clarity for users.
Example structure:
- When it activates: Detects both
Error releasing the state lockandExpiredTokenExceptionin apply output- What it does: Automatically runs
terragrunt plan -- -lock-timeout=0swith fresh credentials to identify the lock ID, then runsterragrunt force-unlockto clear it- Important: The original apply error is still returned; the unlock only clears the lock for the next run
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/2.0/reference/pipelines/feature-flags.md` around lines 129 - 130, Split the long single-sentence description into a short, clear bulleted or multi-sentence structure: create a "When it activates" line referencing the detection of both "Error releasing the state lock" and "ExpiredTokenException" in apply output, a "What it does" line describing that Pipelines runs `terragrunt plan -- -lock-timeout=0s` with fresh credentials to discover the stale lock ID and then runs `terragrunt force-unlock` to release it, and an "Important" note stating that the original apply error is still returned and the unlock only clears the lock for the next run; keep the existing terms ("terragrunt plan -- -lock-timeout=0s", "terragrunt force-unlock", "Error releasing the state lock", "ExpiredTokenException") so readers can easily match the behavior to the implementation.
130-130: Clarify that this detection is AWS-specific.The feature detects
ExpiredTokenException, which is specific to AWS session timeouts. Consider noting this explicitly so users with other cloud providers (GCP, Azure) or local backends understand the scope.Suggested addition: "This detection is specific to AWS session timeouts; similar lock issues with other providers will not trigger automatic unlock."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/2.0/reference/pipelines/feature-flags.md` at line 130, Update the feature description in docs/2.0/reference/pipelines/feature-flags.md to explicitly state the detection is AWS-specific: add a clarifying sentence after the paragraph that mentions ExpiredTokenException (e.g., "This detection is specific to AWS session timeouts; similar lock issues with other providers will not trigger automatic unlock.") so readers using GCP, Azure, or local backends understand the limitation; ensure the new sentence references the existing mention of ExpiredTokenException and the terragrunt force-unlock flow.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@docs/2.0/reference/pipelines/feature-flags.md`:
- Around line 129-133: Add a concise safety warning after the paragraph that
describes automatic force-unlock (the list item mentioning "terragrunt plan --
-lock-timeout=0s" and "terragrunt force-unlock") clarifying that force-unlocking
is powerful and can corrupt state if used during concurrent operations; include
the suggested sentence: "Note: This feature only unlocks when it's safe to do so
(when the session that held the lock has expired). Manual force-unlock
operations should be used with caution." and ensure the note also reiterates
that the feature only applies to single-unit commands and is not supported with
"run --all".
- Around line 129-130: Split the long single-sentence description into a short,
clear bulleted or multi-sentence structure: create a "When it activates" line
referencing the detection of both "Error releasing the state lock" and
"ExpiredTokenException" in apply output, a "What it does" line describing that
Pipelines runs `terragrunt plan -- -lock-timeout=0s` with fresh credentials to
discover the stale lock ID and then runs `terragrunt force-unlock` to release
it, and an "Important" note stating that the original apply error is still
returned and the unlock only clears the lock for the next run; keep the existing
terms ("terragrunt plan -- -lock-timeout=0s", "terragrunt force-unlock", "Error
releasing the state lock", "ExpiredTokenException") so readers can easily match
the behavior to the implementation.
- Line 130: Update the feature description in
docs/2.0/reference/pipelines/feature-flags.md to explicitly state the detection
is AWS-specific: add a clarifying sentence after the paragraph that mentions
ExpiredTokenException (e.g., "This detection is specific to AWS session
timeouts; similar lock issues with other providers will not trigger automatic
unlock.") so readers using GCP, Azure, or local backends understand the
limitation; ensure the new sentence references the existing mention of
ExpiredTokenException and the terragrunt force-unlock flow.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro
Run ID: def7d86e-a78c-49e0-bfd5-f857b879a278
📒 Files selected for processing (1)
docs/2.0/reference/pipelines/feature-flags.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
PIPELINES_FEATURE_EXPERIMENT_AUTO_UNLOCK_STATE_LOCK.Related
Summary by CodeRabbit