Skip to main content

Folder Structure

At the root of your project, you’ll typically find an atmos.yaml configuration file. This file defines how Atmos should discover your stack files for configuration and your Terraform root modules as components.

You will learn

  • How to organize your project on the file system
  • How to separate configuration from components
  • Different ways to organize your project

Atmos is fully configurable, and you can organize your project in any way that makes sense for your team by adusting the paths in atmos.yaml. We also provide detailed guidance on organizing your folder structure, whether it’s for a simple project or enterprise-scale architecture in our Design Patterns section. Choose the model that best fits the stage you plan to reach when you complete the project.

Here's a simple layout, if you just have 3 deployments for things like dev, staging, and prod:

├── components/          # Folder containing all your components, usually organized by toolchain
│   └── terraform/       # Folder for all Terraform "root modules"
└── stacks/
    ├── deploy/          # Folder for deployable stacks
    │   ├── dev/         # Folder for development environment configurations
    │   ├── staging/     # Folder for staging environment configurations
    │   └── prod/        # Folder for production environment configurations
    ├── catalog/         # Folder for the service catalog
    ├── schemas/         # Folder for the schema validations
    └── workflows/       # Folder for workflows that operate on top of stacks

Alternatively, here’s a more complex layout for a larger project broken into multiple organizations, organizational units, and environments:

├── components/                  # Folder containing all your components, usually organized by toolchain
│   └── terraform/               # Folder for all Terraform "root modules"
└── stacks/
    ├── orgs/                    # Folder for deployable stacks
    │   └── acme/                # Folder for the Acme organization
    │       ├── core/            # OU for core services
    │       │   ├── security/    # Folder for security-related configurations
    │       │   ├── audit/       # Folder for audit-related configurations
    │       │   ├── identity/    # Folder for identity management configurations
    │       │   └── network/     # Folder for networking-related configurations
    │       └── plat/            # OU for platform environments
    │           ├── dev/         # Folder for development environment configurations
    │           ├── staging/     # Folder for staging environment configurations
    │           └── prod/        # Folder for production environment configurations
    ├── catalog/                 # Folder for the service catalog
    ├── schemas/                 # Folder for the schema validations
    └── workflows/               # Folder for workflows that operate on top of stacks

Note, that these are just a couple of examples.

components/
folder containing all your components, usually organized by your toolchain
components/terraform
folder for all Terraform "root modules"
stacks/orgs/
folder for deployable stacks
stacks/catalog/
folder for the service catalog
stacks/workflows/
folder for workflows that operate on top of stacks.

You can find some demos of how we organize projects in the Atmos GitHub repository under the examples/ folder. Or check out our Reference Architecture for AWS for a more detailed look at how we organize our projects.

To effectively organize an Atmos project, we want to ensure you have specific locations for Atmos to find your stack configurations and components. At a minimum, we recommend the following folder structure in your project:

Components Folder​

This folder will contain all your components. Organize the components by toolchain. For example, if you have components for Terraform, place them in a Terraform subfolder (e.g. components/terraform/vpc).

Stack Configurations Folder​

Next, you’ll have your stacks configurations, which are organized into multiple subfolders depending on their purpose:

Schema Validations​

This folder contains the JSON or OPA schemas used to validate the stack configurations.

Catalogs​

This should be a separate top-level folder containing your stack configurations. Stack configurations are divided into several parts:

  • Schemas Folder: This folder contains the schemas used to validate the stack configurations.
  • Catalog Folder: This includes all reusable imports, which can be organized into subfolders based on logical groupings.
  • Stacks Folder: This contains the deployable stacks. Each stack is defined in a separate YAML file.

We follow a few conventions in our reference architecture:

Deployments​

We usually organize our stacks by organization, organizational unit, and environment. For example:

  • Orgs Folder: Represents the AWS organizations to which you deploy. You might use a folder called deploy if you have a few simple stacks.
  • Multi-Cloud Projects: If your project involves multiple clouds, consider additional organizational strategies.