Skip to main content

Dirs and Directory Globs

Dirs

The dirs directive is a way to describe which tags, workspaces, and when_modified rules apply to a directory.

dirs:
dir1:
tags: [dir1]
workspaces:
workspace1:
tags: [workspace1]
dir2:
tags: [dir2]
workspaces:
workspace2:
tags: [workspace2]
when_modified:
file_patterns: ["dir2/*.tf", "dir1/*.tf"]

Directory Globs

In addition to specifying absolute path names, the dirs directive supports glob patterns as well. This can be useful for repositories with a lot of directories that match a pattern with a similar configuration.

The Terrateam runtime environment will list all of the files in your repository and match them according to the directory glob pattern. A dirs directive is then constructed from matched configurations as if the user had specified all of them by hand.

Things to note:

  • In a case where two globs match, the configuration with the longest glob match wins
  • Entries for exact directories always have precedence over glob entries

The ${DIR} Variable

File globs specified in file_patterns are always relative to the root of the repository. When the Terrateam runtime is working with directory globs, it needs a way to refer to the directory being processed. The internal ${DIR} variable is used to reference this directory.

info

The ${DIR} variable is only available if the dirs directory is a glob

Valid Configuration

dirs:
foobar/**:
when_modified:
file_patterns: ["_templates/**/*.tf", "${DIR}/*.tf"]

Invalid Configuration

############################################################
# This configuration is not valid!
# `${DIRS}` is not allowed because `foobar` is an exact path
############################################################
dirs:
foobar:
when_modified:
file_patterns: ["_templates/**/*.tf", "${DIR}/*.tf"]

Example

Consider a repository with the following files:

  • _templates/ec2/terragrunt.hcl
  • prod/ec2/us-east-1/foo.tf
  • prod/ec2/us-west-1/foo.tf
  • prod/ebs/us-east-1/foo.tf
  • prod/ebs/us-west-1/foo.tf

A .terrateam/config.yml configuration file:

dirs:
_templates/**:
when_modified:
file_patterns: []
prod/**/ec2/**:
tags: [prod, ec2]
when_modified:
file_patterns: ["_templates/**/*.tf", "${DIR}/*.tf"]
prod/**:
tags: [prod]
when_modified:
file_patterns: ["_templates/**/*.tf", "${DIR}/*.tf"]

Given the file list, the following dirs directive will be automatically generated during every Terrateam operation:

dirs:
_templates/ec2:
when_modified:
file_patterns: []
prod/ec2/us-east-1:
tags: [prod, ec2]
when_modified:
file_patterns: ["_templates/**/*.tf", "prod/ec2/us-east-1/*.tf"]
prod/ec2/us-west-1:
tags: [prod, ec2]
when_modified:
file_patterns: ["_templates/**/*.tf", "prod/ec2/us-west-1/*.tf"]
prod/ebs/us-east-1:
tags: [prod]
when_modified:
file_patterns: ["_templates/**/*.tf", "prod/ebs/us-east-1/*.tf"]
prod/ebs/us-west-1:
tags: [prod]
when_modified:
file_patterns: ["_templates/**/*.tf", "prod/ebs/us-west-1/*.tf"]

Longest Glob Match

In the example above, the files in the prod/ec2 directory match two globs:

  • prod/**/ec2/**
  • prod/**

The glob prod/**/ec2/** is longer than prod/** and is considered the better match because the glob is more specific.

Directory Globs Match Files (Terragrunt)

Globs can be expressed all the way to the file level. The directory of the file is then taken when constructing the dirs directory.

For example, in a repository with a structure to be used with Terragrunt, one could have the following configuration:

dirs:  _templates/**/terragrunt.hcl:    when_modified:      file_patterns: []  **/terragrunt.hcl:    tags: [terragrunt]    when_modified:      file_patterns: ['_templates/**/terragrunt.hcl', '${DIR}/*.hcl', '${DIR}/*.tf', '${DIR}/*.tfvars']

This configuration would apply the following rules:

  • Lines 2-4: Disable Terrateam operations in any directory under the _templates/ directory with a terragrunt.hcl file
  • Lines 5-8: Run Terrateam operations against a directory when:
    • The directory contains a terragrunt.hcl file
    • The pull request changed files end in hcl, tf, or tfvars
    • The pull request changed files includes a terragrunt.hcl file in the _templates/ directory

Use-cases

Keys

KeyTypeDescription
when_modifiedobjectSee when_modified
tagsarrayTags to assign the directory. This list of tags is inherited for each workspace entry.
workspacesobjectWorkspace for the directory. Tags can be specified for the workspace.

Default Configuration

dirs:

When Modified

KeyTypeDescription
file_patternsarrayList of file globs to trigger terrateam plan and terrateam apply
autoplanboolAutomatically run terrateam plan
autoapplyboolAutomatically run terrateam apply on a successful pull request merge

Things to note:

  • The when_modified configuration syntax is identical to the top-level when_modified
  • The when_modified configuration defaults to the the top-level when_modified configuration
  • The when_modified keys can be individually overridden in dirs
  • The file_patterns default value is set to the path of the directory specified in the dirs object
  • The file_patterns list is always relative to the root of the repository
info

When specifying file_patterns for a directory, the directory is not automatically included in the list of patterns.

For example, the configuration below will only identify a change to dir1 if a file in the modules directory is changed:

dirs:
dir1:
when_modified:
file_patterns: ['modules/*.tf']

The following configuration will identify a change to dir1 if a file in the dir1 or modules directory is changed:

dirs:
dir1:
when_modified:
file_patterns: ['dir1/*.tf', 'modules/*.tf']

Tags

KeyTypeDescription
tagsarrayList of tags to assign the directory

When assignging tags to a directory, tag values can be used in any combination to trigger custom workflows or target resources with commands.

Learn more:

Workspaces

The workspaces section is an object where the object key is the name of the workspace and the value is its configuration.

For example:

dirs:
dir1:
workspaces:
development:
tags: ['dev']
production:
tags: ['prod']

Workspace Configuration

KeyTypeDescription
tagsarrayList of tags to assign the workspace

Examples

Multi-Region Production Environment by Directory

dirs:
ec2/us-east-1/production:
tags: [ec2, us-east-1, production]
ec2/us-west-1/production:
tags: [ec2, us-west-1, production]

Multi-Region by Workspace

dirs:
ec2:
tags: [ec2]
when_modified:
file_patterns: ["ec2/*.tf", "ec2/*.tfvars"]
workspaces:
us-east-1:
tags: [us-east-1]
us-west-1
tags: [us-west-1]

Multi-Environment by Workspace

dirs:
ec2:
tags: [ec2]
workspaces:
development:
tags: [development]
production:
tags: [production]

Multi-Environment by Tfvars

info

Coming soon 👷‍♂️

Terraform Modules Directory Dependency

dirs:
modules:
when_modified:
file_patterns: []
ec2:
when_modified:
file_patterns: ["ec2/*.tf", "modules"]

Terragrunt with Directory Globs

when_modified:
file_patterns: []
workflows:
- tag_query: ""
terragrunt: true
plan:
- type: plan
apply:
- type: apply
dirs:
'_envcommon/**':
when_modified:
file_patterns: []
'prod/**/terragrunt.hcl':
when_modified:
file_patterns: ['_envcommon/**/*.hcl', '${DIR}/*.hcl']
warning

Longest glob always wins. In the example above, **/terragrunt.hcl is longer than _envcommon/**.