Create and Operate Mixed-Component Stacks
A stack can contain Terraform infrastructure, Helm releases, and Kubernetes resources that depend on each other. Running each component type separately leaves you to coordinate their order. The new stack deploy and stack destroy commands follow those dependencies across types, while stack create generates new stack definitions from reusable scaffolds.
The Problem
Component types do not determine execution order. A Helm release might need an output from Terraform, while another Terraform component might depend on a Kubernetes resource. Creating another environment also means reproducing its manifests, imports, and component declarations consistently.
The Fix
Stack deployment follows declared component dependencies across types and stacks. Independent components can run concurrently when requested; destruction follows the reverse order. Only component types with a handler for the requested operation participate, including configured custom commands. Each component command retains its authentication, hooks, and confirmation behavior.
The stack plan command previews infrastructure changes before deployment. It runs Terraform plans, Helmfile diffs, and the native plan commands for Helm, Kubernetes, and CloudFormation. Types without a planning operation are excluded. Add --dry-run to inspect the commands without executing their plans or hooks.
The stack test command uses the same component selectors and ordering to run registered tests. Terraform components run atmos terraform test, including their test hooks; custom component kinds can provide their own test operation.
Stack creation reuses the existing scaffold catalog and renderer. The built-in template can add imports and disabled component stubs; a configured template can generate a complete application stack and supporting files. Creation validates the output plan and refuses to overwrite existing files.
How to Use It
Inspect stacks from the same command group: stack list, stack describe, and stack instances reuse the existing list and describe commands, including their filters and output formats.
Preview a new stack with component stubs:
atmos stack create --file stacks/deploy/dev.yaml --name dev \
--component terraform:network --component helm:app --dry-run
Remove --dry-run to create the files, then configure and enable the generated stubs before deployment. Select a team recipe with --template application-stack, where application-stack is defined in scaffold.templates in atmos.yaml; the recipe declares its primary stack output using spec.stack.manifest.
For a recipe that splits stacks across several files, use a directory destination:
atmos stack create --template application-stack --target stacks/deploy/dev \
--set environment=dev --set name=dev \
--component terraform:network --component helmfile:services --dry-run
Directory recipes own the layout and can create one decomposed stack or several distinct
stacks. They do not require a primary manifest. In an interactive terminal, creation asks
for a missing destination and runs the scaffold questionnaire, including during dry runs.
Use --defaults for automation and supply required answers with --set.
Preview affected components, their commands, dependencies, and declared lifecycle hooks:
atmos stack deploy --affected --stack dev --dry-run
Deploy a whole stack, select several components, or open the component picker:
atmos stack deploy --stack dev --dry-run
atmos stack deploy --component=app,api --component=worker --stack dev --dry-run
atmos stack deploy --component --stack dev --dry-run
Component names match across types. Repeat --component, separate names with commas,
or use the bare flag for an interactive multiselect. Without --stack, --all, or
--affected, Atmos prompts for a stack. Use --all to operate across stacks, or
--affected for affected components. Automation must supply values for any requested
prompts explicitly.
Plan proposed changes, then run Terraform tests for selected components:
atmos stack plan --stack dev --component=network,app
atmos stack test --stack dev --component=network,app
Deploy with bounded concurrency, or preview destruction of currently defined components:
atmos stack deploy --all --stack dev --max-concurrency 4
atmos stack destroy --all --stack dev --dry-run
Dependency expansion is opt-in through --include-dependencies[=N] or --include-dependents[=N]. Dry runs display hook declarations and conditions without running them; conditional hooks are evaluated during execution.
Deleted definitions are reported separately. Recovery for deleted-component teardown is still pending: stack deploy --affected --allow-destroy fails before any operations start when the selection contains deletions. The existing flat stack get, set, delete, and format aliases are deprecated and hidden; use stack config instead. In particular, stack delete retains its configuration-editing behavior and does not remove a manifest.
Before You Upgrade
Built-in commands take precedence over custom commands of the same name. If your atmos.yaml defines a custom stack command with a plan, test, deploy, destroy, or create subcommand, the built-in now runs in its place and your steps are ignored, with a warning. This changes what those commands do: atmos stack deploy applies every selected component with auto-approve, and atmos stack destroy destroys them. Rename any custom commands that use these names before upgrading.
Get Involved
Try the mixed-component stack example, including its application-stack scaffold and image-build hook, and share feedback through GitHub Discussions.
