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:

terragrunt apply

This is roughly equivalent to running:

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_DIR 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 run --all destroy command from actually destroying 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

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-assume-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-assume-role-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 without 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:

• GitLab: Configure OpenID Connect in AWS to retrieve temporary credentials
• GitHub: Configuring OpenID Connect in Amazon Web Services
• CircleCI: Using OpenID Connect tokens in jobs

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"