Basic Stack Organization

Atmos Design Pattern

The Basic Stack Organization pattern shows the simplest way to organize stacks: one file per environment (dev, staging, prod). This is how most teams start with Atmos.

Use-cases

Use the Basic Stack Organization pattern when:

• You have a single AWS account per environment (dev, staging, prod)

• You're deploying to one region

• You want the simplest possible setup to get started

Directory Structure

Terminal

   ├── stacks
   │   ├── catalog  # component defaults
   │   │   └── vpc
   │   │       └── defaults.yaml
   │   └── deploy
   │       ├── dev.yaml
   │       ├── staging.yaml
   │       └── prod.yaml
   │
   └── components
       └── terraform
           └── vpc

Configure atmos.yaml

atmos.yaml

components:
  terraform:
    base_path: "components/terraform"

stacks:
  base_path: "stacks"
  included_paths:
    - "deploy/**/*"
  name_template: "{{.vars.stage}}"

Configure Component Defaults

Define shared configuration in the catalog:

stacks/catalog/vpc/defaults.yaml

components:
  terraform:
    vpc:
      vars:
        enabled: true
        nat_gateway_enabled: true
        max_subnet_count: 3

Configure Environment Stacks

Each environment imports the defaults and sets environment-specific values:

stacks/deploy/dev.yaml

import:
  - catalog/vpc/defaults

vars:
  stage: dev

components:
  terraform:
    vpc:
      vars:
        # Dev-specific: smaller, cheaper
        nat_gateway_enabled: false
        max_subnet_count: 2

stacks/deploy/staging.yaml

import:
  - catalog/vpc/defaults

vars:
  stage: staging

components:
  terraform:
    vpc:
      vars:
        # Staging mirrors prod but smaller
        max_subnet_count: 2

stacks/deploy/prod.yaml

import:
  - catalog/vpc/defaults

vars:
  stage: prod

components:
  terraform:
    vpc:
      vars:
        # Prod: full configuration
        map_public_ip_on_launch: false

Deploy

atmos terraform apply vpc -s dev
atmos terraform apply vpc -s staging
atmos terraform apply vpc -s prod

Growing Beyond Basic

As your infrastructure grows, you'll likely need:

Need	Pattern
Multiple regions	Multi-Region Configuration
Multiple teams/tenants	Organizational Hierarchy
Reusable region settings	Mixins
Many components	Layered Stack Configuration

Related Patterns

• Multi-Region Configuration - Add regions to this structure
• Component Catalog - Organize component defaults
• Inline Component Configuration - Even simpler, single-file approach

References

• Catalogs
• Stack Imports