Frequently asked questions
You can use Atmos with your existing Terraform—no rewrite required. Find answers to common questions below.
Getting started
Do I need to rewrite my Terraform?
No. You can use your existing Terraform with Atmos today. An Atmos Terraform component is a Terraform root module—the code you already run with terraform plan and terraform apply.
Point Atmos at your existing root modules, define a stack with their inputs, and run them through Atmos. You can keep your directory layout and include existing .tfvars files. You don’t need Cloud Posse modules, a new architecture, or a rewrite to get started.
For the maximum benefits, we recommend architectural design patterns such as reusable components, configuration inheritance, and independent lifecycles. Adopt these as your needs grow.
How do I get started with an existing project?
Start with one root module and one environment. Add atmos.yaml, point components.terraform.base_path at your Terraform directory, and describe the component and its inputs in a stack. Then run a plan and compare it with your existing workflow.
Choose the migration guide that matches your setup:
- Native Terraform, including existing variable files and scripts
- Terragrunt
- Terraform workspaces
- Terramate
For a new project, start with the Quick Start. You can also adopt Atmos for existing Makefiles, Taskfiles, and Justfiles.
Do I need to move state or recreate my infrastructure?
No. Adopting Atmos does not itself require either. Keep the same Terraform backend, state location, and workspace so Atmos operates on the infrastructure you already manage.
Match the existing backend settings and workspace explicitly; don’t assume Atmos’s generated defaults identify your current state. If your root module already declares its backend, you can disable automatic backend-file generation with components.terraform.auto_generate_backend_file: false in atmos.yaml.
Review a plan before applying. Splitting root modules or changing state locations is a separate architectural change, which you can plan later. See the workspace migration guide and brownfield considerations.
Can my AI coding assistant help me adopt Atmos?
Yes. We provide agent skills that teach compatible coding assistants Atmos conventions and workflows, including migration, stacks, components, and Terraform operations.
Install the migration skill:
atmos ai skill install atmos-migration
Follow the editor and AI assistant setup guide to make skills available in your preferred tool. Pair the skill with the migration guide for your current setup; review the resulting configuration and Terraform plans as you would any infrastructure change.
Using Atmos
How do I run components in dependency order?
Declare component dependencies explicitly. For example, run all Terraform/OpenTofu components in one stack with:
atmos terraform apply --all -s dev
Atmos orders the selected Terraform components using their dependency graph. Output references supply data; declare the ordering relationships separately. To include prerequisites outside the selected stack, use the dependency selection flags.
A plan does not create the outputs needed by a downstream component. For a first deployment, provision prerequisites or use mocks for planning. For operations across different tools, use workflows to coordinate their commands; each component type has its own execution capabilities.
Can I rename stacks and components?
Yes, but check whether the name participates in the identity of the deployed infrastructure. Terraform/OpenTofu need particular care: changing a stack or component name can change the generated backend path or workspace and make existing resources appear unmanaged. Preserve the existing state identity or plan a state migration. See component migrations and workspace configuration.
Other tools have different identities. For example, a CloudFormation component targets a stack_name; preserve that name when reorganizing Atmos configuration for the same deployed stack. Also check resource names and references derived from the renamed values, then review the tool's plan or diff.
How do I remove infrastructure managed by Atmos?
Run the teardown operation for the component type, such as atmos terraform destroy or atmos aws cloudformation delete. Removing a component from YAML alone does not execute teardown.
atmos describe affected reports deleted components and stacks. However, atmos terraform destroy --affected currently selects affected Terraform components that still exist in the current configuration; it filters out deleted components. It is not a deletion-only selector.
Destroy before removing the configuration, or use a reviewed deletion workflow that retrieves the component's configuration and code from the exact earlier revision used for the comparison. Keep that revision available through teardown.
How can I see where a configuration value came from?
Use atmos describe config for the effective CLI configuration and atmos describe component for a component's resolved stack configuration:
atmos describe component vpc -s dev --provenance
Provenance identifies where values originated. Compare the result with --process-templates=false or --process-functions=false to isolate evaluation problems, and use atmos validate stacks to check stack configuration. See the debugging guide for a diagnostic sequence.
How do I select credentials for a component?
Define providers and identities in your authentication configuration. A component can select a default identity through its component-level auth configuration. Use --identity for an explicit selection when running a command, such as atmos terraform plan vpc -s dev --identity dev-reader.
Profiles select a broader set of CLI configuration overrides, such as local versus CI settings. A profile can configure authentication, but it is not itself an identity. Check the selected credentials with atmos auth whoami.
How should I handle secrets?
Configure a supported encrypted store with secret: true, declare the secrets you need, and resolve them with !secret. See secrets configuration for declarations, access controls, and backend setup.
Use ordinary !store for non-sensitive shared configuration. Secret stores require the secret access path and mask values in command output. Terraform's sensitive marker does not by itself define how every downstream tool stores or displays a value; follow the receiving tool's secret-handling guidance too.
Terraform and architecture
Is Atmos a replacement for Terraform?
No. Atmos orchestrates Terraform or OpenTofu: it resolves stack configuration, supplies inputs, and runs the underlying CLI. Your infrastructure remains defined in standard Terraform code.
Atmos also supports Helmfile, Packer, CloudFormation (experimental), and custom commands for other tools and team automation.
Do I have to adopt a specific architecture or use Cloud Posse modules?
No. Your existing root modules can be Atmos components, including a larger root module you haven’t decomposed. The components/terraform directory is a configurable convention, and Cloud Posse’s component library is optional.
You can use your own naming variables with stacks.name_template. Cloud Posse context conventions, mixins, and deeply nested imports are optional; introduce them when they simplify your configuration.
To get more value over time, we recommend separating reusable Terraform code from environment configuration, sharing defaults through imports and inheritance, and giving components independent lifecycles. These design patterns improve reuse and maintainability; they are recommendations, not entry requirements. See Thinking Like Atmos.
Can Atmos download remote modules, or must I vendor them first?
Atmos supports both. Declare a component’s source in stack configuration to provision remote code just in time, with versions selected per environment. You can also use vendoring to pull code ahead of time and optionally commit it for code review, local changes, and offline access.
Source provisioning is currently experimental. Use isolated workdirs for per-stack source versions and refreshes when the URI or version changes or a configured TTL expires. Without workdir provisioning, Atmos normally reuses a non-empty component directory, but an Atmos-owned remote source can refresh when its configured TTL expires. Use atmos terraform source pull <component> -s <stack> --force for an explicit refresh.
Choose source-based versioning when you want remote references in your stacks. Choose explicit vendoring when keeping the component code in your repository is useful. Neither approach requires rewriting the Terraform module.
Can Atmos generate Terraform files?
Yes. Atmos can generate variable files, backend configuration, and files defined in a stack’s generate section, including Terraform HCL, JSON, and supporting configuration.
The general-purpose generate feature is currently experimental. Run atmos terraform generate files, or enable components.terraform.auto_generate_files to generate them before Terraform runs. Generation is available when it fits your workflow; parameterized root modules remain a useful architectural pattern.
Can I still run Terraform without Atmos?
Yes. Components remain standard Terraform root modules. You need to supply the same inputs, backend configuration, workspace, credentials, and any generated files that Atmos normally prepares.
Use atmos terraform shell for a configured shell, or generate variable files and the other required configuration for an independent workflow. Generated files may contain sensitive values; keep them out of version control when they do.
Atmos and Terragrunt
Does Atmos support the capabilities I use in Terragrunt?
Atmos covers the core workflows teams commonly use Terragrunt for. The configuration model and command behavior differ, so migrate the intent of your configuration rather than translating every setting literally.
| Capability | Atmos support |
|---|---|
| Reuse configuration and inputs | Imports, inheritance, and deep merging |
| Fetch remote modules and pin versions | Experimental component sources and vendoring |
| Generate Terraform configuration | Backend generation and the experimental generate section |
| Order operations and share outputs | Component dependencies and !terraform.output |
| Plan before dependencies exist | Mocks and --use-mocks |
| Run commands around Terraform operations | Lifecycle hooks |
| Configure and bootstrap state backends | Centralized backend configuration and experimental backend provisioning for S3 and Azure |
See the Terragrunt migration guide for examples and the behavior of each equivalent. Support for these workflows does not mean every Terragrunt flag or integration has an identical Atmos counterpart.
What are the main differences between Atmos and Terragrunt?
Atmos uses YAML stacks with imports, inheritance, templates, and functions to describe component configuration. Terragrunt uses HCL configuration for units and stacks. Both orchestrate standard Terraform/OpenTofu modules; their orchestration configuration is separate from Terraform’s own language and runtime.
Atmos also brings multi-tool workflows, custom commands, authentication, toolchain management, configuration inspection, and affected-component detection into one CLI. Its design patterns provide guidance for growing your infrastructure without requiring you to adopt them all at once.
Choose based on your team’s configuration preferences and operating needs. The migration guide maps the concepts side by side, and the alternatives page introduces other tools.
Can I adopt Atmos gradually while keeping Terragrunt?
Yes. Keep existing Terragrunt deployments in their current workflow while you introduce Atmos for one component or environment at a time. Custom commands and workflows can provide a common entry point for invoking your existing scripts and tools.
For each migrated component, translate orchestration configuration into Atmos stacks, preserve the backend and workspace that identify its state, and compare plans before switching execution. Give each deployment a clear owner during the transition so the two workflows don’t apply concurrently to the same state. Follow the Terragrunt migration guide.
Integrations
Does Atmos support OpenTofu?
Yes. Set the Terraform component executable to tofu in atmos.yaml:
components:
terraform:
command: tofu
Continue using commands such as atmos terraform plan vpc -s dev; Atmos invokes OpenTofu underneath. See Using OpenTofu for configuration details. Features specific to an engine, such as Terraform Cloud login, still depend on that engine.
Does Atmos work with HCP Terraform and Terraform Enterprise?
Yes. Atmos supports configuration for Terraform’s remote backend and cloud integration, including organization and workspace selection. HCP Terraform was previously called Terraform Cloud. See backend configuration.
HCP Terraform supports saved remote plans with Terraform CLI 1.6 and later. For older or legacy remote execution configurations that don’t support saving a plan, use atmos terraform plan <component> -s <stack> --skip-planfile, or set components.terraform.plan.skip_planfile: true in atmos.yaml. Follow the planfile compatibility guidance for your execution mode.
When Terraform runs in a hosted environment, ensure that environment receives the required module code, inputs, credentials, and generated configuration. Generating a local .tfvars file alone does not configure a hosted workspace or its execution workflow.
How does Atmos fit into CI/CD?
Use the same Atmos commands locally and in CI. The native CI integration supports GitHub Actions workflows with affected-component detection, plans, PR feedback, and deployment orchestration.
Start with the GitHub Actions guides for planning pull requests and applying changes. Other CI systems can invoke the CLI and provide the same configuration, tools, credentials, and state access.
If you use the legacy Atmos Terraform Actions, follow the native CI migration guide. Native CI uses component selection rather than the legacy settings.github.actions_enabled setting. Use GitHub Environments and protection rules to gate production deployments separately from planning.
Does Atmos work with Atlantis?
Yes. Atmos can generate Atlantis repository configuration from your stacks and component settings. Configure Atlantis workflows to run Atmos and provide the required executables and credentials in its runtime.
Does Atmos only work with AWS?
No. Atmos is cloud-agnostic. Terraform and OpenTofu providers determine which infrastructure you can manage, including AWS, Azure, Google Cloud, and services outside those clouds.
Cloud-specific conveniences such as authentication and automatic backend provisioning have their own supported providers. See the multi-cloud overview for details.
About Atmos
Is Atmos free? Do I need a subscription or Atmos Pro?
Atmos CLI is free and open source under Apache 2.0. You don’t need a subscription, hosted service, or daemon to use its core infrastructure and automation workflows.
Atmos Pro is an optional service for visibility and coordination across teams, repositories, and environments. Your cloud resources and any external services you choose to use have their own costs.
Are there examples and reference architectures I can use?
Yes. The Quick Start and example projects provide working configurations you can explore. You can use your own modules or the open-source Cloud Posse component library.
For teams that want a supported AWS reference architecture and implementation help, Cloud Posse offers consulting services. Purchasing a reference architecture is not required to use Atmos.
Who develops Atmos, and how is it funded?
Cloud Posse funds Atmos development, alongside contributions from the community. Cloud Posse’s commercial offerings include infrastructure consulting, AWS reference architectures, and Atmos Pro.
Why is it called Atmos?
The name draws inspiration from the atmospheric terraformers in Aliens. It also expands to Automated Terraform Management & Orchestration Software.
What are some alternatives to Atmos?
See the alternatives overview for related tools and projects that influenced Atmos. If you already use one, the migration guides can help you compare workflows before deciding whether to switch.
