Stack Configuration
Stacks are YAML files that configure your environments. They define which components to deploy, with what settings, and how they relate to each other. This is where configuration lives—separate from your Terraform code.
Configuration Sections
The reference sidebar follows YAML nesting. Literal labels are YAML keys; <name>
represents a user-defined component name. For example, components → terraform →
<name> → mocks corresponds to components.terraform.vpc.mocks for a component
named vpc. Root-level toolchain sections such as terraform configure defaults;
components.terraform.<name> configures an individual component.
A repeated field such as settings applies at the location shown by its parents
in the tree.
Fields that support multiple scopes link to the same reference page from each
supported location. Page scope tables explain restrictions, such as the subset of
metadata fields permitted at the stack root. Colored dots indicate feature status:
yellow for experimental and orange for deprecated; hover or focus a dot for its label.
Stack manifests support various configuration sections at different scopes:
| Section | Description | Scopes |
|---|---|---|
| name | Explicit stack name override | Stack manifest only |
| vars | Variables passed to components | Global, component-type, component |
| locals | File-scoped temporary variables | Global, component-type, component |
| env | Environment variables | Global, component-type, component |
| settings | Integrations and metadata | Global, component-type, component |
| metadata | Component behavior and inheritance | Global (restricted subset), component |
| hooks | Lifecycle event handlers | Global, component-type, component |
| command | Override default executable | Component-type, component |
| backend | Terraform state storage | Component-type, component |
| providers | Terraform provider configuration | Component-type, component |
| auth | Authentication configuration | Global (atmos.yaml), component |
Component Types
Each component type has its own configuration options:
| Type | Purpose | Documentation |
|---|---|---|
| Ansible | Configuration management | Playbook automation |
| Container | Container services | Image builds and persistent services |
| Emulator | Local cloud APIs | Development and testing emulators |
| Helm | Kubernetes deployments | Native Helm chart releases |
| Helmfile | Kubernetes deployments | Helmfile release configuration |
| Kubernetes | Kubernetes deployments | Manifest and Kustomize configuration |
| Packer | Machine image building | AMIs, VM images |
| Terraform | Infrastructure as Code | Cloud resources, networking, IAM |
Composition and Reuse
Build maintainable configurations using these patterns:
| Pattern | Description |
|---|---|
| Imports | Include configuration from other files |
| Catalogs | Reusable component configurations |
| Inheritance | Inherit settings between components |
| Overrides | Override inherited configuration |
| Mixins | Composable configuration snippets |
| dependencies | Define tool and component dependencies |
Sharing State
Share data between components and stacks:
| Topic | Description |
|---|---|
| Remote State | Access Terraform state from other components |
| Share Data | Share configuration between components |
Describing Stacks
Use atmos describe stacks to view the fully computed, deep-merged configuration of any stack. This is invaluable for debugging and understanding what configuration will actually be applied.
# View all stacks
atmos describe stacks
# Filter by specific stack
atmos describe stacks --stack plat-ue2-prod
# Filter by component and section
atmos describe stacks --components vpc --sections vars
# Output as JSON for processing with jq
atmos describe stacks --format json | jq '.["plat-ue2-prod"]'
The output shows the final resolved configuration after all imports, inheritance, and overrides have been applied. Use --sections to filter output to specific sections like vars, env, settings, metadata, backend, or workspace.
7 items
Use the auth section to configure credential management for cloud providers and external services.
8 items
1 item
Use the env section to set environment variables for your Terraform, Helmfile, Packer, or Ansible components.
Use the generate section to create auxiliary configuration files for Terraform components.
10 items
8 items
Run scanners, cost estimators, custom commands, and store outputs at component lifecycle events.
Imports let you split stack configurations across multiple files and reuse them. Each import is deep-merged on top of previous imports, building up the final configuration.
9 items
Use the locals section to define file-scoped temporary variables that reduce repetition and improve readability.
Use the metadata section to control component behavior, inheritance, and deployment settings.
Use the name field to explicitly set a stack's logical name, or use name_template for programmatic naming.
Use the 'Component Overrides' pattern to modify components' configuration and behavior in the current scope.
7 items
Automatically retry transient subprocess errors with configurable backoff and pattern matching.
1 item
13 items
Use the vars section to pass variables to your Terraform, Helmfile, Packer, or Ansible components.
