definitions

The definitions configuration provides a dedicated section for defining YAML anchors that can be referenced throughout your Terrateam configuration. This enables DRY (Don’t Repeat Yourself) principles by allowing you to define reusable configuration templates.

Terrateam does not interpret the contents of definitions. It is a free-form object whose only purpose is to hold anchors. Every other top-level key is validated against the configuration schema, so the values you reference from an anchor must be valid at the place where they are used.

Purpose

YAML anchors allow you to:

• Define configuration once and reuse it multiple times
• Maintain consistency across similar configurations
• Reduce configuration file size and complexity
• Make updates easier by changing values in one place

Syntax

definitions:
  # Define anchors here using &anchor_name
  std_plan: &std_plan
    - type: init
    - type: plan

# Reference anchors elsewhere using *anchor_name
workflows:
  - tag_query: ""
    plan: *std_plan

Rules

Terrateam resolves anchors, aliases, and the << merge key when it parses the file. The following rules apply:

• *anchor inserts the anchored value. It can be a scalar, a list, or a map.
• <<: *anchor merges the keys of an anchored map into the current map. Keys written in the current map override merged keys.
• To merge several maps, use a list: <<: [*first, *second]. Writing <<: twice in the same map is a parse error.
• Merging is shallow. A key in the current map replaces the merged key of the same name; nested maps are not merged.
• An alias cannot address a nested value. *anchor.key is a parse error. Anchor the nested value separately.
• A list alias inside a list produces a nested list. Use the alias as the entire value (plan: *std_plan) or anchor the individual entries.

Examples

Reusable Engine Configuration

Define a standard engine configuration once and reuse it across workflows:

definitions:
  default_engine: &default_engine
    name: terraform
    version: "1.5.0"

workflows:
  - tag_query: "dev"
    engine: *default_engine

  - tag_query: "staging"
    engine:
      <<: *default_engine
      version: "1.5.7"

Standard Workflow Steps

Define common workflow step sequences:

definitions:
  standard_plan: &standard_plan
    - type: init
    - type: run
      cmd: ["terraform", "fmt", "-check"]
    - type: run
      cmd: ["terraform", "validate"]
    - type: plan
    - type: checkov

workflows:
  - tag_query: "dev"
    plan: *standard_plan
  - tag_query: "production"
    plan: *standard_plan

To compose different step lists from the same building blocks, anchor the individual steps:

definitions:
  step_init: &step_init
    type: init
  step_plan: &step_plan
    type: plan
  step_checkov: &step_checkov
    type: checkov

workflows:
  - tag_query: "dev"
    plan:
      - *step_init
      - *step_plan
  - tag_query: "production"
    plan:
      - *step_init
      - *step_plan
      - *step_checkov

Common Access Control Policies

Define reusable access control patterns:

definitions:
  dev_access: &dev_access
    plan: ["*"]
    apply: ["team:developers", "team:platform"]

  prod_access: &prod_access
    plan: ["*"]
    apply: ["team:platform"]
    apply_force: ["team:sre"]

access_control:
  enabled: true
  policies:
    - tag_query: "dev or staging"
      <<: *dev_access

    - tag_query: "production"
      <<: *prod_access

Environment-Specific Settings

Environment variables for a step are set with the env key. Define the variables once per environment:

definitions:
  aws_dev: &aws_dev
    AWS_REGION: us-east-1
    AWS_ROLE_ARN: arn:aws:iam::123456789012:role/terrateam-dev

  aws_prod: &aws_prod
    AWS_REGION: us-east-1
    AWS_ROLE_ARN: arn:aws:iam::123456789012:role/terrateam-prod

workflows:
  - tag_query: "dev"
    plan:
      - type: init
        env: *aws_dev
      - type: plan
        env: *aws_dev

  - tag_query: "production"
    plan:
      - type: init
        env: *aws_prod
      - type: plan
        env: *aws_prod

Shared Apply Requirements

Define approval rules once and apply them to several tag queries:

definitions:
  strict_checks: &strict_checks
    approved:
      enabled: true
      any_of: ["team:platform"]
      any_of_count: 2
    merge_conflicts:
      enabled: true
    status_checks:
      enabled: true

apply_requirements:
  checks:
    - tag_query: "production"
      <<: *strict_checks
    - tag_query: "staging"
      <<: *strict_checks

Shared Directory Configuration

Define common when_modified settings and tags:

definitions:
  shared_modules: &shared_modules
    file_patterns: ["${DIR}/*.tf", "modules/**/*.tf"]
    autoplan: true
    autoapply: false

dirs:
  terraform/networking:
    tags: [networking]
    when_modified: *shared_modules

  terraform/compute:
    tags: [compute]
    when_modified: *shared_modules

Advanced Usage

Merging Multiple Anchors

You can merge several anchors with one <<: key that takes a list:

definitions:
  base_engine: &base_engine
    name: terraform

  pinned_version: &pinned_version
    version: "1.5.0"

workflows:
  - tag_query: ""
    engine:
      <<: [*base_engine, *pinned_version]

Anchor Scoping

Anchors defined in definitions are available throughout the entire configuration file, as long as definitions comes before the first reference:

definitions:
  shared_tags: &shared_tags [aws, managed]

dirs:
  networking:
    tags: *shared_tags
  compute:
    tags: *shared_tags

Best Practices

1. Use descriptive anchor names that clearly indicate their purpose
2. Group related anchors together in the definitions section
3. Document complex anchors with comments explaining their use
4. Keep anchors focused on a single responsibility
5. Test anchor references with terrateam repo-config to ensure they resolve correctly

Limitations

• Anchors must be defined before they are referenced
• YAML anchors are resolved at parse time, not runtime
• Cannot use environment variables or dynamic values in anchor definitions
• Circular references are not supported