Use Atmos

Result

A pipeline whose roots are your Atmos component instances, one per stack and component, applied a dependency layer at a time behind the same gate as plain roots.

Prerequisites

You need	Why
An atmos.yaml at the repo root	init detects Atmos from it
Atmos on the path, or TERRAGUCCI_ATMOS naming it	init runs atmos describe stacks
A remote backend for each instance, such as s3	each job starts from a fresh checkout
terragucci installed (Get your first plan note)	init writes the pipeline

Steps

1. Run init.

   npx terragucci init --dry-run

   It prints the instances and how many waves they make:

   found Atmos (atmos.yaml): 4 instances in 2 waves from atmos describe stacks, ...

2. Write the pipeline.

   npx terragucci init

   Commit it and open a pull request.

Instances

What	How
A root	one instance, named <stack>/<component>, such as prod/vpc
Which instances	every Terraform instance atmos describe stacks lists, less abstract ones (metadata.type: abstract) and disabled ones (metadata.enabled: false)
roots and synth	refused: the stacks decide the roots
An instance that sets env or generate	refused; move the setting into the component’s Terraform, or disable the instance

Refused settings

terragucci atmos write makes each instance’s directory as a copy, so config check and init refuse settings that would edit it:

Setting	Instead
drift with the drift pull request, the default respond.drift	respond.drift: attribute or off; a live value belongs in the stack’s vars or the component
rollouts	move the pin in the component, which every instance of it shares
generate	the stack’s backend and providers settings
ephemeral	none

Waves

What	How
Order	dependencies.components, and settings.depends_on; an entry with no stack means the instance’s own stack
A read with !terraform.state or !terraform.output	puts the instance after the one it reads
Each wave	one dependency layer, in its own apply job behind its own gate
A dependency on a disabled instance	holds nothing back
A dependency no stack deploys, or a cycle	init stops and names it
waves.canary	the canary instances’ layers go first

Jobs

Before reading the roots, every job installs Atmos 1.230.1 (checked against the release’s SHA256SUMS) and runs terragucci atmos write. For another release, set it in terragucci.yml and rerun init:

atmos:
  version: 1.230.0

The check job runs atmos validate stacks first, so a manifest Atmos refuses fails the check with Atmos’s own error.

terragucci atmos write
Reads	atmos describe stacks, with !terraform.state, !terraform.output and !store left unevaluated
Writes	the component’s Terraform to <stack>/<component>, with the varfile, backend and provider override Atmos generates for that instance
Local module sources	a ../ source outside the component is rewritten to reach the same directory from the copy
A directory of your repo at <stack>/<component>	refused

These directories are made in the job. If you run terragucci atmos write yourself, add them to .gitignore.

Workspaces

Each instance plans and applies in the Terraform workspace Atmos names for it, never default. With an s3 backend its state is at <workspace_key_prefix>/<workspace>/<key>, as Atmos keeps it.

terragucci plan, unlock-state, state export and a state migration run each instance in its workspace too.

Tips

The tip pull requests pin providers and add lock files in the components, which git holds, and name instances in a canary wave.

Pull requests

A pull request plans the instances whose written files differ from the base’s, and every instance that depends on one of them. The plan job also writes the instances at the base and compares the two without a cloud credential.

A pull request that changes	Plans
prod/vpc’s vars	prod/vpc, then prod/app, which depends on it
a component’s Terraform	every instance of that component, and their dependents
nothing an instance is written from	nothing

Approval

A wave applies the plans whose digest was approved, as plain roots do. If the stacks change after the approval, the wave plans again and applies nothing. It names the instances that moved; approve the new plans to apply them.

Reads of another instance

A var set with !terraform.state or !terraform.output reads another instance’s outputs:

components:
  terraform:
    app:
      vars:
        vpc_cidr: !terraform.state vpc .cidr

atmos describe stacks runs before the job has a cloud credential, so the job reads the value itself afterwards from the state in the upstream’s own workspace. While the upstream has no state, the instance is held back rather than planned on a stand-in; the plan note names the instance it waits for.

Form	Read
!terraform.state <component> <output>	the output of the instance in the same stack
!terraform.state <component> <stack> <output>	the output of the instance in another stack
An output as .name or .name.key	that output, or a key inside it
!terraform.output	the same as !terraform.state
!store, a read inside a map or a list, or a yq expression	refused; output the value from an instance and read it whole

Roles by stack

An instance’s root is <stack>/<component>, so oidc.roles globs give each stack its roles:

oidc:
  roles:
    "dev/*": { plan: arn:aws:iam::111:role/dev-plan, apply: arn:aws:iam::111:role/dev-apply }
    "prod/*": { plan: arn:aws:iam::222:role/prod-plan, apply: arn:aws:iam::222:role/prod-apply }

terragucci config check lists each role with its stack’s instances and their state keys, and warns when an instance reads another stack’s state. A read uses the upstream’s role.

Next

• Approve a waiting wave
• Use Terragrunt, the same model for units