Tags

Tags in Terrateam allow you to define custom labels that can be used to match and filter resources in your Terraform configuration. While the dirs section of the Terrateam configuration file also supports tags, this documentation specifically focuses on the top-level tags key, which enables you to define tags based on dynamic criteria such as the destination branch of a pull request.

By leveraging the top-level tags configuration, you can create more granular and flexible workflows that adapt to the specific context of your pull requests and branches.

Configuration

The top-level tags are configured in the .terrateam/config.yml file under the tags key. Here’s an example configuration:

tags:
  dest_branch:
    main: '^main$'
    staging: '^staging$'
    dev: '^dev$'
dirs:
  dev:
    tags: [dev]
  staging:
    tags: [staging]
  prod:
    tags: [prod]

In this example, the tags section defines a tag called dest_branch, which has three possible values: main, staging, and dev. Each value is associated with a regular expression that matches the corresponding branch name.

The dirs section, on the other hand, defines tags for specific directories in your repository. These tags are static and are assigned directly to the directories.

The top-level tags configuration allows you to create dynamic tags based on the context of your pull requests, such as the destination branch. These tags can then be used in combination with the static tags defined in the dirs section to create more targeted and flexible workflows.

Tag definition

Each tag in the top-level tags configuration is defined as a key-value pair. The key represents the tag name, and the value is a map of tag values and their corresponding regular expressions. In the example above, the dest_branch tag is defined with three possible values: main, staging, and dev. Each value is associated with a regular expression that matches the corresponding branch name.

Using tags in tag queries

Once tags are defined in the top-level tags configuration, you can use them in tag queries to match and filter resources based on specific criteria. Tag queries are used in various parts of the Terrateam configuration, such as workflows and access control.

Here’s an example of using the dest_branch tag in a workflow configuration:

workflows:
  - tag_query: 'dest_branch:main'
    plan:
      - type: env
        method: source
        cmd: ['echo', 'main']
      - type: init
      - type: plan
    apply:
      - type: env
        method: source
        cmd: ['echo', 'main']
      - type: init
      - type: apply

In this example, the workflow is triggered when the dest_branch tag matches the main value. The tag_query field specifies the condition that must be met for the workflow to be executed.

You can also combine tags from the top-level tags configuration with tags defined in the dirs section to create more specific and targeted workflows. For example:

workflows:
  - tag_query: 'dest_branch:main and prod'
    plan:
      - type: env
        method: source
        cmd: ['echo', 'main']
      - type: init
      - type: plan
    apply:
      - type: env
        method: source
        cmd: ['echo', 'main']
      - type: init
      - type: apply

In this case, the workflow is triggered only when the dest_branch tag matches main and the directory being modified has the prod tag assigned to it in the dirs section.

Matching tags with regular expressions

Terrateam uses regular expressions to match tags against the defined values in the top-level tags configuration. This allows for flexible and powerful matching capabilities. In the example configuration, the regular expressions are defined as follows:

• '^main$': Matches the exact string main.
• '^staging$': Matches the exact string staging.
• '^dev$': Matches the exact string dev.

You can customize the regular expressions to match your specific branch naming conventions or other criteria.

Considerations

When configuring tags in the top-level tags section of the Terrateam configuration, keep the following considerations in mind:

• Tags defined in the top-level tags section are dynamic and can be used to match resources based on the context of your pull requests, such as the destination branch.
• Tags defined in the dirs section are static and are assigned directly to specific directories in your repository.
• You can use tags from both the top-level tags configuration and the dirs section in combination to create more targeted and flexible workflows.