jfr992

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"