---
title: Attributes
description: Learn about terragrunt hcl attributes
slug: docs/reference/hcl/attributes
sidebar:
  order: 3
---

import FileTree from '@components/vendored/starlight/FileTree.astro';

Terragrunt HCL configuration uses [attributes](https://github.com/hashicorp/hcl/blob/main/hclsyntax/spec.md#attribute-definitions) 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](https://opentofu.org/docs/language/values/variables/#environment-variables). 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](https://opentofu.org/docs/language/values/variables/#type-constraints) on the variable in OpenTofu/Terraform in
order for OpenTofu/Terraform to process the inputs as the right type.

Example:

```hcl
# 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`:

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

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

And running:

```bash
terragrunt apply
```

This is roughly equivalent to running:

```bash
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:

```hcl
# 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:

```hcl
# 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:

```hcl
# 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](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html) 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](https://docs.gitlab.com/ee/ci/cloud_services/aws/)
- GitHub: [Configuring OpenID Connect in Amazon Web Services](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services)
- CircleCI: [Using OpenID Connect tokens in jobs](https://circleci.com/docs/openid-connect-tokens/)

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

```hcl
# 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`

```hcl
# 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:

```hcl
# 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:

```hcl
# terragrunt.hcl

terragrunt_version_constraint = ">= 0.23"
```
