Skip to main content

Tags

What are Tags?

Tags are a flexible mechanism of using labels to group Terraform resources in a Terraform repository as well as match against those labels. These two uses are called tag sets and tag queries respectively.

Tag Set

A tag set is an unordered and deduplicated list of labels. For example:

[ec2, production, us-west-1]

Every directory and workspace combination have an implicit tag set.

Tag Query

A tag query is a tag set that is used for matching. Every tag in a tag query must exist in a tag set in order to match.

For example, given a tag set of [ec2, production, us-west-1] and a tag query of [us-west-1, production], the tag query would match this tag set because all tags in the tag query are present in the tag set.

However, given the same tag set, a tag query of [iam, us-west-1, production] would not match because the tag iam is not present in the tag set.

Things to note:

  • An empty tag query will match any tag set
  • The order of tags in a tag set and a tag query do not matter
  • Repeated tags are discarded
    • The tag [ec2, ec2, production] is identical to [ec2, production]

Implicit Tags

dir:<name>

  • Each directory in your repository automatically receives a dir:<name> tag, where <name> is the path of the directory without a trailing /
  • A directory of ec2/production/us-west-1 would have an implicit tag of dir:ec2/production/us-west-1 associated with its tag set

workspace:<name>

  • Each workspace in your repository automatically receives a workspace:<name> tag where <name> is the name of the workspace
  • A directory configured with a workspace production would have an implicit tag of workspace:production associated with its tag set
info

Tags are optionally defined when configuring a directory in your repository .terrateam/config.yml 🔗

Learn more 🔗

Custom Tags

See dirs to learn how to create custom tags.

Using Tag Queries

Tag queries are used in commands and workflows to target a specific set of Terraform resources.

Commands

Tag queries are used when executing commands using GitHub Pull Request Comments.

For example, given the following Terrateam configuration:

dirs:
ec2/us-west-1:
tags: ['ec2', 'us-west-1']
workspaces:
production:
development:
ec2/us-east-1:
tags: ['ec2', 'us-east-1']
workspaces:
production:
development:
s3/us-west-1:
tags: ['s3', 'us-west-1']
workspaces:
production:
development:
s3/us-east-1:
tags: ['s3', 'us-east-1']
workspaces:
production:
development:

If a pull request is opened with changes in all of the configured directories above, one could use the following tag queries to execute an apply in various ways:

  • terrateam apply - This will execute an apply on all of the changes
  • terrateam apply us-east-1 - This will execute an apply on across all workspaces in only those directories that have a us-east-1 tag. To express this as dirspaces, the operation would be executed on the following dirspaces:
    • (ec2/us-east-1, production)
    • (ec2/us-east-1, development)
    • (s3/us-east-1, production)
    • (s3/us-east-1, development)
  • terrateam apply workspace:development - This will execute an apply across all changes in the development workspace. To express this as dirspaces, the operation would be executed on the following dirspaces:
    • (ec2/us-west-1, development)
    • (ec2/us-east-1, development)
    • (s3/us-west-1, development)
    • (s3/us-east-1, development)
  • terrateam apply s3 workspace:production - This will execute an apply in the production workspace in both s3 directories. To express this as dirspaces, the operation would be executed on the following dirspaces:
    • (s3/us-west-1, production)
    • (s3/us-east-1, production)
  • terrateam apply dir:s3/us-west-1 workspace:production This will execute an apply in the s3/us-west-1 directory and the production workspace. To express this as dirspaces, the operation would be executed on the following dirspaces:
    • (s3/us-west-1, production)
tip

Notice that the tag query in the command is just a list of tags separated by spaces whereas tags in the configuration is an array. This is meant to reduce the amount of typing and feel more natural in a GitHub Pull Request Comment.

Workflows

Tag queries are used when matching a dirspace to a workflow.

For example, given the following Terrateam configuration:

dirs:
ec2/us-west-1:
tags: ['ec2', 'us-west-1']
workspaces:
production:
development:
ec2/us-east-1:
tags: ['ec2', 'us-east-1']
workspaces:
production:
development:
s3/us-west-1:
tags: ['s3', 'us-west-1']
workspaces:
production:
development:
s3/us-east-1:
tags: ['s3', 'us-east-1']
workspaces:
production:
development:
workflows:
- tag_query: 'ec2 workspace:production'
plan:
- type: init
- type: plan
apply:
- type: init
- type: apply
- type: run
run_on: failure
cmd: ['bin/post-alert', 'Apply failed on $TERRAFORM_DIR']

Workflows allow the sequence of operations to run when executing a command to be customized. The specific workflow is chosen by applying the tag query to the tags associated with the dirspace. If no tag queries match, the default workflow is used. The order of operations to select a workflow is:

  1. User executes a command, such as terrateam plan or terrateam apply. They may specify a tag query in this command as well.
  2. Terrateam finds all changes in the pull request that match the tag query (no tag query matches all changes) and translates those to the specific dirspaces to execute.
  3. Those dirspaces are mapped to the tag set for each one. For example, the dirspace (ec2/us-east-1, production) would have the tag set: [ec2, us-east-1, dir:ec2/us-east-1, workspace:production].
  4. Before executing each dirspace, Terrateam iterates through the list of workflows, comparing the tag_query to the tag set and chooses the first workflow that matches.
  5. For the dirspace, Terrateam executes the matching workflow, or the default workflow if no workflow is found.
tip

Notice that the tag_query in the workflow is a string containing tags separated by spaces whereas tags in the configuration is an array. This is meant to match how tag queries are specified in commands.