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 files is the recommended way to define the stack manifests with the default configurations for organizations, OUs/tenants, accounts and regions. The _defaults.yaml files themselves are not top-level Atmos stacks, they just contain the default values for the organizations, OUs/tenants, accounts and regions (to make the entire configuration reusable and DRY)
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. Sprig Functions 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>
```
  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