Tags and tag queries

Tags and tag queries are essential features in Terrateam that enable you to organize, manage, and automate your Terraform resources effectively. By leveraging tags, you can create logical groupings of resources based on various criteria, such as environment, application, or region. Tag queries allow you to match and filter resources based on these tags, providing a powerful way to target specific subsets of your infrastructure.

Defining tags

Terrateam provides two main ways to define tags: at the top level of your configuration and within the dirs section. Let’s explore each of these options in detail.

Top-level tags

The top-level tags key in your Terrateam configuration file (.terrateam/config.yml) allows you to define custom tags based on dynamic criteria, such as the destination branch of a pull request. These tags can be used to create granular workflows that adapt to the specific context of your pull requests and branches.

Here’s an example of defining top-level tags:

tags:
  dest_branch:
    main: '^main$'
    staging: '^staging$'
    dev: '^dev$'

In this example, we define a custom tag called dest_branch with three possible values: main, staging, and dev. Each value is associated with a regular expression that matches the corresponding branch name.

Top-level tags are dynamic and can be used to match resources based on the context of your pull requests, such as the destination branch.

Directory-level tags

The dirs section of your Terrateam configuration file allows you to assign tags directly to specific directories in your repository. These tags are static and are explicitly associated with the directories you define. Here’s an example of defining tags within the dirs section:

dirs:
  dev:
    tags: [dev]
  staging:
    tags: [staging]
  prod:
    tags: [prod]

In this example, we assign the dev, staging, and prod tags to the corresponding directories in our repository.

Directory-level tags are static and are explicitly assigned to specific directories in your repository.

Crafting tag queries

Tag queries are powerful expressions that allow you to match and filter resources based on their assigned tags. Terrateam supports a rich set of operators and features to create complex and targeted tag queries.

Tag query syntax

Tag queries are boolean expressions that use a combination of tags, operators, and parentheses to define the matching criteria. The following operators and features are supported:

and: Matches resources that have all the specified tags. This is the default operator if none is specified.
or: Matches resources that have at least one of the specified tags.
not: Matches resources that do not have the specified tag.
in: Matches resources that have the specified tag as a fragment in their path or name.
Parentheses: Used to group and prioritize expressions.

Here are some examples of tag queries:

prod and api: Matches resources that have both the prod and api tags.
staging or dev: Matches resources that have either the staging or dev tags.
not deprecated: Matches resources that do not have the deprecated tag.
app in dir: Matches resources that have the app tag as a fragment in their directory path.
(web or api) and prod: Matches resources that have either the web or api tags, and also have the prod tag.

Combining top-level and directory-level tags

You can create even more targeted tag queries by combining tags defined at the top level with tags assigned to directories. This allows you to match resources based on both dynamic criteria (such as the destination branch) and static directory assignments. Here’s an example that combines top-level and directory-level tags in a tag query:

workflows:
  - tag_query: 'dest_branch:main and prod'
    plan:
      - type: init
      - type: plan
    apply:
      - type: init
      - type: apply

In this example, the workflow is triggered only when the dest_branch tag matches main (indicating a pull request targeting the main branch) and the directory being modified has the prod tag assigned to it.

Using tag queries

Tag queries can be used in various parts of your Terrateam configuration to target specific resources and define granular behavior. Let’s explore some common use cases.

Workflows

In the workflows section of your Terrateam configuration file, you can use tag queries to specify which resources a particular workflow should apply to.

Define your tag queries in the tag_query field of each workflow.
Specify the desired plan and apply steps for each workflow.
Terrateam will execute the workflow only on resources that match the specified tag query.

Here’s an example workflow configuration that uses tag queries:

workflows:
  - tag_query: 'dest_branch:main and prod'
    plan:
      - type: init
      - type: plan
    apply:
      - type: init
      - type: apply
  - tag_query: 'dest_branch:staging and staging'
    plan:
      - type: init
      - type: plan
    apply:
      - type: init
      - type: apply

In this example, we define two workflows: one for the main branch and prod environment, and another for the staging branch and staging environment. Each workflow has its own tag query that matches the desired resources.

Commands

When running Terrateam commands, you can use tag queries to target specific resources. Here are some examples:

terrateam plan env:prod and app:api: Runs a plan operation only on resources that have both the env:prod and app:api tags.
terrateam apply staging: Runs an apply operation only on resources that have the staging tag.

Best practices

To make the most of tags and tag queries in Terrateam, consider the following best practices:

Use meaningful and consistent tag names that reflect your organization’s structure, environments, and naming conventions.
Keep your tag queries concise and focused on the specific resources you want to target.
Use parentheses to group and prioritize expressions for clarity and readability.