Skip to main content

Configuration Overview

Atmos uses multiple types of configuration files, each serving a distinct purpose. Understanding these configuration types is essential for effectively managing your infrastructure.

Configuration Types​

Atmos organizes configuration into four main categories:

Configuration TypeFile(s)Purpose
CLI Configurationatmos.yamlConfigure the Atmos CLI behavior, paths, and integrations
Stack Configurationstacks/**/*.yamlDefine environments and component configurations
Component Configurationcomponents/Infrastructure code (Terraform, Helmfile, Packer)
Vendor Configurationvendor.yamlDefine external dependencies to vendor

CLI Configuration​

The atmos.yaml file configures the Atmos CLI itself. It tells Atmos where to find your stacks and components, how to behave, and what integrations to enable.

Key settings include:

  • Base paths for components, stacks, and workflows
  • Terraform/Helmfile command configuration
  • Stack naming patterns
  • Template and schema settings
  • Integrations (Atlantis, Spacelift, GitHub Actions)
# atmos.yaml
base_path: "."

components:
  terraform:
    base_path: components/terraform

stacks:
  base_path: stacks
  included_paths:
    - "orgs/**/*"
  name_pattern: "{tenant}-{environment}-{stage}"

Learn more about CLI Configuration →

Stack Configuration​

Stack configuration files define your environments and how components are configured within them. Stacks are YAML files that specify which components to deploy and with what settings.

Key features:

  • Component definitions with variables and metadata
  • Imports for configuration reuse
  • Inheritance between configurations
  • Environment-specific overrides
# stacks/prod/us-east-1.yaml
import:
  - catalog/vpc/defaults

components:
  terraform:
    vpc:
      vars:
        environment: ue1
        stage: prod
        cidr_block: "10.0.0.0/16"

Learn more about Stack Configuration →

Component Configuration​

Components are the infrastructure-as-code implementations that Atmos orchestrates. Each component type has its own configuration within stacks:

Terraform Components​

Terraform root modules in components/terraform/. Stack configuration tells Atmos which module to use and what variables to pass.

components:
  terraform:
    vpc:
      metadata:
        component: vpc  # Points to components/terraform/vpc/
      vars:
        cidr_block: "10.0.0.0/16"

Terraform Stack Configuration →

Helmfile Components​

Helmfile configurations in components/helmfile/. Used for deploying Helm charts to Kubernetes.

components:
  helmfile:
    nginx-ingress:
      vars:
        namespace: ingress
        chart_version: "4.0.0"

Helmfile Configuration →

Packer Components​

Packer templates in components/packer/. Used for building machine images.

components:
  packer:
    ubuntu-base:
      vars:
        ami_name: "ubuntu-base"
        instance_type: "t3.medium"

Packer Configuration →

Vendor Configuration​

Vendor manifests define external dependencies that Atmos should download and manage. This enables you to use third-party components, modules, and configurations without copying them into your repository.

# vendor.yaml
apiVersion: atmos/v1
kind: AtmosVendorConfig
metadata:
  name: my-vendor-config
spec:
  sources:
    - component: vpc
      source: github.com/cloudposse/terraform-aws-components.git//modules/vpc
      version: 1.300.0

Learn more about Vendoring →

Configuration Hierarchy​

These configuration types work together in a hierarchy:

  1. CLI Configuration (atmos.yaml) defines where to find everything
  2. Vendor Configuration (vendor.yaml) pulls in external dependencies
  3. Component Configuration (components/) provides the infrastructure code
  4. Stack Configuration (stacks/) assembles components into deployable environments
atmos.yaml                    # CLI: Where to find things
├── vendor.yaml               # Vendor: External dependencies
├── components/               # Components: Infrastructure code
│   ├── terraform/
│   ├── helmfile/
│   └── packer/
└── stacks/                   # Stacks: Environment definitions
    ├── catalog/              # Reusable configurations
    └── orgs/                 # Environment-specific stacks

Next Steps​