Directories and Globs
Directories can be used to describe which Tags, Workspaces, and When Modified rules apply to a directory in your repository.
Terrateam Configuration
Terrateam behavior can be configured via a config.yml
. This file is located in
a directory named .terrateam
at the root of your Terraform repository:
.terrateam/config.yml
.
See Configuration documentation for details.
Configuration
Top-level key: dirs
See Configuration Reference documentation for details.
<directory_name>
Each directory consists of the directory's name as a key and a map as a value.
The value map has the following attributes:
Key | Type | Description |
---|---|---|
tags | List | List of tags to assign the directory. |
workspaces | Workspaces | Workspace configuration. |
when_modified | When Modified | Configuration to override when to match pull request file changes with Autoplan and Autoapply. |
When Modified
When Modified can be configured in the dirs
directive. This configuration is identical to the global When Modified.
- 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 indirs
- The
file_patterns
default value is set to the path of the directory specified in thedirs
object - The
file_patterns
list is always relative to the root of the repository
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']
Assigning Tags
The tags
configuration is used to create a custom tag for a directory.
When assignging Tags to a directory, tag values can be used in any combination to trigger Workflows or target resources with Commands.
dirs:
ec2/us-east-1/production:
tags: [ec2, us-east-1, production]
ec2/us-west-1/production:
tags: [ec2, us-west-1, production]
See Tags documentation for details.
Assigning Workspaces
The workspaces
configuration is an object where the object key is the name of the Workspace and the value is its configuration.
Unique custom tags can be created against a directory and workspace combination.
dirs:
dir1:
workspaces:
development:
tags: ['dev']
production:
tags: ['prod']
Example
dirs:
ec2:
tags: [aws, ec2]
workspaces:
production:
tags: [production]
when_modified:
file_patterns: ["ec2/*.tf", "ec2/*.tfvars", "iam/*.tf", "iam/*.tfvars"]
iam:
tags: [aws, iam]
Description:
- Tag
ec2
withaws, ec2
- Use workspace
production
when a Tag Query includesaws, ec2, production
for a Workflow or Command - Override When Modified file patterns for directory
ec2
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.
- 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.
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 aterragrunt.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
, ortfvars
- The pull request changed files includes a
terragrunt.hcl
file in the_templates/
directory
- The directory contains a
Longest glob wins.