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.

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
  anchor_name: &anchor_name
    key: value

# Reference anchors elsewhere using *anchor_name
some_config: *anchor_name

Examples

Reusable Engine Configuration

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

definitions:
  default_engine: &default_engine
    version: 1.5.0
    environment:
      TF_IN_AUTOMATION: "true"
      TF_INPUT: "false"

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

  - name: staging
    tag_query: "staging"
    engine:
      <<: *default_engine
      environment:
        <<: *default_engine.environment
        ENVIRONMENT: "staging"

Standard Workflow Steps

Define common workflow step sequences:

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

workflows:
  - name: default
    plan:
      - *standard_checks
      - type: plan
    apply:
      - type: init
      - type: apply

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

Define environment configurations:

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:
  - name: development
    tag_query: "dev"
    engine:
      version: 1.5.0
      environment: *aws_dev

  - name: production
    tag_query: "production"
    engine:
      version: 1.5.0
      environment: *aws_prod

Complex Workflow Templates

Create sophisticated reusable workflow patterns:

definitions:
  # Base security scanning
  security_scan: &security_scan
    - type: checkov
      when: always
    - type: run
      cmd: ["tfsec", "."]
      when: always

  # Standard plan workflow
  standard_plan: &standard_plan
    - type: init
    - type: plan
    - <<: *security_scan
    - type: cost_estimation

  # Production approval requirements
  prod_requirements: &prod_requirements
    - approved: 2
    - status_checks
    - merge_conflicts

workflows:
  - name: development
    tag_query: "dev"
    plan: *standard_plan
    apply_requirements:
      - approved

  - name: production
    tag_query: "production"
    plan: *standard_plan
    apply_requirements: *prod_requirements

Shared Directory Configuration

Define common directory settings:

definitions:
  base_tags: &base_tags
    - "$dir"
    - "$workspace"

  standard_backend: &standard_backend
    backend: s3
    backend_config:
      bucket: terraform-state
      region: us-east-1

dirs:
  - path: terraform/networking
    <<: *standard_backend
    tags:
      - *base_tags
      - networking

  - path: terraform/compute
    <<: *standard_backend
    tags:
      - *base_tags
      - compute

Advanced Usage

Merging Anchors

You can merge multiple anchors using the <<: merge operator:

definitions:
  base_config: &base_config
    version: 1.5.0

  aws_config: &aws_config
    environment:
      AWS_REGION: us-east-1

  extended_config: &extended_config
    <<: *base_config
    <<: *aws_config
    environment:
      CUSTOM_VAR: value

workflows:
  - name: default
    engine: *extended_config

Anchor Scoping

Anchors defined in definitions are available throughout the entire configuration file:

definitions:
  my_anchor: &my_anchor
    key: value

# Can be used anywhere in the config
dirs:
  - path: terraform
    custom: *my_anchor

workflows:
  - name: default
    custom: *my_anchor

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