Skip to content
Terrateam

YAML Anchors for Configuration Reuse

YAML anchors enable DRY (Don’t Repeat Yourself) principles in your Terrateam configuration by defining reusable templates. This reduces configuration size, ensures consistency, and makes updates easier.

When to Use YAML Anchors

Section titled “When to Use YAML Anchors”

Use YAML anchors when you have:

  • Multiple workflows with similar configurations
  • Repeated engine settings across environments
  • Common workflow step sequences
  • Standardized access control patterns
  • Shared directory configurations

Basic Syntax

Section titled “Basic Syntax”

Define anchors in the definitions section and reference them throughout your configuration:

definitions:
  my_config: &my_config
    key: value


workflows:
  - name: default
    custom: *my_config

Common Patterns

Section titled “Common Patterns”

Shared Engine Configuration

Section titled “Shared Engine Configuration”

Define once, use everywhere:

definitions:
  standard_engine: &standard_engine
    version: 1.6.0
    environment:
      TF_IN_AUTOMATION: "true"
      TF_INPUT: "false"


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


  - name: production
    tag_query: "prod"
    engine:
      <<: *standard_engine
      environment:
        <<: *standard_engine.environment
        PRODUCTION: "true"

Reusable Workflow Steps

Section titled “Reusable Workflow Steps”

Create standard workflow patterns:

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


  security_steps: &security_steps
    - type: checkov
    - type: run
      cmd: ["tfsec", "."]


workflows:
  - name: default
    plan:
      - *validation_steps
      - *security_steps
      - type: plan
      - type: cost_estimation

Environment-Specific Configurations

Section titled “Environment-Specific Configurations”

Manage multiple environments efficiently:

definitions:
  # AWS environment configurations
  aws_dev: &aws_dev
    AWS_REGION: us-east-1
    AWS_ROLE_ARN: arn:aws:iam::123456789012:role/terrateam-dev
    ENVIRONMENT: development


  aws_staging: &aws_staging
    AWS_REGION: us-east-1
    AWS_ROLE_ARN: arn:aws:iam::123456789012:role/terrateam-staging
    ENVIRONMENT: staging


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


  # Standard requirements
  basic_requirements: &basic_requirements
    - approved
    - status_checks


  strict_requirements: &strict_requirements
    - approved: 2
    - status_checks
    - merge_conflicts


workflows:
  - name: development
    tag_query: "dev"
    engine:
      version: 1.6.0
      environment: *aws_dev
    apply_requirements: *basic_requirements


  - name: staging
    tag_query: "staging"
    engine:
      version: 1.6.0
      environment: *aws_staging
    apply_requirements: *basic_requirements


  - name: production
    tag_query: "production"
    engine:
      version: 1.6.0
      environment: *aws_prod
    apply_requirements: *strict_requirements

Standardized Access Control

Section titled “Standardized Access Control”

Define access patterns once:

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


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


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


    - tag_query: "production"
      <<: *platform_only


    - tag_query: "infrastructure"
      <<: *platform_only

Complex Workflow Templates

Section titled “Complex Workflow Templates”

Build sophisticated reusable patterns:

definitions:
  # Base configuration for all workflows
  base_config: &base_config
    engine:
      version: 1.6.0
      tf_version: 1.5.0


  # Standard validation for all plans
  plan_validation: &plan_validation
    - type: init
    - type: run
      cmd: ["terraform", "fmt", "-check"]
    - type: run
      cmd: ["terraform", "validate"]


  # Security scanning template
  security_scan: &security_scan
    - type: checkov
      when: always
    - type: run
      cmd: ["tfsec", ".", "--format", "json"]
      when: always


  # Complete plan workflow
  full_plan: &full_plan
    - *plan_validation
    - type: plan
    - *security_scan
    - type: cost_estimation
      when: always


  # Notification template
  notifications: &notifications
    - type: run
      cmd: ["echo", "Deployment complete"]
      when: apply_succeeded


workflows:
  - name: feature-branch
    <<: *base_config
    tag_query: "feature"
    plan: *full_plan


  - name: main-branch
    <<: *base_config
    tag_query: "main"
    plan: *full_plan
    apply:
      - type: init
      - type: apply
      - *notifications

Directory Configuration Templates

Section titled “Directory Configuration Templates”

Share configurations across directories:

definitions:
  # S3 backend configuration
  s3_backend: &s3_backend
    backend: s3
    backend_config:
      bucket: terraform-state
      region: us-east-1
      encrypt: true


  # Standard tags for all directories
  base_tags: &base_tags
    - "$dir"
    - "$workspace"


  # Module directories configuration
  module_config: &module_config
    autoplan: false
    tags:
      - *base_tags
      - "module"


dirs:
  - path: terraform/networking
    <<: *s3_backend
    tags:
      - *base_tags
      - "networking"
      - "core"


  - path: terraform/compute
    <<: *s3_backend
    tags:
      - *base_tags
      - "compute"
      - "application"


  - path: modules/**
    <<: *module_config

Advanced Techniques

Section titled “Advanced Techniques”

Merging Multiple Anchors

Section titled “Merging Multiple Anchors”

Combine configurations using the merge operator:

definitions:
  base: &base
    version: 1.6.0


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


  monitoring: &monitoring
    environment:
      DATADOG_API_KEY: ${DATADOG_API_KEY}


  complete: &complete
    <<: *base
    <<: *aws
    <<: *monitoring
    environment:
      CUSTOM: value


workflows:
  - name: monitored
    engine: *complete

Conditional Patterns

Section titled “Conditional Patterns”

Create flexible templates:

definitions:
  # Base steps all workflows need
  required_steps: &required_steps
    - type: init
    - type: plan


  # Optional compliance steps
  compliance_steps: &compliance_steps
    - type: checkov
    - type: cost_estimation
    - type: run
      cmd: ["compliance-check"]


  # Development workflow - basic
  dev_plan: &dev_plan
    - *required_steps


  # Production workflow - full compliance
  prod_plan: &prod_plan
    - *required_steps
    - *compliance_steps


workflows:
  - name: development
    tag_query: "dev"
    plan: *dev_plan


  - name: production
    tag_query: "production"
    plan: *prod_plan

Best Practices

Section titled “Best Practices”
  1. Name anchors descriptively - Use clear names that indicate purpose
  2. Group related anchors - Keep similar configurations together
  3. Document complex anchors - Add comments explaining usage
  4. Start simple - Begin with basic patterns and evolve as needed
  5. Test thoroughly - Verify anchors resolve correctly before deploying

Example: Complete Multi-Environment Setup

Section titled “Example: Complete Multi-Environment Setup”
definitions:
  # Terraform versions
  tf_latest: &tf_latest
    version: 1.6.0
    tf_version: 1.5.0


  # Validation steps
  validate: &validate
    - type: init
    - type: run
      cmd: ["terraform", "fmt", "-check"]
    - type: run
      cmd: ["terraform", "validate"]


  # Security scanning
  security: &security
    - type: checkov
    - type: cost_estimation


  # Environment credentials
  dev_env: &dev_env
    AWS_ROLE_ARN: arn:aws:iam::111111111111:role/terrateam-dev
    AWS_REGION: us-east-1


  prod_env: &prod_env
    AWS_ROLE_ARN: arn:aws:iam::222222222222:role/terrateam-prod
    AWS_REGION: us-east-1


  # Access patterns
  dev_access: &dev_access
    plan: ["*"]
    apply: ["team:developers"]


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


# Apply configurations
workflows:
  - name: development
    <<: *tf_latest
    tag_query: "dev"
    engine:
      <<: *tf_latest
      environment: *dev_env
    plan:
      - *validate
      - type: plan
      - *security
    apply_requirements:
      - approved


  - name: production
    <<: *tf_latest
    tag_query: "production"
    engine:
      <<: *tf_latest
      environment: *prod_env
    plan:
      - *validate
      - type: plan
      - *security
    apply_requirements:
      - approved: 2
      - status_checks


access_control:
  enabled: true
  policies:
    - tag_query: "dev"
      <<: *dev_access
    - tag_query: "production"
      <<: *prod_access

This approach reduces a 200+ line configuration to under 100 lines while improving maintainability and consistency.