Skip to content

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.

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 /.

workspace:<name>

Each workspace in your repository automatically receives a workspace:<name> tag where <name> is the name of the workspace.

Tag Query

The value of tag sets is that they can be queried against. For example, access control uses tag queries to determine which rules to apply to a dirspace.

A tag query is a boolean expression which supports parenthesis, and, or, not, and in operators.

  • A tag query is implicitly an and unless otherwise specified. For example, the tag query ec2 production is the same as ec2 and production. This will match only those dirspaces which have ec2 and production in their tag set.
  • The tag query ec2 or production will match all dirspaces which have ec2 or production in their tag set.
  • not ec2 will match all dirspaces that do not have ec2 in their tag sets.
  • ec2 in dir matches directory that has ec2 as a fragment in its path. For example the directory environments/production/ec2/us-east-1 would be matched by ec2 in dir. in does not match partial directory fragments. For example, the following directory would not match: environments/production/ec2-iam/us-east-1. If using with not it is required to use parenthesis: not (ec2 in dir).
  • Quotes can be used to enforce that a word is interpreted as a tag. For example, "and", "or", and "not" are the tags matching those words rather than the operators.
  • Parenthesis can be combined with any of these to create more complicated expression. For example ec2 and (dev or staging).

Custom Tags

See Directories and Globs documentation 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.