Skip to main content

​
What is Atmos?

Atmos is a command-line tool that wraps Terraform (or OpenTofu) and adds a configuration layer that separates what to deploy (components) from where to deploy it (stacks).

​
Key Atmos Concepts

​
Components

A component is a reusable Terraform module. This bundle includes components for:
  • S3 buckets
  • DynamoDB tables
  • SQS queues
  • IAM roles
  • Karpenter node pools
Components live in atmos/components/terraform/ and contain standard Terraform code.

​
Stacks

A stack is a configuration file that defines which components to deploy and with what settings. Stacks live in atmos/stacks/ and are written in YAML: 
# Example: atmos/stacks/valinor/opennext.yaml
components:
  terraform:
    s3-bucket/opennext:
      vars:
        name: opennext-cache
        versioning_enabled: false

​
How Context Uses Atmos

This infrastructure bundle uses Atmos to:
  1. Simplify onboarding — The atmos bootstrap command handles configuration, state backend creation, and deployment in a guided flow
  2. Manage configuration — Your settings (namespace, region, cluster name) are stored in one file (atmos/stacks/valinor/_config.yaml) and automatically applied to all components
  3. Enable customization — You can override any default by editing stack files, without modifying Terraform code

​
Common Commands

CommandDescription
atmos bootstrapGuided setup wizard
atmos bootstrap configureConfigure your environment
atmos bootstrap terraformDeploy all infrastructure
atmos bootstrap terraform --planPreview changes before deploying
atmos terraform plan <component> -s <stack>Plan a single component
atmos terraform apply <component> -s <stack>Apply a single component
atmos describe component <component> -s <stack>View resolved configuration

​
Example: Deploying a Single Component

To deploy just the S3 bucket: 
# Preview changes
atmos terraform plan s3-bucket/opennext -s acme-usw2

# Apply changes
atmos terraform apply s3-bucket/opennext -s acme-usw2
Replace acme-usw2 with your stack name (the combination of your namespace and environment).

​
Example: Viewing Configuration

To see the fully resolved configuration for a component: 
atmos describe component s3-bucket/opennext -s acme-usw2
This shows all variables, including defaults and overrides, that will be passed to Terraform.

​
Configuration Files

FilePurpose
atmos.yamlCLI configuration (paths, settings)
atmos/stacks/valinor/_config.yamlYour environment settings — edit this
atmos/stacks/valinor/_defaults.yamlShared defaults for all components
atmos/stacks/valinor/opennext.yamlOpenNext component configurations
atmos/components/terraform/Terraform module source code

​
Terraform State

Atmos manages Terraform state using an S3 backend. The atmos bootstrap configure command creates an S3 bucket to store state. State is isolated per component, so deployments don’t interfere with each other.

​
Learn More