Customize Stack Behavior

The stacks section of the atmos.yaml defines how Atmos locates and manages your stack configurations. Think of it as the bootstrapping configuration. Here you can define the stack name pattern or template used to build the "slugs" and specify where to find stack files.

important

Do not confuse this configuration with stack configuration. This configuration below is defined in the atmos.yaml and instructs atmos where to find your stack configurations.

atmos.yaml

stacks:
  # Can also be set using 'ATMOS_STACKS_BASE_PATH' ENV var, or '--config-dir' and '--stacks-dir' command-line arguments
  # Supports both absolute and relative paths
  base_path: "stacks"

  # Can also be set using 'ATMOS_STACKS_INCLUDED_PATHS' ENV var (comma-separated values string)
  included_paths:
    # Tell Atmos to search for the top-level stack manifests in the `orgs` folder and its sub-folders
    - "orgs/**/*"

  # Can also be set using 'ATMOS_STACKS_EXCLUDED_PATHS' ENV var (comma-separated values string)
  excluded_paths:
    # Tell Atmos that all `_defaults.yaml` files are not top-level stack manifests
    - "**/_defaults.yaml"

  # To define Atmos stack naming convention, use either `name_pattern` or `name_template`.
  # `name_template` has higher priority (if `name_template` is specified, `name_pattern` will be ignored).
  # `name_pattern` uses the predefined context tokens {namespace}, {tenant}, {environment}, {stage}.
  # `name_pattern` can also be set using 'ATMOS_STACKS_NAME_PATTERN' ENV var
  name_pattern: "{tenant}-{environment}-{stage}"
  # `name_template` is a Golang template.
  # For the template tokens, and you can use any Atmos sections and attributes that the Atmos command
  # `atmos describe component <component> -s <stack>` generates (refer to https://atmos.tools/cli/commands/describe/component).
  # `name_template` can also be set using 'ATMOS_STACKS_NAME_TEMPLATE' ENV var
  # name_template: "{{.vars.tenant}}-{{.vars.environment}}-{{.vars.stage}}"

• stacks.base_path specifies the path to the folder where all Atmos stack config files (stack manifests) are defined. If the global base_path is not provided or is an empty string, stacks.base_path is an independent setting that supports both absolute and relative paths. If the global base_path is defined, stacks.base_path is relative to the global base_path

• stacks.included_paths tells Atmos where to search for the top-level stack manifests

  note

  Atmos top-level stack manifests are configuration files that define all settings and components for the corresponding environment (organization, OU/tenant, account, region), and they are used in atmos CLI commands like atmos terraform plan <component> -s <top-level-stack> and atmos terraform apply <component> -s <top-level-stack>

• stacks.excluded_paths tells Atmos which paths from stacks.included_paths to exclude. For example, we will exclude the config files that don't contain the top-level stack manifests, but just define the default values that get imported into top-level stack manifests

  note

  The _defaults.yaml naming convention is the recommended way to define stack manifests with default configurations for organizations, OUs/tenants, accounts and regions. This is a naming convention, not an Atmos feature. The _defaults.yaml files themselves are not top-level Atmos stacks—they just contain default values to make the entire configuration reusable and DRY. The underscore prefix ensures these files sort to the top of directory listings and are visually distinct from actual stack configurations.

  info

  The _defaults.yaml stack manifests are not imported into other Atmos manifests automatically. You must explicitly import them using imports. Atmos has no special knowledge of this naming pattern—these files are only excluded from stack discovery because they match the **/_defaults.yaml pattern in the excluded_paths configuration.

  See the _defaults.yaml Design Pattern for a complete explanation of this convention.

• stacks.name_pattern configures the name pattern for the top-level Atmos stacks using the context variables namespace, tenant, environment and stage as the tokens. Depending on the structure of your organization, OUs, accounts and regions, set stacks.name_pattern to the following:

  • name_pattern: {stage} - if you use just one region and a few accounts (stages) in just one organization and one OU. In this case, the top-level Atmos stacks will use just the stage (account) in their names, and to provision the Atmos components in the top-level stacks, you will be executing Atmos commands like atmos terraform apply <component> --stack dev, atmos terraform apply <component> --stack staging and atmos terraform apply <component> --stack prod

  • name_pattern: {environment}-{stage} - if you have multiple regions and accounts (stages) in just one organization and one OU. In this case, the top-level Atmos stacks will use the environment (region) and stage (account) in their names, and to provision the Atmos components in the top-level stacks, you will be executing Atmos commands like atmos terraform apply <component> --stack ue2-dev, atmos terraform apply <component> --stack uw2-staging and atmos terraform apply <component> --stack ue1-prod. Note that the name_pattern can also be defined as {stage}-{environment}, in which case the Atmos commands will look like atmos terraform apply <component> --stack dev-ue2

  • name_pattern: {tenant}-{environment}-{stage} - if you have multiple regions, OUs (tenants) and accounts (stages) in just one organization. In this case, the top-level Atmos stacks will use the tenant, environment (region) and stage (account) in their names, and to provision the Atmos components in the top-level stacks, you will be executing Atmos commands like atmos terraform apply <component> --stack plat-ue2-dev, atmos terraform apply <component> --stack core-uw2-staging and atmos terraform apply <component> --stack plat-ue1-prod, where plat and core are the OUs/tenants in your organization

  • name_pattern: {namespace}-{tenant}-{environment}-{stage} - if you have a multi-org, multi-tenant, multi-account and multi-region architecture. In this case, the top-level Atmos stacks will use the namespace, tenant, environment (region) and stage (account) in their names, and to provision the Atmos components in the top-level stacks, you will be executing Atmos commands like atmos terraform apply <component> --stack org1-plat-ue2-dev, atmos terraform apply <component> --stack org2-core-uw2-staging and atmos terraform apply <component> --stack org2-plat-ue1-prod, where org1 and org2 are the organization names (defined as namespace in the corresponding _defaults.yaml config files for the organizations)

• stacks.name_template serves the same purpose as stacks.name_pattern (defines the naming convention for the top-level Atmos stacks), but provides much more functionality. Instead of using the predefined context variables as tokens, it uses Go templates. Atmos Template Functions, Sprig Functions, Gomplate Functions, and Gomplate Datasources are supported as well

  • For the Go template tokens, and you can use any Atmos sections (e.g. vars, providers, settings) that the Atmos command atmos describe component <component> -s <stack> generates for a component in a stack.

  • name_template: "{{.vars.tenant}}-{{.vars.environment}}-{{.vars.stage}}" defines the same name pattern for the top-level Atmos stacks as name_pattern: "{tenant}-{environment}-{stage}" does

  • Since stacks.name_template allows using any variables form the vars section (and other sections), you can define your own naming convention for your organization or for different clouds (AWS, Azure, GCP). For example, in the corresponding _defaults.yaml stack manifests, you can use the following variables:

    • org instead of namespace
    • division instead of tenant
    • region instead of environment
    • account instead of stage

    Then define the following stacks.name_template in atmos.yaml:

    atmos.yaml

    stacks:
      name_template: "{{.vars.division}}-{{.vars.account}}-{{.vars.region}}"

    You will be able to execute all Atmos commands using the newly defined naming convention:

    atmos terraform plan <component> -s <division-account-region>
    atmos terraform apply <component> -s <division-account-region>
    atmos describe component <component> -s <division-account-region>

    name_template can have complex logic and use template expressions and functions. The following template defines a name_template that builds a stack_name string by validating and concatenating several input variables in a hierarchical order.

    atmos.yaml

    name_template: |-
      {{- $ns := .vars.namespace -}}
      {{- $tenant := .vars.tenant -}}
      {{- $env := .vars.environment -}}
      {{- $stage := .vars.stage -}}
      {{- $stack_name := "" -}}
    
      {{- if eq $ns "" -}}
      {{- fail "Error: 'namespace' is required." -}}
      {{- end -}}
    
      {{- if and (ne $tenant "") (eq $ns "") -}}
      {{- fail "Error: 'tenant' requires 'namespace'." -}}
      {{- end -}}
    
      {{- if and (ne $env "") (or (eq $tenant "") (eq $ns "")) -}}
      {{- fail "Error: 'environment' requires 'tenant' and 'namespace'." -}}
      {{- end -}}
    
      {{- if and (ne $stage "") (or (eq $env "") (eq $tenant "") (eq $ns "")) -}}
      {{- fail "Error: 'stage' requires 'environment', 'tenant', and 'namespace'." -}}
      {{- end -}}
    
      {{- if ne $tenant "" -}}
      {{- $stack_name = $tenant -}}
      {{- end -}}
    
      {{- if ne $env "" -}}
      {{- $stack_name = printf "%s-%s" $stack_name $env -}}
      {{- end -}}
    
      {{- if ne $stage "" -}}
      {{- $stack_name = printf "%s-%s" $stack_name $stage -}}
      {{- end -}}
    
      {{- $stack_name -}}

    It pulls values from the Atmos section vars and assigns them to local template variables:

    • namespace
    • tenant
    • environment
    • stage

    The template enforces hierarchical dependencies between variables:

    • namespace is required
    • If tenant is provided, namespace must also be set
    • If environment is provided, both tenant and namespace must be set
    • If stage is provided, then environment, tenant, and namespace must all be set

    If validations pass, it constructs the stack_name progressively:

    • Starts with tenant if it exists
    • Appends environment if it exists
    • Appends stage if it exists

    The template outputs the resulting stack name. For example, if the variables are:

    namespace: acme
    tenant: plat
    environment: ue2
    stage: prod

    The resulting stack name will be plat-ue2-prod.

note

Use either stacks.name_pattern or stacks.name_template to define the naming convention for the top-level Atmos stacks.

stacks.name_template has higher priority.

If stacks.name_template is specified, stacks.name_pattern will be ignored.

tip

Refer to Atmos Design Patterns for the examples on how to configure the stacks section in atmos.yaml for different use-cases