Directory Structure

A well-organized directory layout simplifies management of Terraform configurations with Terragrunt, promotes reuse, and makes environment-specific customizations straightforward.

Key Components

Example Directory Tree

.
├── terragrunt.hcl              # Global Terragrunt configuration
├── modules                     # Reusable Terraform modules
│   ├── app
│   │   ├── main.tf
│   │   └── variables.tf
│   └── mysql
│       ├── main.tf
│       └── variables.tf
└── envs                        # Environment-specific configurations
    ├── dev
    │   ├── account.hcl         # Dev account ID, region, etc.
    │   ├── common-vars.hcl     # Shared dev variables
    │   ├── app
    │   │   └── terragrunt.hcl  # Inherits root, adds app settings
    │   └── mysql
    │       └── terragrunt.hcl  # Inherits root, adds MySQL settings
    └── prod
        ├── account.hcl         # Prod account ID, region, etc.
        ├── common-vars.hcl     # Shared prod variables
        ├── app
        │   └── terragrunt.hcl
        └── mysql
            └── terragrunt.hcl

How It Works

1. Global Settings
   The root terragrunt.hcl provides defaults for all modules and environments:

   • Remote state backend configuration
   • Shared providers
   • Pre/post hooks for automation

   Note

   Define secure and centralized remote state backends in your root file to maintain state consistency across teams.

2. Environment Overrides
   Each environment directory (envs/dev, envs/prod) contains:

   • account.hcl for environment-specific parameters (account IDs, AWS region, etc.)
   • common-vars.hcl to share variable values among all components

3. Component-Specific Configuration
   Inside envs/<environment>/<component>/terragrunt.hcl you:

   • Include both the root configuration and the environment’s account.hcl
   • Reference the corresponding module from modules/<component>
   • Override or supplement module inputs as needed

4. Shared Variables
   Use common-vars.hcl to avoid repetition:

   inputs = {
     project_name = "example"
     tags = {
       owner = "team-infra"
     }
   }
   

   Warning

   Avoid duplicating variables across component configs. Centralize values in common-vars.hcl to prevent drift.

Benefits

• Modularity: Break infrastructure into reusable modules.
• Clarity: Isolate environment-specific settings from shared defaults.
• Scalability: Easily add new environments or components without refactoring existing code.

Links and References

• Terragrunt Documentation
• Terraform Modules
• Terraform Remote State