Pipelines Configurations as Code

Block Reference

For a more comprehensive walkthrough of how blocks work please see the Pipelines Configurations as Code concepts.

environment block

environmentlabeled-blockoptional

Environment blocks are used to define configurations that are applicable to a specific environment within a repository.

The label applied to an environment block is the name of the environment. This is a user-defined label for the environment, and must be globally unique.

See more below.

Example

# .gruntwork/environments.hcl
environment "an_environment" {
  filter {
    paths = ["an-environment/*"]
  }

  authentication {
    aws_oidc {
      account_id         = aws.accounts.all.an_account.id
      plan_iam_role_arn  = "arn:aws:iam::${aws.accounts.all.an_account.id}:role-to-assume-for-plans"
      apply_iam_role_arn = "arn:aws:iam::${aws.accounts.all.an_account.id}:role-to-assume-for-applies"
    }
  }
}

aws {
  accounts "all" {
    path = "aws/accounts.yml"
  }
}

unit block

unitblockoptional

Unit blocks are used to define configurations that are applicable to a single unit of IaC within a repository. See more below.

Example

unit {
  authentication {
    aws_oidc {
      account_id         = "an-aws-account-id"
      plan_iam_role_arn  = "arn:aws:iam::an-aws-account-id:role-to-assume-for-plans"
      apply_iam_role_arn = "arn:aws:iam::an-aws-account-id:role-to-assume-for-applies"
    }
  }
}

authentication block

authenticationblockoptional

Authentication blocks are components used by environment and unit blocks to determine how Pipelines will authenticate with cloud platforms when running Terragrunt commands. See more below.

Example

authentication {
  aws_oidc {
    account_id     = "an-aws-account-id"
    plan_iam_role  = "arn:aws:iam::an-aws-account-id:role-to-assume-for-plans"
    apply_iam_role = "arn:aws:iam::an-aws-account-id:role-to-assume-for-applies"
  }
}

repository block

repositoryblockoptional

Repository blocks are used to define configurations that are applicable to the entire repository. See more below.

Example

repository {
  deploy_branch_name = "main"
}

env block

envblockoptional

Env blocks are configuration components used by repository blocks to specify environment variables that will be set when executing Terragrunt commands. The block contains a map of environment variable names and their values.

Example

repository {
  env {
    TF_VAR_environment = "an_environment_provided_input"
    TG_STRICT_VALIDATE = true
  }
}

filter block

filterblockoptional

A list of path globs that the filter should match against. Paths are relative to the directory containing the .gruntwork directory.

aws block

awsblock

AWS blocks are configurations used by aws-oidc authentication blocks to have commonly re-used AWS configurations codified and referenced by multiple authentication blocks.

There can only be one aws block defined within global configurations.

Nested within the aws block are accounts blocks that define the configurations for collections of AWS accounts.

The label applied to an accounts block is the name of the Accounts block. This is a user-defined label for the collection of AWS accounts defined by the block, and must be unique within the context of the aws block.

For more information on importing accounts from accounts.yml click here

See more below.

Example

aws {
  accounts "all" {
    path = "aws/accounts.yml"
  }
}

accounts block

accountslabeled blockoptional

Accounts blocks define the configurations for collections of AWS accounts.

The label applied to an accounts block is the name of the Accounts block. This is a user-defined label for the collection of AWS accounts defined by the block, and must be unique within the context of the aws block.

aws_oidc block

aws_oidcblockoptional

An AWS OIDC authentication block that determines how Pipelines will authenticate with AWS using OIDC. See more below.

azure_oidc block

azure_oidcblockoptional

An Azure OIDC authentication block that determines how Pipelines will authenticate with Azure using OIDC. See more below.

custom block

customblockoptional

A custom authentication block that determines how Pipelines will authenticate with custom authentication logic when running Terragrunt commands. See more below.

Block Attributes

environment block attributes

filterblockrequired

A filter block that determines which units the environment is applicable to. See more below.

caution

Every unit must be uniquely matched by the filters of a single environment block. If a unit is matched by multiple environment blocks, Pipelines will throw an error.

authenticationblockrequired

An authentication block that determines how Pipelines will authenticate with cloud platforms when running Terragrunt commands. See more below.

unit block attributes

authenticationblockrequired

An authentication block that determines how Pipelines will authenticate with cloud platforms when running Terragrunt commands. See more below.

authentication block attributes

aws_oidcblockrequired

An AWS OIDC authentication block that determines how Pipelines will authenticate with AWS using OIDC See more below.

repository block attributes

deploy_branch_namestringoptional

The branch that Pipelines will deploy infrastructure changes from.

Default:main

consolidate_added_or_changedbooleanoptional

Whether or not Pipelines will consolidate added or changed resources when running Terragrunt commands.

Job Consolidation Definition

Job consolidation is the mechanism whereby Pipelines will take multiple jobs (e.g. ModuleAdded, ModuleChanged) and consolidate them into a single job (e.g. ModulesAddedOrChanged) when running Terragrunt commands.

This is a useful optimization that Pipelines can perform, as it divides the CI/CD costs of running Terragrunt in CI by the number of jobs that are consolidated. In addition, this results in more accurate runs, as it allows Terragrunt to leverage the Directed Acyclic Graph (DAG) to order updates.

e.g. Instead of running the following jobs: A. ModuleAdded B. ModuleChanged

Where ModuleChanged depends on ModuleAdded, Pipelines will consolidate these jobs into a single job: C. ModulesAddedOrChanged

Because the underlying implementation of a ModulesAddedOrChanged uses the run-all Terragrunt command, it will use the DAG to ensure that the ModuleAdded job runs before the ModuleChanged job.

Default:true

consolidate_deletedbooleanoptional

Whether or not Pipelines will consolidate deleted resources when running Terragrunt plan commands.

caution

This is disabled by default because there can be unintended consequences to deleting additional resources via a run-all Terragrunt command. It is recommended to enable this feature only when you are confident that you understand the implications of doing so.

Default:false

tf_binarystringoptional

The Infrastructure as Code(Iac) binary that Pipelines will instruct Terragrunt to use. Valid values are:

• opentofu (default): Use OpenTofu for managing infrastructure. Gruntwork recommends customers use OpenTofu.

• terraform: Use Terraform for managing infrastructure.

  note

  Changing this value for existing infrastructure may require additional steps to ensure a successful migration.

Default:opentofu

ignore_liststringoptional

A comma separate list of ignore filters to exclude from pipelines runs. See the full documentation here

filter block attributes

pathsarray[string]required

A list of path globs that the filter should match against. Paths are relative to the directory containing the .gruntwork directory.

aws block attributes

accountslabeled blockrequired

The AWS account ID that Pipelines will authenticate with. See more below.

accounts block attributes

pathstringrequired

The path to the accounts.yml file that contains the definition of AWS accounts.

note

The value used for the path attribute is relative to the directory containing the .gruntwork directory.

e.g. If the accounts.yml file is located at the root of the repository, and the configuration containing the aws block is located in .gruntwork/aws.hcl, then the value of the path attribute would be ../accounts.yml.

This is to make it convenient to tuck the accounts.yml file away somewhere in the .gruntwork directory if you like.

aws_oidc block attributes

account_idstringrequired

The AWS account ID that Pipelines will authenticate with.

plan_iam_role_arnstringrequired

The IAM role ARN that Pipelines will assume when running Terragrunt plan commands.

apply_iam_role_arnstringrequired

The IAM role ARN that Pipelines will assume when running Terragrunt apply commands.

regionstringoptional

The AWS region that Pipelines will use when calling the AWS Security Token Service (STS) to generate authentication tokens.

Default:us-east-1

session_durationnumberoptional

The duration in seconds that the AWS session will be valid for.

Default:3600

azure_oidc block attributes

tenant_idstringrequired

The Azure tenant ID that Pipelines will authenticate with.

subscription_idstringrequired

The Azure subscription ID that Pipelines will authenticate with.

plan_client_idstringrequired

The Azure client ID that Pipelines will authenticate with when running Terragrunt plan commands.

apply_client_idstringrequired

The Azure client ID that Pipelines will authenticate with when running Terragrunt apply commands.

custom block attributes

auth_provider_cmdstringrequired

The command that Pipelines will execute to authenticate with the custom authentication logic.

tip

You can learn more about how custom authentication works in the Custom Authentication documentation.