stacks

The stacks key defines named groups of dirspaces (directory + workspace combinations) with shared configuration, variables, and orchestration rules.

Default Configuration

stacks:
  names: {}

Keys

stacks

Key	Type	Description
names	Map	A map of stack names to their configurations

stacks.names.<name>

Each named stack can be either a regular stack (with tag_query) or a nested stack (with stacks).

Regular Stack Configuration

Key	Type	Description
tag_query	String	Required. Tag query expression to match dirspaces for this stack
variables	Map	Optional. Key-value pairs of variables accessible in workflows
rules	Object	Optional. Orchestration rules for this stack

Nested Stack Configuration

Key	Type	Description
stacks	List	Required. List of stack names to include in this nested stack
variables	Map	Optional. Key-value pairs of variables accessible in workflows
rules	Object	Optional. Orchestration rules for this stack

stacks.names.<name>.rules

Key	Type	Description
plan_after	List	Stack names that must be applied before this stack can plan
apply_after	List	Stack names that must be applied before this stack can apply
modified_by	List	Stack names that, when modified, trigger this stack as modified
auto_apply	Boolean	Whether to automatically apply this stack after successful plan

Stack Boundaries

A stack is the unit that depends_on orders within. The depends_on key of a directory may only name directories in the same stack, or in a stack that shares a nested stack with it. Naming a directory in an unrelated stack is a configuration error, and the run reports it instead of planning.

To order two stacks that share no nested stack, use the plan_after and apply_after rules above. To let directories in two stacks depend on each other, put both stacks inside one nested stack.

Examples

Basic Environment Stacks

stacks:
  names:
    development:
      tag_query: 'development'
      variables:
        environment: dev
        aws_account: "111111111111"
      rules:
        auto_apply: true

    staging:
      tag_query: 'staging'
      variables:
        environment: staging
        aws_account: "222222222222"
      rules:
        apply_after:
          - development

    production:
      tag_query: 'production'
      variables:
        environment: prod
        aws_account: "333333333333"
      rules:
        apply_after:
          - staging

Layered Infrastructure

stacks:
  names:
    network:
      tag_query: 'network'

    data:
      tag_query: 'database'
      rules:
        plan_after:
          - network

    compute:
      tag_query: 'compute'
      rules:
        plan_after:
          - network

    application:
      tag_query: 'application'
      rules:
        plan_after:
          - data
          - compute

Nested Stacks

stacks:
  names:
    us-east-1:
      tag_query: 'us-east-1'
      variables:
        region: us-east-1

    us-west-2:
      tag_query: 'us-west-2'
      variables:
        region: us-west-2

    all-regions:
      stacks:
        - us-east-1
        - us-west-2
      rules:
        auto_apply: true

Modified By Rules

stacks:
  names:
    shared:
      tag_query: 'dir:shared/*'

    base:
      tag_query: 'dir:base/*'
      rules:
        modified_by:
          - shared
        # plan_after is implicitly set to [shared]

    services:
      tag_query: 'dir:services/*'
      rules:
        modified_by:
          - base
        plan_after:
          - shared
        # Explicit plan_after, so no implicit construction

Using Stack Variables

stacks:
  names:
    production:
      tag_query: 'production'
      variables:
        tf_version: "1.5.7"
        region: "us-east-1"

workflows:
  - tag_query: ''
    engine:
      name: terraform
      version: '${tf_version}'
    plan:
      - type: init
        extra_args: ['-backend-config=region=${region}']
      - type: plan

Integration with Access Control

stacks:
  names:
    production:
      tag_query: 'production'

access_control:
  policies:
    - tag_query: 'stack_name:production'
      plan: ['*']
      apply: ['team:sre']