Terragrunt Skill for Claude Code

A Claude Code skill providing best practices guidance for Terragrunt infrastructure-as-code with OpenTofu/Terraform.

Architecture

Important: Catalog and Live repositories should be separate Git repositories. The live repo consumes units and stacks from the catalog via Git URLs.

Option A: Modules in Separate Repos

┌─────────────────────────────────────────────────────────────────────┐
│                        SEPARATE REPOSITORIES                         │
├─────────────────────────┬─────────────────────────┬─────────────────┤
│   Module Repos          │   Catalog Repo          │   Live Repo     │
│   (terraform-aws-*)     │   (infrastructure-      │   (infrastructure-
│                         │    <org>-catalog)       │    <org>-live)  │
├─────────────────────────┼─────────────────────────┼─────────────────┤
│ • OpenTofu modules      │ • units/ (wrappers)     │ • root.hcl      │
│ • Semantic versioning   │ • stacks/ (templates)   │ • account.hcl   │
│ • Terratest             │ • References modules    │ • Deployments   │
│ • Pre-commit hooks      │   via Git URLs          │ • Consumes      │
│                         │                         │   catalog       │
└─────────────────────────┴─────────────────────────┴─────────────────┘
         ▲                         ▲                        │
         │                         │                        │
         └─────────────────────────┴────────────────────────┘
                    Live repo references both via Git URLs

Option B: Modules in Catalog

┌───────────────────────────────────────────────────────────────┐
│                    SEPARATE REPOSITORIES                       │
├─────────────────────────────────┬─────────────────────────────┤
│   Catalog Repo                  │   Live Repo                 │
│   (infrastructure-<org>-catalog)│   (infrastructure-<org>-live)
├─────────────────────────────────┼─────────────────────────────┤
│ • modules/ (OpenTofu modules)   │ • root.hcl                  │
│ • units/ (module wrappers)      │ • account.hcl               │
│ • stacks/ (unit compositions)   │ • Deployments               │
│ • Discovered via `tg catalog`   │ • Consumes catalog via Git  │
│ • Single versioning strategy    │ • `tg scaffold` for new     │
└─────────────────────────────────┴─────────────────────────────┘
                ▲                              │
                └──────────────────────────────┘
                  Live repo references catalog

Trade-offs:

Aspect	Option A (Separate Module Repos)	Option B (Modules in Catalog)
Versioning	Independent per module	Single catalog version
CI/CD	Dedicated pipeline per module	One pipeline for all
Complexity	More repos to manage	Simpler structure
Team ownership	Clear boundaries	Shared ownership
`terragrunt catalog`	Discovers units/stacks	Discovers modules too

Features

Catalog & Live Pattern

Infrastructure Catalog: Reusable units and template stacks (separate repo)
Infrastructure Live: Environment-specific deployments consuming the catalog
Module Repos: Separate repositories with semantic versioning

Unit & Stack Patterns

Values pattern for configuration injection
Reference resolution ("../unit" → dependency outputs)
Unit interdependencies with mock outputs
Conditional dependencies with enabled and skip_outputs

CI/CD Pipelines

GitLab CI with reusable templates
GitHub Actions workflows
AWS OIDC authentication (assume-role-with-web-identity)
GCP Workload Identity Federation
SSH-based Git access (recommended over HTTPS)

Performance Optimization

Provider caching (--provider-cache)
Two-layer caching architecture (local + network mirror)
Benchmarking tools (Hyperfine, boring-registry)
Explicit stacks for 2x faster runs

Multi-Account Deployments

Cross-account role assumption
Environment-based state bucket separation
Hierarchical configuration (root.hcl → account.hcl → region.hcl → env.hcl)

Installation

This skill is distributed via Claude Code marketplace using .claude-plugin/marketplace.json.

Claude Code (Recommended)

/plugin marketplace add jfr992/terragrunt-skill
/plugin install terragrunt-skill@jfr992

Manual Installation

# Clone to Claude skills directory
git clone https://github.com/jfr992/terragrunt-skill.git ~/.claude/skills/terragrunt-skill

Verify Installation

After installation, try:

"Create a Terragrunt stack for a serverless API with Lambda, DynamoDB, and S3"

Claude will automatically use the skill when working with Terragrunt code.

Quick Start

1. Create a Catalog Repository

# Ask Claude to scaffold a new catalog
"Create a new infrastructure catalog with units for S3, DynamoDB, and Lambda"

This generates:

infrastructure-catalog/
├── units/
│   ├── s3/terragrunt.hcl           # Wraps terraform-aws-s3 module
│   ├── dynamodb/terragrunt.hcl     # Wraps terraform-aws-dynamodb module
│   └── lambda/terragrunt.hcl       # Wraps terraform-aws-lambda module
└── stacks/
    └── serverless-api/terragrunt.stack.hcl  # Combines units

2. Create a Live Repository

# Ask Claude to scaffold a live repo
"Create a live infrastructure repo for AWS with staging environment"

This generates:

infrastructure-live/
├── root.hcl                        # Provider, backend, catalog config
├── non-prod/
│   ├── account.hcl                 # AWS account config
│   └── us-east-1/
│       ├── region.hcl
│       └── staging/
│           ├── env.hcl             # Environment config
│           └── my-api/
│               └── terragrunt.stack.hcl  # Deployment (references catalog)

3. Deploy

cd infrastructure-live/non-prod/us-east-1/staging/my-api

# Plan the stack
terragrunt stack run plan

# Apply the stack
terragrunt stack run apply

# Target specific unit using filters (recommended)
terragrunt stack run apply --filter '.terragrunt-stack/dynamodb'

# Target unit and its dependencies
terragrunt stack run apply --filter '.terragrunt-stack/lambda...'

See Terragrunt Filters for advanced filtering options.

Usage

The skill activates when working with:

terragrunt.hcl files (units)
terragrunt.stack.hcl files (stacks)
root.hcl configuration
Terragrunt CLI commands

Example Prompts

"Create a new EKS stack with Karpenter and ArgoCD registration"
"Set up a serverless API with Lambda, DynamoDB, and S3"
"Add GitLab CI pipeline with GCP Workload Identity"
"Optimize Terragrunt performance with provider caching"

Test Output (Examples)

The test-output/ directory contains example files generated using this skill, demonstrating the recommended patterns:

test-output/
├── catalog/                    # Example catalog repo structure
│   ├── units/
│   │   ├── s3/terragrunt.hcl
│   │   ├── dynamodb/terragrunt.hcl
│   │   └── lambda/terragrunt.hcl
│   └── stacks/
│       ├── serverless-api/terragrunt.stack.hcl
│       └── eks-cluster/terragrunt.stack.hcl
└── live/                       # Example live repo structure
    ├── root.hcl
    └── non-prod/
        ├── account.hcl
        └── us-east-1/
            ├── region.hcl
            └── staging/
                ├── env.hcl
                └── my-api/terragrunt.stack.hcl

Note: In production, catalog/ and live/ would be separate Git repositories. They are combined here for demonstration purposes only.

Documentation Structure

File	Description
`skills/terragrunt-skill/SKILL.md`	Core skill documentation
`test-output/`	Example output generated by this skill
`skills/terragrunt-skill/references/cicd-pipelines.md`	GitLab CI & GitHub Actions templates
`skills/terragrunt-skill/references/patterns.md`	Repository separation, pre-commit, semantic-release
`skills/terragrunt-skill/references/performance.md`	Caching, benchmarking, optimization
`skills/terragrunt-skill/references/state-management.md`	S3/DynamoDB backend patterns
`skills/terragrunt-skill/references/multi-account.md`	Cross-account deployment patterns

Compatibility

Terragrunt 0.68+
OpenTofu 1.6+ / Terraform 1.5+
AWS, GCP (authentication patterns)

Contributing

See CLAUDE.md for contributor guidelines and repository architecture.

State Backend Bootstrap

Terragrunt can automatically create state backend resources (S3 bucket with native lockfile) when you run any command:

# root.hcl
remote_state {
  backend = "s3"
  config = {
    bucket       = "tfstate-${local.account_name}-${local.aws_region}"
    key          = "${path_relative_to_include()}/terraform.tfstate"
    region       = local.aws_region
    encrypt      = true
    use_lockfile = true
  }
  generate = {
    path      = "backend.tf"
    if_exists = "overwrite_terragrunt"
  }
}

Terragrunt automatically provisions the S3 bucket (with versioning, encryption, access logging) if it doesn't exist. Native S3 lockfile (OpenTofu >= 1.10) replaces the need for a DynamoDB lock table.

See State Backend for details.

Platform Engineering & Self-Service

Catalog Discovery

The terragrunt catalog command enables self-service infrastructure by letting teams browse and scaffold from your catalog:

# Browse available modules, units, and stacks
terragrunt catalog

# Scaffold a specific unit
terragrunt scaffold git@github.com:YOUR_ORG/infrastructure-catalog.git//units/rds

Boilerplate Templates

Boilerplate powers the scaffolding with interactive prompts:

# units/rds/boilerplate.yml
variables:
  - name: instance_class
    description: "RDS instance class"
    type: string
    default: "db.t3.medium"

  - name: engine_version
    description: "Database engine version"
    type: string
    default: "15.4"

When users run terragrunt scaffold, they're prompted for these values, generating a pre-configured terragrunt.hcl.

Self-Service Portal Integration

The scaffold command can be integrated with internal developer platforms:

# API endpoint calls scaffold with predefined values
terragrunt scaffold \
  git@github.com:YOUR_ORG/infrastructure-catalog.git//units/rds \
  --var instance_class=db.r5.large \
  --var engine_version=15.4 \
  --output-folder /deployments/team-a/rds

This enables:

Standardized deployments across teams
Governance via catalog-level policies
Reduced toil through automated configuration
Version control with automatic Git tag resolution

References

License

Apache 2.0

Name		Name	Last commit message	Last commit date
Latest commit History 52 Commits
.claude-plugin		.claude-plugin
.github/workflows		.github/workflows
evaluations		evaluations
skills/terragrunt-skill		skills/terragrunt-skill
test-output		test-output
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation

Terragrunt Skill for Claude Code

Architecture

Option A: Modules in Separate Repos

Option B: Modules in Catalog

Features

Catalog & Live Pattern

Unit & Stack Patterns

CI/CD Pipelines

Performance Optimization

Multi-Account Deployments

Installation

Claude Code (Recommended)

Manual Installation

Verify Installation

Quick Start

1. Create a Catalog Repository

2. Create a Live Repository

3. Deploy

Usage

Example Prompts

Test Output (Examples)

Documentation Structure

Compatibility

Contributing

State Backend Bootstrap

Platform Engineering & Self-Service

Catalog Discovery

Boilerplate Templates

Self-Service Portal Integration

References

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 8

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages