Tags and Tag Queries


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


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.


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.

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.

  • 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]

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.