Atmos Quick Start (Advanced)

Atmos is a universal tool for DevOps and cloud automation. This advanced example provisions a small AWS application stack — entirely offline — against a local AWS emulator (Floci), so you can learn the patterns end to end without a real AWS account or any credentials.

Follow the Quick Start: Advanced guide for a step-by-step walkthrough of this repository.

It's just plain Terraform

The components in components/terraform/ are vanilla Terraform — raw aws_* resources using only the official hashicorp/aws provider. There are no Cloud Posse modules and no special wrappers. Atmos is a bring-your-own-Terraform orchestrator: it never requires you to rewrite your Terraform or adopt proprietary components. Each component carries only a stock providers.tf (provider "aws" { region = var.region }) with no endpoint or credentials configuration — the local-aws identity (kind: aws/emulator) generates a providers_override.tf.json that points the provider at the emulator at runtime, so the exact same code deploys unchanged against real AWS.

Component	What it is (plain Terraform)
`kms-key`	`aws_kms_key` + alias
`s3-bucket`	`aws_s3_bucket` (+ versioning, SSE)
`dynamodb-table`	`aws_dynamodb_table`
`sns-topic`	`aws_sns_topic`
`sqs-queue`	`aws_sqs_queue` (+ policy)
`app-config`	publishes resolved config + secrets to SSM Parameter Store

The components are wired together with Atmos features — not Terraform remote_state data sources: stack templates build predictable coordinates, dependency metadata controls graph order, store hooks publish applied outputs, and !secret resolves declared secrets from the SSM/Secrets Manager stores.

Run it end to end

Everything runs against the local emulator. You need Atmos and a container runtime (Docker or Podman).

The test custom command brings up the emulator, seeds secrets, applies the full component DAG in dependency order, confirms the cross-component wiring resolves, then tears everything down:

atmos test -s plat-ue2-dev

Or run the same steps by hand:

# Start the local AWS emulator for the stack.
atmos emulator up aws -s plat-ue2-dev

# Lint every stack manifest.
atmos validate stacks

# Seed the required app-config secrets.
atmos secret set API_KEY=sk-quickstart-example -s plat-ue2-dev -c app-config
atmos secret set 'DB_CONFIG={"username":"app","password":"s3cr3t"}' -s plat-ue2-dev -c app-config

# Apply every component in dependency order (the S3 state backend is auto-provisioned
# inside the emulator via `provision.backend.enabled`).
atmos terraform deploy --all -s plat-ue2-dev

# Inspect a component and see where every value came from.
atmos describe component app-config -s plat-ue2-dev --provenance
atmos list instances --format tree --provenance

# Tear down.
atmos terraform destroy --all -s plat-ue2-dev -auto-approve
atmos emulator down aws -s plat-ue2-dev

Available stacks: plat-ue2-{dev,staging,prod} (us-east-2) and plat-uw2-{dev,staging,prod} (us-west-2).

How the environments differ

The three environments deploy the same services with different settings - that's the whole point of the layered configuration. The catalog defines each component's defaults once; each region manifest sets the stage-specific values directly. Open stacks/orgs/acme/plat/prod/us-east-2.yaml and you can see exactly what makes that prod region different.

Setting	`dev` (ephemeral)	`staging` (middle)	`prod` (hardened)
`s3-bucket` `force_destroy`	`true`	`true`	`false`
`s3-bucket` `versioning_enabled`	`false`	`true`	`true`
`kms-key` `deletion_window_in_days`	`7`	`14`	`30`
`kms-key` `enable_key_rotation`	`false`	`true`	`true`
`sqs-queue` `message_retention_seconds`	`86400` (1d)	`345600` (4d)	`1209600` (14d)

See it resolved per stage (no deploy required):

atmos describe component s3-bucket -s plat-ue2-dev
atmos describe component s3-bucket -s plat-ue2-prod

Tags and labels

Every component in the catalog carries metadata.tags (a list, matched with any) and metadata.labels (a map, matched with all) — see the Component Metadata reference. Use them to select components across the whole stack without listing names:

# Everything tagged "messaging" (sns-topic, sqs-queue) — regardless of stack.
atmos list components --tags messaging

# Everything labeled tier=foundational (kms-key, s3-bucket) — the components
# everything else in this stack depends on.
atmos list components --labels tier=foundational

# Plan (or deploy/destroy) only the messaging components for a stack.
atmos terraform plan --all --tags messaging -s plat-ue2-dev

# Plan only the foundational tier — composes with --all the same way --affected does.
atmos terraform plan --all --labels tier=foundational -s plat-ue2-dev

Operator commands

This example also registers operator-focused custom commands in atmos.yaml:

atmos operator status -s <stack>                  # show stack tree, instances, catalog, and next commands
atmos operator inspect <component> -s <stack>     # describe component config with provenance