Stack Mixins

Advanced

Mixins are reusable snippets of configurations (like regions, tags, etc) included in stack configurations to avoid repetition and enhance modularity. They allow for defining common settings, variables, or configurations once and applying them efficiently across various stacks.

important

Mixins are treated the same as all other imports in Atmos, with no special handling or technical distinction.

Use-cases

Here are some use-cases for when to use mixins.

Mixins by Region

Mixins organized by region will make it very easy to configure where a stack is deployed by simply changing the imported mixin.

Consider naming them after the canonical region name for the cloud provider you're using.

For example, here's what it would look like for AWS. Let's name this file mixins/region/us-east-1.yaml. Now, anytime we want a Parent Stack deployed in the us-east-1 region, we just need to specify this import, and we'll automatically inherit all the settings for that region.

For example, let's define a mixin with the defaults for operating in the us-east-1 region:

mixins/region/us-east-1.yaml

vars:
  region: us-east-1   # the canonical cloud region
  availability_zones: # the designated availability zones to use in this region
  - us-east-1a
  - us-east-1b

Then we can use this mixin, anytime we deploy in us-east-1 to ensure we conform to the organization's standards.

stacks/prod/network.yaml

imports:
- mixins/region/us-east-1

terraform:
  components:
    vpc:
    # ...

Mixins by Stage

Provide the default settings for operating in a particular stage (e.g. Dev, Staging, Prod) to enforce consistency.

For example, let's define the stage name and required tags for production in the mixin file named mixins/stage/prod.yaml

mixins/stage/prod.yaml

vars:
  stage: prod
  tags:
    CostCenter: 12345

Now, anytime we want to provision a parent stack in production, we'll want to add this to the imports:

stacks/prod/backing-services.yaml

imports:
- mixins/stage/prod

terraform:
  components:
    rds-cluster:
    # ...

Use Mixins for Naming Conventions

This simple example highlights a simple fix for one of the most common issues in enterprise organizations: naming inconsistency. Using a mixin is a great way for organizations ensure naming conventions are followed consistently.

For example, there are many ways developers will define production.

• e.g. prd
• e.g. prod
• e.g. production
• e.g. Production
• e.g. Prod
• e.g. PROD
• etc

To avoid this situation, use the mixin mixins/stage/prod and always use the appropriate naming convention.

Mixins for Retry Policies

Mixins are not limited to vars. Use the overrides section to share a retry policy across components that do not share a common base component.

Sharing retry with the whole stack? Skip the mixin

If the retry policy should apply to every supported component in the stack, put retry: at the stack-manifest root instead — see Stack-Level Defaults. No mixin file or import needed. Reach for the mixin pattern below when the policy should apply to only part of a stack.

For example, define retry conditions tuned for transient provider-registry failures in a mixin named mixins/policy/registry-retry.yaml:

mixins/policy/registry-retry.yaml

terraform:
  overrides:
    retry:
      max_attempts: 5
      backoff_strategy: exponential
      initial_delay: 2s
      max_delay: 30s
      conditions:
        - /Bad Gateway/
        - /GOAWAY/
        - /connection reset/
        - /could not query provider registry/

Import this mixin into a stack file. Every terraform component visible from that file picks up the same retry policy. You do not need to add retry to each component. You do not need a shared abstract base component either.

stacks/prod/network.yaml

imports:
- mixins/policy/registry-retry

terraform:
  components:
    vpc:
    # ...
    transit-gateway:
    # ...

Ready to learn this topic?

Mixins are really just a Design Pattern for imports that uses inheritance to alter the Stack configuration in some deliberate way. Learn Design Pattern