Names the dependency. The configuration reads its outputs as dependency.<name>.outputs. Each dependency block in a file needs a different name and a different config_path. See the duplicate-dependency-labels strict control.
dependency
Usage
A dependency block reads another unit’s outputs:
dependency "vpc" { config_path = "../vpc"}
inputs = { vpc_id = dependency.vpc.outputs.vpc_id}Directoryvpc
- terragrunt.hcl
Directoryapp
- terragrunt.hcl
app passes the vpc_id output of vpc to its module. In a run queue, e.g. terragrunt run --all -- apply, vpc runs before app. To order units without reading outputs, use dependencies.
Before vpc is applied, it has no outputs, and app fails to read them. Set mock_outputs so app can run plan first:
dependency "vpc" { config_path = "../vpc"
mock_outputs_allowed_terraform_commands = ["validate", "plan"] mock_outputs = { vpc_id = "vpc-mock" }}A dependency block can contain an expansion block, which repeats it once per element of a collection, e.g. dependency.aurora["web"].outputs.id.
Depending on a stack
A dependency block’s config_path can point at a directory that contains a terragrunt.stack.hcl file. The dependency then reads the outputs of every unit the stack generates.
Directorynetworking
- terragrunt.stack.hcl
Directoryapp
- terragrunt.hcl
The networking stack creates a VPC with a public and a private subnet. Both subnets come from the same subnet unit, which outputs the subnet’s id, cidr_block, and availability_zone:
unit "vpc" { source = "github.com/acme/infrastructure-catalog//units/vpc?ref=v1.0.0" path = "vpc"
values = { cidr_block = "10.0.0.0/16" }}
unit "public" { source = "github.com/acme/infrastructure-catalog//units/subnet?ref=v1.0.0" path = "public"
values = { availability_zone = "us-east-1a" cidr_block = "10.0.1.0/24" }}
unit "private" { source = "github.com/acme/infrastructure-catalog//units/subnet?ref=v1.0.0" path = "private"
values = { availability_zone = "us-east-1a" cidr_block = "10.0.101.0/24" }}Generating the stack creates a directory for each unit under networking/.terragrunt-stack:
Directorynetworking
- terragrunt.stack.hcl
Directory.terragrunt-stack
Directoryvpc
- terragrunt.hcl
Directorypublic
- terragrunt.hcl
Directoryprivate
- terragrunt.hcl
Directoryapp
- terragrunt.hcl
app reads each unit’s outputs under the unit’s name in the stack file:
dependency "networking" { config_path = "../networking"}
inputs = { vpc_id = dependency.networking.outputs.vpc.id public_subnet_id = dependency.networking.outputs.public.id private_subnet_id = dependency.networking.outputs.private.id}Output addresses
A stack dependency reads each unit at the same address terragrunt stack output gives it. Once networking is applied, running terragrunt stack output in networking prints one entry per unit:
$ terragrunt stack outputprivate = { availability_zone = "us-east-1a" cidr_block = "10.0.101.0/24" id = "subnet-33333333333333333"}public = { availability_zone = "us-east-1a" cidr_block = "10.0.1.0/24" id = "subnet-11111111111111111"}vpc = { cidr_block = "10.0.0.0/16" id = "vpc-00000000000000000"}dependency.networking.outputs has the same shape, so dependency.networking.outputs.public.id is "subnet-11111111111111111" and dependency.networking.outputs.vpc.cidr_block is "10.0.0.0/16".
Now disable the private unit:
unit "vpc" { source = "github.com/acme/infrastructure-catalog//units/vpc?ref=v1.0.0" path = "vpc"
values = { cidr_block = "10.0.0.0/16" }}
unit "public" { source = "github.com/acme/infrastructure-catalog//units/subnet?ref=v1.0.0" path = "public"
values = { availability_zone = "us-east-1a" cidr_block = "10.0.1.0/24" }}
unit "private" { enabled = false
source = "github.com/acme/infrastructure-catalog//units/subnet?ref=v1.0.0" path = "private"
values = { availability_zone = "us-east-1a" cidr_block = "10.0.101.0/24" }}Terragrunt no longer generates private, so its entry is gone from the output:
$ terragrunt stack outputpublic = { availability_zone = "us-east-1a" cidr_block = "10.0.1.0/24" id = "subnet-11111111111111111"}vpc = { cidr_block = "10.0.0.0/16" id = "vpc-00000000000000000"}dependency.networking.outputs loses the private attribute the same way, so app fails with an Unsupported attribute error on dependency.networking.outputs.private.id. The dependency also leaves out a unit that has no outputs.
An expanded unit nests its elements under their keys. Here a subnets unit expands into one subnet per availability zone:
unit "vpc" { source = "github.com/acme/infrastructure-catalog//units/vpc?ref=v1.0.0" path = "vpc"
values = { cidr_block = "10.0.0.0/16" }}
unit "subnets" { expansion { for_each = { us-east-1a = "10.0.1.0/24" us-east-1b = "10.0.2.0/24" } }
source = "github.com/acme/infrastructure-catalog//units/subnet?ref=v1.0.0" path = "subnets/${each.key}"
values = { availability_zone = each.key cidr_block = each.value }}terragrunt stack output prints each element under subnets, keyed by availability zone:
$ terragrunt stack outputsubnets = { us-east-1a = { availability_zone = "us-east-1a" cidr_block = "10.0.1.0/24" id = "subnet-11111111111111111" } us-east-1b = { availability_zone = "us-east-1b" cidr_block = "10.0.2.0/24" id = "subnet-22222222222222222" }}vpc = { cidr_block = "10.0.0.0/16" id = "vpc-00000000000000000"}app reaches each element by its key:
dependency "networking" { config_path = "../networking"}
inputs = { vpc_id = dependency.networking.outputs.vpc.id subnet_a_id = dependency.networking.outputs.subnets["us-east-1a"].id subnet_b_id = dependency.networking.outputs.subnets["us-east-1b"].id}Nested stacks
A nested stack block adds a level named after the stack. Here networking creates its subnets through a nested subnets stack:
unit "vpc" { source = "github.com/acme/infrastructure-catalog//units/vpc?ref=v1.0.0" path = "vpc"
values = { cidr_block = "10.0.0.0/16" }}
stack "subnets" { source = "github.com/acme/infrastructure-catalog//stacks/subnets?ref=v1.0.0" path = "subnets"
values = { availability_zone = "us-east-1a" public_cidr_block = "10.0.1.0/24" private_cidr_block = "10.0.101.0/24" }}# stacks/subnets/terragrunt.stack.hcl in the catalog
unit "public" { source = "github.com/acme/infrastructure-catalog//units/subnet?ref=v1.0.0" path = "public"
values = { availability_zone = values.availability_zone cidr_block = values.public_cidr_block }}
unit "private" { source = "github.com/acme/infrastructure-catalog//units/subnet?ref=v1.0.0" path = "private"
values = { availability_zone = values.availability_zone cidr_block = values.private_cidr_block }}The nested stack generates its own .terragrunt-stack directory inside networking/.terragrunt-stack/subnets:
Directorynetworking
- terragrunt.stack.hcl
Directory.terragrunt-stack
Directoryvpc
- terragrunt.hcl
Directorysubnets
- terragrunt.stack.hcl
Directory.terragrunt-stack
Directorypublic
- terragrunt.hcl
Directoryprivate
- terragrunt.hcl
Directoryapp
- terragrunt.hcl
terragrunt stack output prints the units of subnets under the stack’s name:
$ terragrunt stack outputsubnets = { private = { availability_zone = "us-east-1a" cidr_block = "10.0.101.0/24" id = "subnet-33333333333333333" } public = { availability_zone = "us-east-1a" cidr_block = "10.0.1.0/24" id = "subnet-11111111111111111" }}vpc = { cidr_block = "10.0.0.0/16" id = "vpc-00000000000000000"}app reads them through the same name:
dependency "networking" { config_path = "../networking"}
inputs = { vpc_id = dependency.networking.outputs.vpc.id public_subnet_id = dependency.networking.outputs.subnets.public.id private_subnet_id = dependency.networking.outputs.subnets.private.id}Each further level of nesting adds another name. A nested stack is left out when it has enabled = false, has not been generated, or has no units with outputs. An expanded nested stack keys its elements the same way as an expanded unit. Here subnets expands into one nested stack per availability zone:
unit "vpc" { source = "github.com/acme/infrastructure-catalog//units/vpc?ref=v1.0.0" path = "vpc"
values = { cidr_block = "10.0.0.0/16" }}
stack "subnets" { expansion { for_each = { us-east-1a = { public = "10.0.1.0/24", private = "10.0.101.0/24" } us-east-1b = { public = "10.0.2.0/24", private = "10.0.102.0/24" } } }
source = "github.com/acme/infrastructure-catalog//stacks/subnets?ref=v1.0.0" path = "subnets/${each.key}"
values = { availability_zone = each.key public_cidr_block = each.value.public private_cidr_block = each.value.private }}terragrunt stack output prints the public and private units of each element under its key:
$ terragrunt stack outputsubnets = { us-east-1a = { private = { availability_zone = "us-east-1a" cidr_block = "10.0.101.0/24" id = "subnet-33333333333333333" } public = { availability_zone = "us-east-1a" cidr_block = "10.0.1.0/24" id = "subnet-11111111111111111" } } us-east-1b = { private = { availability_zone = "us-east-1b" cidr_block = "10.0.102.0/24" id = "subnet-44444444444444444" } public = { availability_zone = "us-east-1b" cidr_block = "10.0.2.0/24" id = "subnet-22222222222222222" } }}vpc = { cidr_block = "10.0.0.0/16" id = "vpc-00000000000000000"}app reaches a unit in one element through the element’s key, then the unit’s name:
dependency "networking" { config_path = "../networking"}
inputs = { vpc_id = dependency.networking.outputs.vpc.id public_subnet_a_id = dependency.networking.outputs.subnets["us-east-1a"].public.id public_subnet_b_id = dependency.networking.outputs.subnets["us-east-1b"].public.id}Mock outputs
mock_outputs for a stack dependency uses the same addresses as its outputs, with a map or object at each level. For the nested subnets stack:
dependency "networking" { config_path = "../networking"
mock_outputs_allowed_terraform_commands = ["validate", "plan"] mock_outputs = { vpc = { id = "vpc-mock" } subnets = { public = { id = "subnet-public-mock" } private = { id = "subnet-private-mock" } } }}Before any unit in the stack is applied, the whole mock_outputs value stands in, as it does for a unit dependency.
Once some units are applied, reading a unit that isn’t applied yet fails unless mock_outputs_merge_strategy_with_state fills it from mock_outputs. With vpc applied:
| Not applied | no_merge |
shallow |
deep_map_only |
|---|---|---|---|
subnets.public and subnets.private |
Fails | mock_outputs |
mock_outputs |
subnets.private |
Fails | Fails | mock_outputs |
Run order
A unit that depends on a stack waits for every unit the stack generates, including units in nested stacks. See the run queue. A stack can’t declare dependencies of its own.
Terragrunt reads outputs only from generated units. run --all generates the stacks under its working directory before running, so run it from a directory that contains both the stack and the dependent unit, or run terragrunt stack generate in the stack directory first.
Fetching outputs faster
To read a dependency’s outputs, Terragrunt first tries to parse only the dependency’s remote_state block, and reads the outputs from that backend. In this chain, app depends on vpc, and vpc depends on account:
remote_state { backend = "s3" generate = { path = "backend.tf" if_exists = "overwrite_terragrunt" } config = { bucket = "my-tofu-state" key = "${path_relative_to_include()}/tofu.tfstate" region = "us-east-1" }}include "root" { path = find_in_parent_folders("root.hcl")}
dependency "vpc" { config_path = "../vpc"}include "root" { path = find_in_parent_folders("root.hcl")}
dependency "account" { config_path = "../account"}
inputs = { account_id = dependency.account.outputs.account_id}- root.hcl
Directoryapp
- terragrunt.hcl
Directoryvpc
- terragrunt.hcl outputs read from its
remote_statebackend
- terragrunt.hcl outputs read from its
Directoryaccount
- terragrunt.hcl not parsed
To read vpc’s outputs for app, Terragrunt parses only the remote_state block that vpc includes, and skips vpc’s dependency "account". A remote_state block can read locals and include and keep this shortcut.
When the remote_state block reads dependency outputs, Terragrunt parses the dependency’s whole configuration, including its own dependency blocks, one level at a time down the chain. If vpc sets its own backend from account’s outputs, reading vpc’s outputs also reads account’s:
dependency "account" { config_path = "../account"}
remote_state { backend = "s3" generate = { path = "backend.tf" if_exists = "overwrite_terragrunt" } config = { bucket = dependency.account.outputs.state_bucket key = "vpc/tofu.tfstate" region = "us-east-1" }}Parsing only remote_state skips the dependency’s hooks and extra_arguments for init. If the dependency needs them to reach its state, set disable_dependency_optimization = true in its remote_state block.
Labels
Attributes
The directory of the unit to read, relative to this unit’s directory. A directory with a terragrunt.stack.hcl file reads every unit the stack generates. See Depending on a stack. Setting it to a file is deprecated. See the dependency-config-path-file strict control.
dependency "vpc" { config_path = "../vpc"}When false, Terragrunt ignores the block. The unit doesn’t wait for the dependency in a run queue, and dependency.<name>.outputs doesn’t exist.
feature "use_cache" { default = false}
dependency "cache" { config_path = "../cache" enabled = feature.use_cache.value}When true, Terragrunt doesn’t read the dependency’s outputs, and dependency.<name>.outputs is mock_outputs. Without mock_outputs, dependency.<name>.outputs doesn’t exist. The unit still waits for the dependency in a run queue.
dependency "vpc" { config_path = "../vpc" skip_outputs = true
mock_outputs = { vpc_id = "vpc-mock" }}Outputs to use when the dependency has none, e.g. before its first apply, so this unit can run plan.
dependency "vpc" { config_path = "../vpc"
mock_outputs = { vpc_id = "vpc-mock" }}The commands that can use mock_outputs, e.g. ["validate", "plan"]. When it’s unset, every command can. Any other command fails when the dependency has no outputs, so apply can’t run with mock values.
dependency "vpc" { config_path = "../vpc"
mock_outputs_allowed_terraform_commands = ["validate", "plan"] mock_outputs = { vpc_id = "vpc-mock" }}How mock_outputs fill in outputs the dependency doesn’t have. no_merge uses the dependency’s outputs as they are, and uses mock_outputs only when it has none. shallow adds a top-level output that only mock_outputs has. deep_map_only also adds the missing keys of map outputs. Lists don’t merge.
dependency "vpc" { config_path = "../vpc"
mock_outputs_merge_strategy_with_state = "shallow" mock_outputs = { new_output = "mock" }}Deprecated. Use mock_outputs_merge_strategy_with_state. true works like mock_outputs_merge_strategy_with_state = "shallow".
dependency "vpc" { config_path = "../vpc"
mock_outputs_merge_with_state = true mock_outputs = { new_output = "mock" }}