Advanced

Advanced Tutorial

In about 30 minutes, you'll deploy a real event-driven application backend — a KMS key, an encrypted S3 bucket, a DynamoDB table, an SNS topic, an SQS queue, and an SSM Parameter Store config — and you'll do it entirely on your laptop, with no AWS account and no credentials. Along the way you'll learn the Atmos patterns you'll reach for every day.

New to Atmos? Start with the Simple Quick Start first — this tutorial assumes you've seen the basics.

What you'll build

A small but realistic backend, provisioned with plain Terraform and orchestrated by Atmos:

• kms-key — encryption key the other resources use
• s3-bucket — versioned, KMS-encrypted bucket
• dynamodb-table — a simple table
• sns-topic + sqs-queue — the queue subscribes to the topic
• app-config — publishes the stack's resolved coordinates and two secrets to SSM Parameter Store

The components depend on each other, so Atmos deploys them in dependency order. Everything runs against a local sandbox (a containerized cloud-API emulator) that Atmos starts for you — including the S3 state backend, which Atmos provisions inside the sandbox automatically.

You will learn

• How Atmos installs the exact tools your stacks need (OpenTofu, security scanners) so everyone runs the same versions
• How to start a local sandbox and bind your components to it with an identity — no providers.tf, no endpoints
• How to compose configuration with catalogs, mixins, and a stack hierarchy instead of copy-paste
• How components share data with stack templates, dependency metadata, output-publishing hooks, and stores
• How to run hooks — security scans, cost estimates, output publishing — automatically on plan and apply
• How to manage secrets so they're delivered to Terraform in memory and never written to disk
• How to validate stacks and then deploy everything in dependency order with one command

It's just plain Terraform — bring your own

Every component here is vanilla Terraform: raw aws_* resources on the official hashicorp/aws provider, with no Cloud Posse modules and no wrappers. The components carry no providers.tf and no backend block — Atmos generates the provider and backend configuration at apply time and points them at the sandbox. You write the resources; Atmos wires the plumbing. Switch the stack and the same components deploy to real AWS.

Prerequisites

The only thing you need installed is a container runtime — Docker or Podman. Atmos installs OpenTofu and everything else through its toolchain. You do not need an AWS account, AWS credentials, or any cloud access.

You can follow along in your own repo, or clone the finished example to read ahead:

git clone https://github.com/cloudposse/atmos.git
cd atmos/examples/quick-start-advanced

The steps

1. Configure the Project — lay out the repo and a single atmos.yaml
2. Install the Toolchain — pin OpenTofu and let Atmos install it for you
3. Start the Local Sandbox — spin up the emulator your stacks deploy against
4. Create Stacks — compose components with catalogs, mixins, and a hierarchy
5. Configure Hooks — scan on every plan and publish outputs on every apply
6. Manage Secrets — keep secrets off disk with stores and !secret
7. Validate Configurations — lint stacks and enforce policy
8. Deploy Everything — bring the whole backend up in dependency order

Then, when you're ready for more, three optional chapters — automating workflows, adding custom commands, and vendoring components — plus a Terraform state backend deep-dive.

Ready? Configure the Project →

Configure the Project

Lay out an Atmos monorepo and create a single atmos.yaml at the repo root that tells Atmos where your components and stacks live.

Install the Toolchain

Let Atmos install and pin the exact tools your stacks need — OpenTofu and a security scanner — so everyone runs the same versions with no separate tool manager.

Start the Local Sandbox

This tutorial provisions real Terraform resources — a KMS key, an S3 bucket, a DynamoDB table, an SNS topic, an SQS queue, and SSM parameters —

Advanced Tutorial

In about 30 minutes, deploy a real event-driven AWS backend entirely on your laptop — no cloud account, no credentials — and learn the Atmos patterns that matter most.

Create Stacks

In the previous steps, we configured the Terraform components and started the local sandbox.

Configure Hooks

Run automated actions at component lifecycle events — security scans after a plan, output publishing after an apply — with Atmos hooks.

Manage Secrets

The app-config component needs two secrets: a third-party APIKEY and a structured DBCONFIG (JSON) containing database credentials. Atmos manages

Validate Configurations

Lint every stack against the built-in manifest schema, then enforce your own rules on component configuration with JSON Schema and OPA policies.

Deploy Everything

Having configured the Terraform components, the Atmos components catalog, all the mixins and defaults, and the Atmos top-level stacks, we can now

Automate Common Workflows

You've already deployed the full backend. This chapter and the ones that follow are optional — reach for them when you want to package the commands your operators run every day.

Add Custom Commands

This is an advanced extension point, not a required step — most people add custom commands only after running Atmos for a while and noticing a command they wish existed.

Optional: Vendor Components

This step is not required for the tutorial. The six components in this example live in the repo under components/terraform/, so there's nothing to

Terraform State Backend

This example stores Terraform state in an S3 backend — the same backend you'd use in production —

Final Notes

Atmos provides unlimited flexibility in defining and configuring stacks and components in the stacks.

Next Steps

You have just learned the essentials of Atmos.