Skip to main content

Stack Names

Every stack in Atmos has a logical name used for identification, the -s flag, dependencies, and Terraform workspaces. You can either set this name explicitly using the name field in your stack manifest, or compute it programmatically using name_template in atmos.yaml.

Choosing Your Approach​

Atmos offers two approaches for stack naming. Choose based on your infrastructure's consistency:

ApproachWhereWhen to Use
name_templateatmos.yamlConsistent context variables across all stacks
nameStack manifestInconsistent naming, migrations, or legacy infrastructure

Use name_template When​

You should use name_template in atmos.yaml when:

  • You have consistent context variables (like namespace, tenant, environment, stage) across all stacks
  • All your root modules use these variables deterministically
  • You want programmatic, convention-based naming (e.g., following the null-label pattern)

atmos.yaml

stacks:
  name_template: "{{ .vars.tenant }}-{{ .vars.environment }}-{{ .vars.stage }}"

With this configuration, a stack with vars.tenant: acme, vars.environment: ue1, and vars.stage: prod will automatically be named acme-ue1-prod.

Use name When​

You should use the name field in your stack manifest when:

  • You're migrating from Terragrunt or another tool and need to preserve existing workspace names
  • Your infrastructure has inconsistent naming that doesn't follow a pattern
  • You have legacy stacks that predate your naming conventions
  • You need to match existing Terraform workspace names exactly
  • Any inconsistency in your vars would break a deterministic template

stacks/legacy-prod.yaml

name: "my-legacy-prod-stack"

import:
  - catalog/defaults

components:
  terraform:
    vpc:
      vars:
        cidr: "10.0.0.0/16"

With this configuration, the stack is identified as my-legacy-prod-stack regardless of the filename or any name_template in atmos.yaml.

Precedence Order​

When determining a stack's name, Atmos uses this precedence order:

  1. name (highest) - Explicit name from stack manifest
  2. name_template - Go template from atmos.yaml
  3. name_pattern - Token-based pattern from atmos.yaml
  4. Default - Basename of the stack file (e.g., prod.yaml → prod)

This means the name field always wins, allowing you to override programmatic naming for specific stacks.

Configuration​

The name field is a top-level key in stack manifests, at the same level as import, vars, and components:

name: "explicit-stack-name"

import:
  - catalog/base

vars:
  environment: prod

components:
  terraform:
    vpc:
      vars:
        cidr: "10.0.0.0/16"

Examples​

Migrating from Terragrunt​

When migrating from Terragrunt, your existing Terraform state is tied to specific workspace names. Use name to preserve these:

stacks/us-east-1/prod/vpc.yaml

name: "prod-us-east-1-vpc"  # Matches existing Terraform workspace

import:
  - catalog/vpc

components:
  terraform:
    vpc:
      vars:
        cidr: "10.0.0.0/16"

This ensures atmos terraform apply vpc -s prod-us-east-1-vpc uses the existing state without requiring state migrations.

Legacy Infrastructure​

For infrastructure that predates your naming standards:

stacks/old-datacenter.yaml

name: "dc1-legacy-infra"  # Historical name that must be preserved

components:
  terraform:
    network:
      vars:
        vpc_id: "vpc-abc123"

Mixed Approach​

You can use name_template for most stacks while overriding specific ones with name:

atmos.yaml

stacks:
  name_template: "{{ .vars.tenant }}-{{ .vars.environment }}-{{ .vars.stage }}"

stacks/acme/prod/us-east-1.yaml

# Uses name_template: acme-prod-ue1
vars:
  tenant: acme
  environment: prod
  stage: ue1

components:
  terraform:
    vpc:
      vars:
        cidr: "10.0.0.0/16"

stacks/legacy-acquisition.yaml

name: "acquired-company-prod"  # Overrides name_template for this stack

vars:
  tenant: acquired
  environment: prod
  stage: main

components:
  terraform:
    vpc:
      vars:
        cidr: "10.1.0.0/16"

How Stack Names Are Used​

Stack names appear throughout Atmos:

  • CLI: atmos terraform apply vpc -s my-stack-name
  • Listing: atmos list stacks shows stack names
  • Dependencies: Reference stacks by name in settings.depends_on
  • Terraform Workspaces: Workspace names derive from stack names
  • Describe Commands: atmos describe stacks uses stack names as keys

Best Practices​

  1. Prefer name_template for new projects - Programmatic naming ensures consistency and reduces manual effort.

  2. Use name as an escape hatch - Reserve explicit names for migrations, legacy systems, or acquisitions.

  3. Document your naming convention - Whether using name_template or explicit names, document the pattern for your team.

  4. Consider Terraform state implications - Changing a stack's name changes its workspace, which affects state file location.

  5. Keep names meaningful - Stack names should convey environment, region, and purpose at a glance.