Skip to content

dependency

unit

Usage

A dependency block reads another unit’s outputs:

app/terragrunt.hcl
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:

app/terragrunt.hcl
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:

networking/terragrunt.stack.hcl
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:

app/terragrunt.hcl
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:

Terminal window
$ terragrunt stack output
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"
}

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:

networking/terragrunt.stack.hcl
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:

Terminal window
$ terragrunt stack output
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 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:

networking/terragrunt.stack.hcl
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:

Terminal window
$ terragrunt stack output
subnets = {
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:

app/terragrunt.hcl
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:

networking/terragrunt.stack.hcl
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:

Terminal window
$ terragrunt stack output
subnets = {
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:

app/terragrunt.hcl
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:

networking/terragrunt.stack.hcl
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:

Terminal window
$ terragrunt stack output
subnets = {
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:

app/terragrunt.hcl
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:

app/terragrunt.hcl
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:

root.hcl
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"
}
}
app/terragrunt.hcl
include "root" {
path = find_in_parent_folders("root.hcl")
}
dependency "vpc" {
config_path = "../vpc"
}
vpc/terragrunt.hcl
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_state backend
  • 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:

vpc/terragrunt.hcl
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

name

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.

Attributes

config_pathstring

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.

terragrunt.hcl
dependency "vpc" {
config_path = "../vpc"
}
enabledoptional(bool, true)

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.

terragrunt.hcl
feature "use_cache" {
default = false
}
dependency "cache" {
config_path = "../cache"
enabled = feature.use_cache.value
}
skip_outputsoptional(bool, false)

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.

terragrunt.hcl
dependency "vpc" {
config_path = "../vpc"
skip_outputs = true
mock_outputs = {
vpc_id = "vpc-mock"
}
}
mock_outputsoptional(map(any))

Outputs to use when the dependency has none, e.g. before its first apply, so this unit can run plan.

terragrunt.hcl
dependency "vpc" {
config_path = "../vpc"
mock_outputs = {
vpc_id = "vpc-mock"
}
}
mock_outputs_allowed_terraform_commandsoptional(list(string))

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.

terragrunt.hcl
dependency "vpc" {
config_path = "../vpc"
mock_outputs_allowed_terraform_commands = ["validate", "plan"]
mock_outputs = {
vpc_id = "vpc-mock"
}
}
mock_outputs_merge_strategy_with_stateoptional(string, ""no_merge"")

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.

terragrunt.hcl
dependency "vpc" {
config_path = "../vpc"
mock_outputs_merge_strategy_with_state = "shallow"
mock_outputs = {
new_output = "mock"
}
}
mock_outputs_merge_with_stateoptional(bool, false)

Deprecated. Use mock_outputs_merge_strategy_with_state. true works like mock_outputs_merge_strategy_with_state = "shallow".

terragrunt.hcl
dependency "vpc" {
config_path = "../vpc"
mock_outputs_merge_with_state = true
mock_outputs = {
new_output = "mock"
}
}