# 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](/stacks/name) | Explicit stack name override | Stack manifest only |
| [vars](/stacks/vars) | Variables passed to components | Global, component-type, component |
| [locals](/stacks/locals) | File-scoped temporary variables | Global, component-type, component |
| [env](/stacks/env) | Environment variables | Global, component-type, component |
| [settings](/stacks/settings) | Integrations and metadata | Global, component-type, component |
| [metadata](/stacks/components/component-metadata) | Component behavior and inheritance | Global (restricted subset), component |
| [hooks](/stacks/hooks) | Lifecycle event handlers | Global, component-type, component |
| [command](/stacks/command) | Override default executable | Component-type, component |
| [backend](/stacks/backend) | Terraform state storage | Component-type, component |
| [providers](/stacks/providers) | Terraform provider configuration | Component-type, component |
| [auth](/stacks/auth) | Authentication configuration | Global (atmos.yaml), component |

## Component Types

Each component type has its own configuration options:

| Type | Purpose | Documentation |
|------|---------|---------------|
| [Ansible](/stacks/components/ansible) | Configuration management | Playbook automation |
| [Container](/stacks/components/container) | Container services | Image builds and persistent services |
| [Emulator](/stacks/components/emulator) | Local cloud APIs | Development and testing emulators |
| [Helm](/stacks/components/helm) | Kubernetes deployments | Native Helm chart releases |
| [Helmfile](/stacks/components/helmfile) | Kubernetes deployments | Helmfile release configuration |
| [Kubernetes](/stacks/components/kubernetes) | Kubernetes deployments | Manifest and Kustomize configuration |
| [Packer](/stacks/components/packer) | Machine image building | AMIs, VM images |
| [Terraform](/stacks/components/terraform) | Infrastructure as Code | Cloud resources, networking, IAM |

## Composition and Reuse

Build maintainable configurations using these patterns:

| Pattern | Description |
|---------|-------------|
| [Imports](/stacks/imports) | Include configuration from other files |
| [Catalogs](/howto/catalogs) | Reusable component configurations |
| [Inheritance](/howto/inheritance) | Inherit settings between components |
| [Overrides](/stacks/overrides) | Override inherited configuration |
| [Mixins](/howto/mixins) | Composable configuration snippets |
| [dependencies](/stacks/dependencies) | Define tool and component dependencies |

## Sharing State

Share data between components and stacks:

| Topic | Description |
|-------|-------------|
| [Remote State](/stacks/remote-state) | Access Terraform state from other components |
| [Share Data](/stacks/share-data) | Share configuration between components |

## Describing Stacks

Use [`atmos describe stacks`](/cli/commands/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.

```bash
# 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`.