# Atmos FAQ

# Frequently asked questions

You can use Atmos with your existing Terraform—no rewrite required. Find answers to common questions below.

[Migration guides ↗](/migration/native-terraform)
[Agent skills ↗](/ai/skills)

[Getting started](#getting-started)
[Using Atmos](#using-atmos)
[Terraform & architecture](#terraform-and-architecture)
[Atmos & Terragrunt](#atmos-vs-terragrunt)
[Integrations](#integrations)
[About Atmos](#general)

## 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](/migration/native-terraform). 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](/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](/migration/native-terraform), including existing variable files and scripts
- [Terragrunt](/migration/terragrunt)
- [Terraform workspaces](/migration/terraform-workspaces)
- [Terramate](/migration/terramate)

For a new project, start with the [Quick Start](/quick-start/). You can also adopt Atmos for existing [Makefiles](/migration/makefile), [Taskfiles](/migration/taskfile), and [Justfiles](/migration/justfile).

### 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](/migration/terraform-workspaces) and [brownfield considerations](/components/terraform/brownfield).

### Can my AI coding assistant help me adopt Atmos?

Yes. We provide [agent skills](/ai/skills) that teach compatible coding assistants Atmos conventions and workflows, including migration, stacks, components, and Terraform operations.

Install the migration skill:

```shell
atmos ai skill install atmos-migration
```

Follow the [editor and AI assistant setup guide](/projects/setup-editor/ai-assistants) 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 should components share data and outputs?

Choose the method for the data you need. For deployed Terraform/OpenTofu outputs, use [`!terraform.state`](/functions/yaml/terraform.state) with a supported backend, or [`!terraform.output`](/functions/yaml/terraform.output) when you need the underlying CLI's output handling. For deployed CloudFormation Outputs, use [`!aws.cloudformation.output`](/functions/yaml/aws.cloudformation.output).

**Terraform CLI lookups can make large configurations very slow.** `!terraform.output` and [`atmos.Component`](/functions/template/atmos.Component) for Terraform targets prepare the component, initialize it when needed, select the workspace, and run `terraform output`. `atmos.Component` eagerly loads outputs even if you only read `.vars` or `.settings`. Output caching helps within one command, but does not persist across commands; prefer direct state reads for outputs and imports or inheritance for shared configuration.

`atmos.Component` also supports component configuration and outputs for other supported types, including CloudFormation. [External stores](/stacks/sharing-state/stores) let different tools publish and consume persisted values; [named workflow outputs](/steps/outputs) pass results between steps within a run. A workflow result is not automatically persisted for a later deployment. See [sharing data between components](/stacks/sharing-state) to compare the options.

### How do I run components in dependency order?

Declare [component dependencies](/stacks/dependencies/components) explicitly. For example, run all Terraform/OpenTofu components in one stack with:

```shell
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](/cli/commands/terraform/usage#flags).

A plan does not create the outputs needed by a downstream component. For a first deployment, provision prerequisites or use [mocks for planning](/migration/terragrunt#mock_outputs--component-mocks). For operations across different tools, use [workflows](/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](/tutorials/atmos-component-migrations-in-yaml) and [workspace configuration](/components/terraform/workspaces).

Other tools have different identities. For example, a CloudFormation component targets a [`stack_name`](/stacks/components/aws-cloudformation); 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`](/cli/commands/terraform/destroy) or [`atmos aws cloudformation delete`](/cli/commands/aws/cloudformation/delete). Removing a component from YAML alone does not execute teardown.

[`atmos describe affected`](/cli/commands/describe/affected#detecting-deleted-components-in-affected-stacks) 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`](/cli/commands/describe/config) for the effective CLI configuration and [`atmos describe component`](/cli/commands/describe/component) for a component's resolved stack configuration:

```shell
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](/troubleshoot/debugging) for a diagnostic sequence.

### How do I select credentials for a component?

Define providers and identities in your [authentication configuration](/cli/configuration/auth). A component can select a default identity through its [component-level auth configuration](/stacks/auth#component-level-identity-selection). Use `--identity` for an explicit selection when running a command, such as `atmos terraform plan vpc -s dev --identity dev-reader`.

[Profiles](/cli/configuration/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`](/cli/commands/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`](/functions/yaml/secret). See [secrets configuration](/cli/configuration/secrets) 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](/components/helmfile), [Packer](/components/packer), [CloudFormation](/components/cloudformation) (experimental), and [custom commands](/cli/configuration/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`](/cli/configuration/stacks#stack-naming-with-name_template-recommended). 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](/design-patterns) improve reuse and maintainability; they are recommendations, not entry requirements. See [Thinking Like Atmos](/learn/mindset).

### Can Atmos download remote modules, or must I vendor them first?

Atmos supports both. Declare a component’s [`source`](/cli/commands/terraform/source) in stack configuration to provision remote code just in time, with versions selected per environment. You can also use [vendoring](/vendor/) 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](/stacks/components/provision/workdir) 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](/design-patterns/version-management/source-based-versioning) when you want remote references in your stacks. Choose [explicit vendoring](/design-patterns/version-management/vendoring-components) 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](/cli/commands/terraform/generate/varfiles), [backend configuration](/cli/commands/terraform/generate/backends), and files defined in a stack’s [`generate` section](/stacks/generate), 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`](/cli/commands/terraform/shell) for a configured shell, or [generate variable files](/cli/commands/terraform/generate/varfiles) 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](/stacks/imports), inheritance, and deep merging |
| Fetch remote modules and pin versions | Experimental component [sources](/cli/commands/terraform/source) and [vendoring](/vendor/) |
| Generate Terraform configuration | Backend generation and the experimental [`generate` section](/stacks/generate) |
| Order operations and share outputs | [Component dependencies](/stacks/dependencies/components) and [`!terraform.output`](/functions/yaml/terraform.output) |
| Plan before dependencies exist | [Mocks and `--use-mocks`](/migration/terragrunt#mock_outputs--component-mocks) |
| Run commands around Terraform operations | Lifecycle [hooks](/stacks/hooks) |
| Configure and bootstrap state backends | Centralized [backend configuration](/stacks/backend) and experimental [backend provisioning](/stacks/components/provision/backend) for S3 and Azure |

See the [Terragrunt migration guide](/migration/terragrunt) 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](/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](/migration/terragrunt) maps the concepts side by side, and the [alternatives page](/reference/alternatives) 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](/cli/configuration/commands) and [workflows](/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](/migration/terragrunt).

## Integrations

### Does Atmos support OpenTofu?

Yes. Set the Terraform component executable to `tofu` in `atmos.yaml`:

```yaml
components:
  terraform:
    command: tofu
```

Continue using commands such as `atmos terraform plan vpc -s dev`; Atmos invokes OpenTofu underneath. See [Using OpenTofu](/cli/configuration/components/terraform#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](/stacks/backend#terraform-cloud--enterprise).

HCP Terraform supports [saved remote plans with Terraform CLI 1.6 and later](https://developer.hashicorp.com/terraform/cloud-docs/workspaces/run/cli#saved-plans). 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](/components/terraform/planfiles#terraform-cloud-integration) 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](/ci) supports GitHub Actions workflows with affected-component detection, plans, PR feedback, and deployment orchestration.

Start with the [GitHub Actions guides](/integrations/github-actions) 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](/ci/migrate-legacy-actions). Native CI uses [component selection](/ci#choosing-which-components-run-in-ci) rather than the legacy `settings.github.actions_enabled` setting. Use [GitHub Environments and protection rules](/ci#gating-production-with-environments) to gate production deployments separately from planning.

### Does Atmos work with Atlantis?

Yes. Atmos can [generate Atlantis repository configuration](/cli/configuration/integrations/atlantis) 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](/multi-cloud) 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](/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](/quick-start/) and [example projects](https://github.com/cloudposse/atmos/tree/main/examples) provide working configurations you can explore. You can use your own modules or the open-source [Cloud Posse component library](https://github.com/cloudposse-terraform-components).

For teams that want a supported AWS reference architecture and implementation help, [Cloud Posse offers consulting services](https://cloudposse.com/consulting). Purchasing a reference architecture is not required to use Atmos.

### Who develops Atmos, and how is it funded?

[Cloud Posse](https://cloudposse.com/) funds Atmos development, alongside contributions from the community. Cloud Posse’s commercial offerings include infrastructure consulting, AWS reference architectures, and [Atmos Pro](/pro).

### Why is it called Atmos?

The name draws inspiration from the [atmospheric terraformers in Aliens](https://avp.fandom.com/wiki/Atmosphere_Processing_Plant). It also expands to **Automated Terraform Management & Orchestration Software**.

### What are some alternatives to Atmos?

See the [alternatives overview](/reference/alternatives) 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.