
terragrunt-skill
Use when working with Terragrunt (0.68 to 1.2; OpenTofu or Terraform) - stacks, units, catalogs, expansion, dependencies, remote state, CAS/OCI sources, version upgrades, CI/CD pipelines (GitLab CI, GitHub Actions), AWS/GCP OIDC, performance, multi-account deployments
- version
- 3.0.0
- GitHub stars
- 29
Install
/plugin install terragrunt-skill@jfr992Run it inside Claude Code after adding the marketplace with /plugin marketplace add jfr992/terragrunt-skill.
Contents
Discovered from sourceSkills 1
Terragrunt Infrastructure Skill
Overview
This skill provides guidance for infrastructure using Terragrunt with OpenTofu, following a three-repository pattern:
- Infrastructure Catalog - Units and stacks that reference modules from separate repos
- Infrastructure Live - Environment-specific deployments consuming the catalog
- Module Repos - Separate repositories for each OpenTofu module (independent versioning)
Step 0: Detect Versions
Before giving commands, check terragrunt --version, .terragrunt-version, mise.toml/.tool-versions, terragrunt_version_constraint in root.hcl, and whether tofu or terraform is installed. This skill defaults to TG 1.2 + OpenTofu ≥ 1.10. For older Terragrunt (0.68+), Terraform, or classic layouts, follow version-compatibility.md: use run-all/--terragrunt-* on < 0.77.22, classic layouts on < 0.78, no autoinclude on < 1.1, no expansion on < 1.2, and no state encryption on Terraform.
Choosing an Architecture
Default recommendation: explicit stacks — the catalog + terragrunt.stack.hcl + values pattern this skill teaches. Units are generated from stack files; configuration flows through values; no per-unit boilerplate.
Supported alternative: classic implicit stacks — the original Gruntwork pattern: account/region/env/component directory hierarchy, per-level .hcl variable files, shared component config in _envcommon/ via include + expose. Any directory of units is an implicit stack. Use it when the repo already follows it, when the footprint is too small to justify a catalog, or when the team isn't ready for stacks. See classic-live-structure.md.
Orthogonal choice: module organization — modules monorepo (modules/ + examples/, one tag versions all, //modules/x?ref= sourcing) vs module-per-repo (independent versioning). Either works with either architecture. See modules-monorepo.md.
Migrating classic → stacks: follow the official Terralith to Terragrunt guide.
Quick Navigation
| Topic | Reference |
|---|---|
| Version compatibility (TG 0.68→1.2, OpenTofu vs Terraform) | version-compatibility.md |
| Naming conventions | naming.md |
| Catalog structure | catalog-structure.md |
| Live repo structure | live-structure.md |
| Classic live structure (implicit stacks) | classic-live-structure.md |
| Modules monorepo | modules-monorepo.md |
| Discovery commands (find/list/dag) | discovery-commands.md |
| Root/account/env configs | root-config.md |
| Unit dependencies | dependencies.md |
| Expansion (for_each/count) | expansion.md |
| Catalog scaffolding | catalog-scaffolding.md |
| Stack commands | stack-commands.md |
| Patterns & best practices | patterns.md |
| State management | state-management.md |
| Multi-account setup | multi-account.md |
| Performance optimization | performance.md |
| Content Addressable Store (CAS) | cas.md |
| CI/CD pipelines (shared + IAM/OIDC setup) | cicd-pipelines.md |
| GitLab CI pipelines | cicd-gitlab.md |
| GitHub Actions pipelines | cicd-github.md |
Core Concepts
Values Pattern
Units receive configuration through values.xxx:
inputs = {
name = values.name
environment = values.environment
instance_class = try(values.instance_class, "db.t3.medium") # Optional with default
}
Dependency Wiring (autoinclude first)
Since Terragrunt 1.1, declare dependencies in the stack file with autoinclude so catalog units stay dependency-agnostic. See dependencies.md for the full pattern.
Reference Resolution (legacy)
Older catalogs resolve symbolic references like "../acm" to dependency outputs inside the unit:
inputs = {
acm_certificate_arn = try(values.acm_certificate_arn, "") == "../acm" ?
dependency.acm.outputs.acm_certificate_arn :
values.acm_certificate_arn
}
Keep it when maintaining an existing catalog; prefer autoinclude for new work.
Module Sourcing
Units reference modules via Git URL with version from values:
terraform {
source = "git::git@github.com:YOUR_ORG/modules/rds.git//app?ref=${values.version}"
}
For catalog-internal references (units/stacks/modules in the same repo), Terragrunt 1.1+ allows plain relative paths with update_source_with_cas = true — stack generate rewrites them to content-addressed references, so no URL pinning or version plumbing is needed. See cas.md.
Common Operations
Create New Unit
- Create
units/<name>/terragrunt.hcl - Reference module via Git URL with
${values.version} - Use
values.xxxfor inputs - Add dependencies with mock outputs
- Wire dependencies via
autoincludein the stack (legacy:"../unit"reference resolution)
Create New Stack
- Create
stacks/<name>/terragrunt.stack.hcl - Define
localsfor computed values - Add
unitblocks referencing catalog units - Pass values including version and dependency paths
Deploy to New Environment
- Create environment directory structure
- Add
env.hclwithstate_bucket_suffix - Add stack files referencing catalog and run
terragrunt stack generate - Run
terragrunt backend bootstrap --allto create state resources (or pass--backend-bootstrapon the first run). Do not userun --all -- backend bootstrap: everything after--goes to OpenTofu/Terraform.
Best Practices
- Pin module versions - Use Git tags in
values.version - Pin catalog versions - Use refs in unit source URLs
- Wire dependencies with autoinclude - legacy
"../unit"resolution only in existing catalogs - Provide mock outputs - Enable plan/validate without dependencies
- Auto-detect features -
length(keys(try(values.X, {}))) > 0 - Override paths -
try(values.X_path, "../default") - Separate state per environment - Use
state_bucket_suffix
Common Pitfalls
- Git refspec error - Use
//path?ref=branchNOT?ref=branch//path - Heredoc in ternary - Wrap in parentheses:
condition ? (\n<<-EOF\n...\nEOF\n) : "" - Missing mock outputs - Always provide for plan/validate
- Hardcoded paths - Use local paths only for testing
Upgrading to 1.2
base64gzip()output changed - may force resource replacement;base64gzip_compatexists as an experiment.- Generated files are read-only - stored in CAS as links; set
mutable = trueon agenerateblock that must be edited (see cas.md). - S3 bootstrap no longer adds a root-access bucket policy - set
enable_bucket_root_access = trueif you relied on it. - Dependency outputs read from state by default - S3/GCS/azurerm; encrypted state and other backends fall back to
output; opt out with--no-dependency-fetch-output-from-state(see performance.md).
Docs Lookup
Prefer the Terragrunt docs MCP server https://mcp.docs.terragrunt.com/mcp (public beta) when available; otherwise https://docs.terragrunt.com.
Version Management
- Development: Branch refs (
ref=feature-branch) - Testing: RC tags (
ref=v1.0.0-rc1) - Production: Stable tags (
ref=v1.0.0)
Sponsors
Details
- Marketplace
- jfr992/terragrunt-skill
- Category
- Development
- Keywords
- terragrunt, opentofu, terraform, infrastructure-as-code, stacks, units, aws, gcp, ci-cd