Skip to content
Terragrunt
👷 The Terragrunt website redesign is Work In Progress! 👷
For a list of outstanding TODOs see this.
To give feedback, click here.

Attributes

Terragrunt HCL configuration uses attributes when there are values that need to be defined for Terragrunt as a whole.

Think of attributes as the values used for Terragrunt configuration, such as the inputs to pass an orchestrated OpenTofu/Terraform binary, or the download directory to use.

inputs

The inputs attribute is a map that is used to specify the input variables and their values to pass in to OpenTofu/Terraform. Each entry of the map is passed to OpenTofu/Terraform using the environment variable mechanism. This means that each input will be set using the form TF_VAR_variablename, with the value in json encoded format.

Note that because the values are being passed in with environment variables and json, the type information is lost when crossing the boundary between Terragrunt and OpenTofu/Terraform. You must specify the proper type constraint on the variable in OpenTofu/Terraform in order for OpenTofu/Terraform to process the inputs as the right type.

Example:

terragrunt.hcl
inputs = {
  string      = "string"
  number      = 42
  bool        = true
  list_string = ["a", "b", "c"]
  list_number = [1, 2, 3]
  list_bool   = [true, false]


  map_string = {
    foo = "bar"
  }


  map_number = {
    foo = 42
    bar = 12345
  }


  map_bool = {
    foo = true
    bar = false
    baz = true
  }


  object = {
    str  = "string"
    num  = 42
    list = [1, 2, 3]


    map = {
      foo = "bar"
    }
  }


  from_env = get_env("FROM_ENV", "default")
}

Using this attribute is roughly equivalent to setting the corresponding TF_VAR_ attribute.

For example, setting this in your terragrunt.hcl:

terragrunt.hcl
inputs = {
  instance_type  = "t2.micro"
  instance_count = 10


  tags = {
    Name = "example-app"
  }
}

And running:

Terminal window
terragrunt apply

This is roughly equivalent to running:

Terminal window
TF_VAR_instance_type="t2.micro" \
TF_VAR_instance_count=10 \
TF_VAR_tags='{"Name":"example-app"}' \
tofu apply # or terraform apply

Variable Precedence

Variables loaded in OpenTofu/Terraform will consequently use the following precedence order (with the highest precedence being lowest on the list):

  1. inputs set in terragrunt.hcl files.
  2. Explicitly set TF_VAR_ environment variables (these will override the inputs set in terragrunt.hcl if they conflict).
  3. terraform.tfvars files if present.
  4. terraform.tfvars.json files if present.
  5. Any *.auto.tfvars or *.auto.tfvars.json files, processed in lexical order of their filenames.
  6. Any -var and -var-file options on the command line, in the order they are provided.

download_dir

The terragrunt download_dir string option can be used to override the default download directory.

The precedence is as follows: --download-dir command line option → TG_DOWNLOAD env variable → download_dir attribute of the terragrunt.hcl file in the module directory → download_dir attribute of the included terragrunt.hcl.

It supports all terragrunt functions, i.e. path_relative_from_include().

prevent_destroy

Terragrunt prevent_destroy boolean flag allows you to protect selected OpenTofu/Terraform module. It will prevent destroy or destroy-all command to actually destroy resources of the protected module. This is useful for modules you want to carefully protect, such as a database, or a module that provides auth.

Example:

terragrunt.hcl
terraform {
  source = "git::git@github.com:foo/modules.git//app?ref=v0.0.3"
}


prevent_destroy = true

skip

DEPRECATED: Use exclude instead.

The terragrunt skip boolean flag can be used to protect units you don’t want any changes to, or just to skip units that don’t define any infrastructure by themselves. When set to true, all terragrunt commands will skip the selected module.

Consider the following file structure:

  • Directoryroot
    • terragrunt.hcl
    • Directoryprod
      • terragrunt.hcl
    • Directorydev
      • terragrunt.hcl
    • Directoryqa
      • terragrunt.hcl

In some cases, the root level terragrunt.hcl file is solely used to DRY up your OpenTofu/Terraform configuration by being included in the other terragrunt.hcl files. In this case, you do not want the run-all commands to process the root level terragrunt.hcl since it does not define any infrastructure by itself. To make the run-all commands skip the root level terragrunt.hcl file, you can set skip = true:

root/terragrunt.hcl
skip = true

The skip flag can be inherited from an included terragrunt.hcl file if skip is defined there, unless it is explicitly redefined in the current’s module terragrunt.hcl file.

iam_role

The iam_role attribute can be used to specify an IAM role that Terragrunt should assume before invoking OpenTofu/Terraform.

The precedence is as follows: --iam-role command line option → TG_IAM_ASSUME_ROLE env variable → iam_role attribute of the terragrunt.hcl file in the module directory → iam_role attribute of the included terragrunt.hcl.

Example:

terragrunt.hcl
iam_role = "arn:aws:iam::ACCOUNT_ID:role/ROLE_NAME"

Notes:

  • Value of iam_role can reference local variables
  • Definitions of iam_role included from other HCL files through include

iam_assume_role_duration

The iam_assume_role_duration attribute can be used to specify the STS session duration, in seconds, for the IAM role that Terragrunt should assume before invoking OpenTofu/Terraform.

The precedence is as follows: --iam-assume-role-duration command line option → TG_IAM_ASSUME_ROLE_DURATION env variable → iam_assume_role_duration attribute of the terragrunt.hcl file in the module directory → iam_assume_role_duration attribute of the included terragrunt.hcl.

Example:

terragrunt.hcl
iam_assume_role_duration = 14400

iam_assume_role_session_name

The iam_assume_role_session_name attribute can be used to specify the STS session name, for the IAM role that Terragrunt should assume before running OpenTofu/Terraform.

The precedence is as follows: --iam-assume-role-session-name command line option → TG_IAM_ASSUME_ROLE_SESSION_NAME env variable → iam_assume_role_session_name attribute of the terragrunt.hcl file in the module directory → iam_assume_role_session_name attribute of the included terragrunt.hcl.

iam_web_identity_token

The iam_web_identity_token attribute can be used along with iam_role to assume a role using AssumeRoleWithWebIdentity. iam_web_identity_token can be set to either the token value (typically using get_env()), or the path to a file on disk.

The precedence is as follows: --iam-web-identity-token command line option → TG_IAM_ASSUME_ROLE_WEB_IDENTITY_TOKEN env variable → iam_web_identity_token attribute of the terragrunt.hcl file in the module directory → iam_web_identity_token attribute of the included terragrunt.hcl.

The primary benefit of using AssumeRoleWithWebIdentity over regular AssumeRole is that it enables you to run terragrunt in your CI/CD pipelines wihthout static AWS credentials.

Git Provider Configuration

To use AssumeRoleWithWebIdentity in your CI/CD environment, you must first configure an AWS OpenID Connect provider to trust the OIDC service provided by your git provider.

Follow the instructions below for whichever Git provider you use:

Once you have configured your OpenID Connect Provider and configured the trust policy of your IAM role according to the above instructions, you can configure Terragrunt to use the Web Identity Token in the following manner.

If your Git provider provides the OIDC token as an environment variable, pass it in to the iam_web_identity_token as follows

terragrunt.hcl
iam_role = "arn:aws:iam::<AWS account number>:role/<IAM role name>"


iam_web_identity_token = get_env("<variable name>")

If your Git provider provides the OIDC token as a file, simply pass the file path to iam_web_identity_token

terragrunt.hcl
iam_role = "arn:aws:iam::<AWS account number>:role/<IAM role name>"


iam_web_identity_token = "/path/to/token/file"

terraform_binary

The terragrunt terraform_binary string option can be used to override the default binary Terragrunt calls (which is tofu).

The precedence is as follows: --tf-path command line option → TG_TF_PATH env variable → terragrunt.hcl in the module directory → included terragrunt.hcl

terraform_version_constraint

The terragrunt terraform_version_constraint string overrides the default minimum supported version of OpenTofu/Terraform. Terragrunt usually only officially supports the latest version of OpenTofu/Terraform, however, in some cases an older version of OpenTofu/Terraform is needed.

Example:

terragrunt.hcl
terraform_version_constraint = ">= 0.11"

terragrunt_version_constraint

The terragrunt terragrunt_version_constraint string can be used to specify which versions of the Terragrunt CLI can be used with your configuration. If the running version of Terragrunt doesn’t match the constraints specified, Terragrunt will produce an error and exit without taking any further actions.

Example:

terragrunt.hcl
terragrunt_version_constraint = ">= 0.23"

retryable_errors

DEPRECATED: Use errors instead.

The terragrunt retryable_errors list can be used to override the default list of retryable errors with your own custom list.

Default List:

retryable_errors = [
  "(?s).*Failed to load state.*tcp.*timeout.*",
  "(?s).*Failed to load backend.*TLS handshake timeout.*",
  "(?s).*Creating metric alarm failed.*request to update this alarm is in progress.*",
  "(?s).*Error installing provider.*TLS handshake timeout.*",
  "(?s).*Error configuring the backend.*TLS handshake timeout.*",
  "(?s).*Error installing provider.*tcp.*timeout.*",
  "(?s).*Error installing provider.*tcp.*connection reset by peer.*",
  "NoSuchBucket: The specified bucket does not exist",
  "(?s).*Error creating SSM parameter: TooManyUpdates:.*",
  "(?s).*app.terraform.io.*: 429 Too Many Requests.*",
  "(?s).*ssh_exchange_identification.*Connection closed by remote host.*",
  "(?s).*Client\\.Timeout exceeded while awaiting headers.*",
  "(?s).*Could not download module.*The requested URL returned error: 429.*",
]

Example:

terragrunt.hcl
retryable_errors = [
  "(?s).*Error installing provider.*tcp.*connection reset by peer.*",
  "(?s).*ssh_exchange_identification.*Connection closed by remote host.*"
]