terragrunt-skill

Terragrunt Infrastructure Skill

Overview

This skill provides guidance for infrastructure using Terragrunt with OpenTofu, following a three-repository pattern:

1. Infrastructure Catalog - Units and stacks that reference modules from separate repos
2. Infrastructure Live - Environment-specific deployments consuming the catalog
3. Module Repos - Separate repositories for each OpenTofu module (independent versioning)

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
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
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
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
}

Reference Resolution

Units resolve symbolic references like "../acm" to dependency outputs:

inputs = {
  acm_certificate_arn = try(values.acm_certificate_arn, "") == "../acm" ?
    dependency.acm.outputs.acm_certificate_arn :
    values.acm_certificate_arn
}

Module Sourcing

Units reference modules via Git URL with version from values:

terraform {
  source = "git::[email protected]:YOUR_ORG/modules/rds.git//app?ref=${values.version}"
}

Common Operations

Create New Unit

1. Create units/<name>/terragrunt.hcl
2. Reference module via Git URL with ${values.version}
3. Use values.xxx for inputs
4. Add dependencies with mock outputs
5. Implement reference resolution for "../unit" patterns

Create New Stack

1. Create stacks/<name>/terragrunt.stack.hcl
2. Define locals for computed values
3. Add unit blocks referencing catalog units
4. Pass values including version and dependency paths

Deploy to New Environment

1. Create environment directory structure
2. Add env.hcl with state_bucket_suffix
3. Run terragrunt run --all -- backend bootstrap to create state resources
4. Add stack files referencing catalog

Best Practices

1. Pin module versions - Use Git tags in values.version
2. Pin catalog versions - Use refs in unit source URLs
3. Use reference resolution - "../unit" → dependency outputs
4. Provide mock outputs - Enable plan/validate without dependencies
5. Auto-detect features - length(keys(try(values.X, {}))) > 0
6. Override paths - try(values.X_path, "../default")
7. Separate state per environment - Use state_bucket_suffix

Common Pitfalls

1. Git refspec error - Use //path?ref=branch NOT ?ref=branch//path
2. Heredoc in ternary - Wrap in parentheses: condition ? (\n<<-EOF\n...\nEOF\n) : ""
3. Missing mock outputs - Always provide for plan/validate
4. Hardcoded paths - Use local paths only for testing

Version Management

• Development: Branch refs (ref=feature-branch)
• Testing: RC tags (ref=v1.0.0-rc1)
• Production: Stable tags (ref=v1.0.0)