terragrunt

Generate and show an execution plan

$ terragrunt plan

$ terragrunt apply

$ terragrunt show

$ terragrunt output

$ terragrunt destroy

$ terragrunt run-all apply

terragrunt [GLOBAL_OPTIONS] [COMMAND_OPTIONS]
terragrunt [COMMAND_OPTIONS] [PATH]

--terragrunt-non-interactive
    Global: Disables all interactive prompts, essential for automation and CI/CD pipelines.

--terragrunt-config
    Global: Specifies the path to the main terragrunt.hcl configuration file.

--terragrunt-source
    Global: Downloads Terraform code from a remote URL (e.g., Git repository) before execution.

--terragrunt-source-update
    Global: Forces Terragrunt to delete and re-download the Terraform source code.

--terragrunt-debug
    Global: Enables verbose debug logging, useful for troubleshooting issues.

--terragrunt-log-level
    Global: Sets the logging verbosity level (e.g., info, warn, error, debug).

--terragrunt-override-attr
    Global: Overrides a specific attribute within the terragrunt.hcl configuration file.

--terragrunt-fetch-dependencies
    Global: Ensures that all module dependencies are downloaded and processed before execution.

--terragrunt-ignore-dependency-errors
    Global: Allows run-all commands to continue execution even if a dependency module encounters an error.

apply
    Command: Executes terraform apply after Terragrunt has prepared the environment, creating or updating infrastructure.

plan
    Command: Executes terraform plan after Terragrunt setup, showing the planned infrastructure changes without applying them.

init
    Command: Initializes the Terraform working directory and configures the backend based on the terragrunt.hcl settings.

destroy
    Command: Executes terraform destroy after Terragrunt setup, to tear down Terraform-managed infrastructure.

run-all
    Command: Runs a specified Terragrunt command (apply, plan, destroy, etc.) across all modules in the current directory hierarchy, respecting dependencies.

hclfmt
    Command: Formats Terragrunt HCL configuration files to a consistent, canonical style.

validate-inputs
    Command: Checks if all required inputs for the current Terraform module are correctly defined and provided via Terragrunt.

terragrunt-info
    Command: Displays useful information about the current Terragrunt environment, including version, working directory, and parsed configuration.

Terragrunt is a thin wrapper for Terraform that provides extra tools for working with Terraform configurations. Its primary goal is to keep your Terraform code DRY (Don't Repeat Yourself) by allowing you to define common configurations, such as remote state, providers, and backend settings, just once at a higher level and then inherit them across multiple environments and modules.

It solves challenges related to orchestrating multiple Terraform modules, managing dependencies between them, and handling remote state configuration in a more robust and consistent manner. Terragrunt achieves this by dynamically generating Terraform configuration files, executing Terraform commands, and providing features like dependency management (running modules in the correct order), enforcing remote state configuration, and automating backend initialization. It aims to reduce boilerplate, improve maintainability, and ensure consistency across large infrastructure projects built with Terraform.

Terragrunt introduces an additional abstraction layer over Terraform, which can sometimes increase the learning curve for new users. Debugging issues might require understanding both Terragrunt's behavior and the underlying Terraform commands. Complex run-all orchestrations might require careful dependency management to avoid unexpected behavior or state inconsistencies. It is opinionated about directory structure, which might require adapting existing Terraform layouts.

These HCL-based files are the core of Terragrunt's configuration. They define how Terragrunt should interact with your Terraform modules, specifying properties like the source path of the Terraform code, input variables, remote state backend configurations, and explicit dependencies on other Terragrunt modules. They allow for powerful inheritance and variable interpolation.

Terragrunt's most significant benefit is its ability to enforce the Don't Repeat Yourself (DRY) principle. It achieves this by allowing common configurations (e.g., AWS region, S3 backend settings, common tags) to be defined once at a higher level in the directory hierarchy and then automatically inherited by all child modules. This significantly reduces boilerplate code and improves consistency and maintainability across large infrastructure projects.

Terragrunt offers robust dependency management, allowing users to define explicit relationships between different Terraform modules. When using commands like run-all, Terragrunt automatically determines the correct order of execution for modules based on their dependencies, ensuring that resources are provisioned or destroyed in the correct sequence (e.g., a VPC must exist before subnets or EC2 instances are deployed within it).

Terragrunt was developed by Gruntwork, a company specializing in DevOps and infrastructure-as-code. It was first released in 2016, motivated by the challenges of managing large, complex, and enterprise-grade Terraform deployments. Its core purpose was to address the lack of built-in features in Terraform for enforcing DRY principles, managing remote state consistently across environments, and orchestrating multiple interdependent modules efficiently. Since its inception, Terragrunt has evolved to become a popular companion tool for Terraform, especially in organizations with extensive infrastructure setups.

terraform(1), packer(1), ansible(1), aws(1), az(1), gcloud(1)