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.

Experimental

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​

Stack Names ExampleView full example

Stack Names Example

This example demonstrates imperative stack naming using the name field in stack manifests.

Overview

Stack names are determined by the following precedence (highest to lowest):

  1. name - Explicit name from the stack manifest (always wins)
  2. name_template - Template-based naming (if configured)
  3. name_pattern - Pattern-based naming (if configured)
  4. Filename - Basename of the stack file (fallback)

This example demonstrates the name field, which always takes precedence over other naming methods.

Stacks

FileName FieldCanonical Name
stacks/dev.yaml(none)dev
stacks/prod.yamlproductionproduction

Usage

# List all stacks
atmos list stacks

# Dev stack - uses filename
atmos terraform plan mock -s dev

# Prod stack - uses explicit name
atmos terraform plan mock -s production

# This will NOT work (filename is not the canonical name):
# atmos terraform plan mock -s prod

Key Points

  • The name field takes precedence over the filename
  • Only the canonical name is valid for the -s flag
  • This is useful for migrations, legacy infrastructure, or matching existing Terraform workspace names
Browse all files

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.