CheatPress

Terragrunt Terraform orchestration

Version 1.1.6 · source

Terragrunt, Postcard, light preview Light · Postcard 102 × 152 mm · PDF Terragrunt, Postcard, dark preview Dark · Postcard 102 × 152 mm · PDF Terragrunt, Postcard, ink saver preview Ink saver · Postcard 102 × 152 mm · PDF
Terragrunt, A5, light preview Light · A5 148 × 210 mm · PDF Terragrunt, A5, dark preview Dark · A5 148 × 210 mm · PDF Terragrunt, A5, ink saver preview Ink saver · A5 148 × 210 mm · PDF
Terragrunt, A4, light preview Light · A4 210 × 297 mm · PDF Terragrunt, A4, dark preview Dark · A4 210 × 297 mm · PDF Terragrunt, A4, ink saver preview Ink saver · A4 210 × 297 mm · PDF
Terragrunt, A4 landscape, light preview Light · A4 landscape 297 × 210 mm · PDF Terragrunt, A4 landscape, dark preview Dark · A4 landscape 297 × 210 mm · PDF Terragrunt, A4 landscape, ink saver preview Ink saver · A4 landscape 297 × 210 mm · PDF
Terragrunt, A3, light preview Light · A3 297 × 420 mm · PDF Terragrunt, A3, dark preview Dark · A3 297 × 420 mm · PDF Terragrunt, A3, ink saver preview Ink saver · A3 297 × 420 mm · PDF
Terragrunt, A3 landscape, light preview Light · A3 landscape 420 × 297 mm · PDF Terragrunt, A3 landscape, dark preview Dark · A3 landscape 420 × 297 mm · PDF Terragrunt, A3 landscape, ink saver preview Ink saver · A3 landscape 420 × 297 mm · PDF
Terragrunt, Letter, light preview Light · Letter 8.5 × 11 in · PDF Terragrunt, Letter, dark preview Dark · Letter 8.5 × 11 in · PDF Terragrunt, Letter, ink saver preview Ink saver · Letter 8.5 × 11 in · PDF
Terragrunt, Tabloid, light preview Light · Tabloid 11 × 17 in · PDF Terragrunt, Tabloid, dark preview Dark · Tabloid 11 × 17 in · PDF Terragrunt, Tabloid, ink saver preview Ink saver · Tabloid 11 × 17 in · PDF

Start here

terragrunt run plan
Plan this unit
terragrunt run apply
Apply this unit
terragrunt run --all plan
Plan every unit
terragrunt run --all apply
Apply in DAG order
terragrunt run --all destroy
Destroy in reverse order
terragrunt find
List units found
terragrunt hcl fmt
Format HCL files
terragrunt render --json
Show resolved config

Concepts

  1. Discover find units in tree
  2. Order DAG from dependencies
  3. Init + run auto-init, then tofu cmd
  4. Result summary of all units

Run

terragrunt run plan
Plan the unit in this directory
terragrunt run apply
Apply the unit in this directory
terragrunt run init
Initialise the unit
terragrunt run destroy
Destroy the unit
terragrunt run output
Show unit outputs
terragrunt plan
Shortcut for run plan
terragrunt run --all plan
Plan all units below here
terragrunt run --all apply
Apply all units in order
terragrunt run --all destroy
Destroy all, dependents first
terragrunt run --graph plan
Plan this unit and its dependents
Dependents run in graph order; for destroy the order is reversed.
terragrunt run --all --parallelism <n> plan
Cap concurrent units
terragrunt run --all --no-auto-approve apply
Keep the apply prompt
terragrunt run --all --queue-ignore-dag-order plan
Ignore dependency order
Risky for apply and destroy.
terragrunt run --all --out-dir <dir> plan
Save a plan file per unit
Run apply with the same --out-dir and filters.
terragrunt run --source <path> plan
Override the module source
terragrunt run --tf-path <bin> plan
Pick tofu or terraform binary
terragrunt exec -- <cmd>
Run any command in the unit

Select units

--filter '<glob>'
Only units matching the path
Repeat the flag to OR several filters. Quote globs so the shell leaves them alone.
--filter '!<glob>'
Exclude matching units
--filter 'name=<unit>...'
A unit plus its dependencies
Graph expressions: ...name adds dependents, name... adds dependencies.
--working-dir <dir>
Run as if in another directory

Config blocks

Parent terragrunt.hcl: backend and shared code 
remote_state {  backend = "s3"  generate = { path = "backend.tf", if_exists = "overwrite_terragrunt" }  config = {    bucket = "my-state"    key    = "${path_relative_to_include()}/tofu.tfstate"    region = "eu-central-1"  }}
Child unit: include, source, inputs
include "root" {  path = find_in_parent_folders("root.hcl")}terraform {  source = "git::https://example.com/modules.git//vpc?ref=v1.2.0"}inputs = {  cidr = "10.0.0.0/16"}
dependency: read another unit's outputs 
dependency "vpc" {  config_path = "../vpc"  mock_outputs = { vpc_id = "fake" }}inputs = { vpc_id = dependency.vpc.outputs.vpc_id }
dependencies and locals: order only, shared values 
dependencies { paths = ["../vpc", "../iam"] }locals {  env = basename(get_terragrunt_dir())}
generate: write a file before each run
generate "provider" {  path      = "provider.tf"  if_exists = "overwrite_terragrunt"  contents  = "provider \"aws\" { region = \"eu-central-1\" }"}
Hooks and extra arguments
terraform {  before_hook "fmt" {    commands = ["plan"]    execute  = ["tofu", "fmt", "-check"]  }  extra_arguments "vars" {    commands  = get_terraform_commands_that_need_vars()    arguments = ["-var-file=common.tfvars"]  }}
Block purpose
Block Use
include Inherit a parent file
inputs Variables passed to the module
dependency Outputs of another unit
dependencies Ordering without outputs
remote_state Backend setup
generate Write helper files
locals Named values in the file
feature Flags set with --feature

Functions

find_in_parent_folders()
Nearest parent terragrunt file
path_relative_to_include()
Unit path relative to parent
get_terragrunt_dir()
Directory of this terragrunt.hcl
get_env("<NAME>", "<default>")
Read an environment variable

Discover

terragrunt find
List units and stacks
terragrunt find --json
Machine-readable list
terragrunt find --dag
Sort by dependency order
terragrunt list
List configurations
terragrunt dag graph
Print the DAG as DOT
terragrunt render --json
Resolved config, includes merged

Format and validate

terragrunt hcl fmt
Format HCL files in place
terragrunt hcl fmt --check
Fail if formatting differs
terragrunt hcl validate
Validate HCL files

Stacks and backend

terragrunt stack generate
Create units from stack.hcl
terragrunt stack run <cmd>
Run a command on a stack
terragrunt backend bootstrap
Create the state backend

Recipes

Plan only a subset
terragrunt run --all --filter 'prod/**' -- planterragrunt run --all --filter '!prod/legacy/**' -- planterragrunt run --all --parallelism 4 -- plan -no-color
Reviewed plan, then apply the same plans 
terragrunt run --all --out-dir /tmp/plans planterragrunt run --all --out-dir /tmp/plans apply
CI format and validate gate
terragrunt hcl fmt --checkterragrunt hcl validateterragrunt run --all --non-interactive -- validate
Test a local module against a unit
cd live/dev/vpcterragrunt run --source ~/code/modules//vpc -- plan