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"
}

filter block

filterblockoptional

The ceiling of retention days that can be configured via a backup plan for the given vault

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.

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

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 running Terragrunt commands.

Default:us-east-1

session_durationnumberoptional

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

Default:3600