feat(emulator): local cloud emulators + emulator-based advanced quick-start & docs example drawer by osterman · Pull Request #2647 · cloudposse/atmos

Erik Osterman (Cloud Posse) (osterman) · 2026-06-21T14:57:29Z

what

Emulator feature — run cloud-service emulators locally as first-class Atmos components:

emulator component kind + driver registry (pkg/emulator): the EmulatorDriver interface, ResolveDriver/Drivers, Endpoint/Profile types, the built-in AWS Floci driver, and the AWS target-profile builder (dummy creds, AWS_ENDPOINT_URL, and the Terraform provider behavior flags env can't set).
atmos emulator CLI (cmd/emulator): lifecycle verbs (up/down/reset/list/…), flags, and shell completions.
Auth/identity binding so in-process AWS and Terraform both reach the emulator (pkg/auth, pkg/component, internal/exec); generic provider-config contribution (pkg/generator).
Design captured as three PRDs: docs/prd/emulators.md, docs/prd/kubernetes-identity.md, docs/prd/provider-config-contributor.md.
Examples + E2E: examples/emulator-aws, examples/demo-floci, and the floci/acceptance jobs.
Changelog: website/blog/2026-06-22-emulator-persistence.mdx.

Emulator-based advanced quick-start — rewrote the advanced tutorial to deploy a real event-driven AWS backend (KMS key, encrypted S3 bucket, DynamoDB table, SNS topic, SQS queue, SSM Parameter Store config) entirely on your laptop, with no AWS account and no credentials, via the emulator. New backing example examples/quick-start-advanced (replaces the old VPC-based one).

Docs UI — a right-side [Example] drawer that follows each quickstart page and shows the page's backing example files (QuickStartExampleDrawer, wired through theme/DocItem/Content + theme/Root, reading the file-browser plugin's global data). Plus restyled File, Terminal, KeyPoints ("You will learn"), KeyTakeaways, EmbedExample, and ActionCard components, a CodeBlock line-numbers toggle, and supporting theme/CSS overrides.

why

Emulators let contributors and CI run the full Atmos workflow — auth, secrets, vendoring, toolchain, Terraform apply — against local cloud emulators, the same on a laptop and in CI, with no cloud credentials. That makes the advanced tutorial runnable by anyone and gives fast, hermetic local iteration.
The example drawer and component restyle let each tutorial page show its backing example inline, so readers can follow the docs and the code side by side.

references

Stacked on osterman/container-component-type (reuses its persistent container lifecycle via ComponentType: "emulator").
See docs/prd/emulators.md for the full design and per-step implementation sequence.

atmos-pro · 2026-06-21T14:57:32Z

Tip

Atmos Pro

No affected stacks workflow was detected for this pull request.
If this is expected, no action is needed.
Learn More. Ask AI.

github-actions · 2026-06-21T14:58:11Z

Dependency Review

✅ No vulnerabilities or license issues found.

Scanned Files

None

codecov · 2026-06-21T20:24:05Z

Codecov Report

❌ Patch coverage is 81.91781% with 330 lines in your changes missing coverage. Please review.
✅ Project coverage is 80.45%. Comparing base (3e80b05) to head (6523621).

Files with missing lines	Patch %	Lines
pkg/emulator/manager.go	73.04%	45 Missing and 24 partials ⚠️
pkg/emulator/vault.go	59.66%	28 Missing and 20 partials ⚠️
pkg/component/emulator/executor.go	80.64%	23 Missing and 7 partials ⚠️
cmd/emulator/completions.go	68.23%	19 Missing and 8 partials ⚠️
pkg/component/emulator/emulator.go	79.72%	12 Missing and 3 partials ⚠️
pkg/auth/identities/emulator/identity.go	86.27%	7 Missing and 7 partials ⚠️
pkg/emulator/mounts.go	74.46%	10 Missing and 2 partials ⚠️
pkg/emulator/spec.go	92.68%	6 Missing and 6 partials ⚠️
pkg/container/docker.go	76.74%	5 Missing and 5 partials ⚠️
pkg/emulator/yamlfunc.go	84.12%	5 Missing and 5 partials ⚠️
... and 20 more

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2647      +/-   ##
==========================================
+ Coverage   80.42%   80.45%   +0.02%     
==========================================
  Files        1402     1444      +42     
  Lines      133010   134759    +1749     
==========================================
+ Hits       106973   108415    +1442     
- Misses      20138    20337     +199     
- Partials     5899     6007     +108

Flag	Coverage Δ
unittests	`80.45% <81.91%> (+0.02%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
cmd/describe_component.go	`74.80% <100.00%> (ø)`
cmd/emulator/flags.go	`100.00% <100.00%> (ø)`
cmd/identity_helpers.go	`89.47% <100.00%> (ø)`
cmd/root.go	`71.37% <ø> (ø)`
errors/errors.go	`100.00% <ø> (ø)`
internal/exec/describe_component.go	`79.09% <100.00%> (+0.06%)`	⬆️
internal/exec/describe_stacks.go	`98.29% <100.00%> (+0.02%)`	⬆️
...ternal/exec/describe_stacks_component_processor.go	`95.90% <100.00%> (+0.01%)`	⬆️
internal/exec/utils_auth.go	`96.34% <100.00%> (ø)`
pkg/auth/emulator.go	`100.00% <100.00%> (ø)`
... and 59 more

... and 7 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

mergify · 2026-06-22T20:12:07Z

Warning

This PR exceeds the recommended limit of 10,000 lines.

Large PRs are difficult to review and may be rejected due to their size.

Please verify that this PR does not address multiple issues.
Consider refactoring it into smaller, more focused PRs to facilitate a smoother review process.

mergify · 2026-06-22T20:12:07Z

Important

Cloud Posse Engineering Team Review Required

This pull request modifies files that require Cloud Posse's review. Please be patient, and a core maintainer will review your changes.

To expedite this process, reach out to us on Slack in the #pr-reviews channel.

mergify · 2026-06-22T20:14:06Z

💥 This pull request now has conflicts. Could you fix it Erik Osterman (Cloud Posse) (@osterman)? 🙏

Erik Osterman (Cloud Posse) (osterman) · 2026-06-23T02:59:12Z

CodeRabbit (@coderabbitai) full review

coderabbitai · 2026-06-23T02:59:18Z

✅ Action performed

Full review finished.

mergify · 2026-06-23T14:46:40Z

💥 This pull request now has conflicts. Could you fix it Erik Osterman (Cloud Posse) (@osterman)? 🙏

mergify · 2026-06-25T10:42:53Z

💥 This pull request now has conflicts. Could you fix it Erik Osterman (Cloud Posse) (@osterman)? 🙏

Erik Osterman (Cloud Posse) (osterman) · 2026-06-25T17:10:21Z

CodeRabbit (@coderabbitai) full review

coderabbitai · 2026-06-25T17:10:28Z

✅ Action performed

Full review finished.

…port

…from reset) The entirely-rewritten quick-start tutorials (simple + advanced) and their emulator-backed example were committed earlier on this branch, then lost when the branch was hard-reset to origin/main (reflog a622ff6). The emulator feature was re-applied afterward, but the tutorial rewrite + example were not. This restores them from the dangling commit e9c805c. - website/docs/quick-start/{simple,advanced}: rewritten tutorials (new "You will learn" intros, emulator-first "deploy on your laptop, no credentials" flow); renames configure-cli/configure-repository into configure-project, install-toolchain, start-sandbox, configure-hooks, configure-secrets. - examples/quick-start-advanced: rebuilt around the emulator (app-config, dynamodb-table, kms-key, s3-bucket, sns-topic, sqs-queue + emulator catalog; removes vpc/vpc-flow-logs-bucket). - tests: recover the repointed provenance-snapshots/flag-inheritance test inputs and the flag-inheritance fixture; regenerate the affected CLI golden snapshots. - website/docs/stacks/imports.mdx: fix inbound link to the renamed page. Verified: go build ./..., the affected CLI snapshot tests, and `npm run build` (no broken links) all pass. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

… (restored from reset) This branch was the top of 3 stacked PRs (container -> emulator -> docs-UI redesign). When the parent merged, the branch was auto-retargeted to main and a later `git reset` (a622ff6) discarded the work. Container + emulator were re-applied; this restores the lost docs-UI redesign PR from dangling commit e9c805c (29 source files, ~5.1k lines). - The right-side [Example] drawer that follows each quickstart page: components/QuickStartExampleDrawer/{index.tsx,routeMap.ts,styles.module.css}, wired via theme/DocItem/Content/index.tsx + theme/Root.tsx (reads example file contents from the existing file-browser plugin globalData). - Component restyle: File, Terminal, KeyPoints ("You will learn"), KeyTakeaways, ActionCard, EmbedExample, CopyMarkdownButton, Screengrab. - CodeBlock line-numbers feature: components/CodeLineNumberPreference + theme/CodeBlock/** ; theme/DocCard, DocBreadcrumbs, AnnouncementBar; custom.css; docusaurus.config.js; data/announcements.js. Excluded by design: the Geist-font/landing redesign (that is a different branch, osterman/sidebar-beta-badge); src/data/roadmap.js (would revert main's roadmap); regenerated Screengrabs/*.html (regenerate via the screengrabs workflow). Verified: `npm run build` succeeds (no broken links); the [Example] drawer renders on the built quickstart pages. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

The recovered advanced example uses runtime Atmos YAML functions (!secret, !store, !terraform.state) that the static yaml-language-server (InoUno/yaml-ls-check, empty customTags) cannot resolve, failing with 'Unresolved tag: !secret'. Exclude it from [validate] like the other function-using examples; it is still covered by the floci and acceptance jobs. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…n this branch) The recovered docs-UI config added client-side redirects targeting /stacks/terraform/backend, a page from a docs reorganization not included in this branch. plugin-client-redirects fails the build on redirects to non-existent paths. Point the backend redirects at /stacks/backend, which is the canonical page here. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

github-actions · 2026-06-26T03:48:04Z

Warning

Release Documentation Required

This PR is labeled minor or major and requires documentation updates:

Changelog entry ✅

Roadmap update - Update website/src/data/roadmap.js with the new milestone

Alternatively: If this change doesn't require release documentation, remove the minor or major label.

github-actions · 2026-06-26T03:48:05Z

Warning

Release Documentation Required

This PR is labeled minor or major and requires documentation updates:

Changelog entry ✅

Roadmap update - Update website/src/data/roadmap.js with the new milestone

Alternatively: If this change doesn't require release documentation, remove the minor or major label.

…lators Rewrite the changelog post from the narrow 'persistence' angle into a broad 'Introducing Emulators' announcement (the feature this PR ships): the emulator component kind + `atmos emulator` CLI, credential-free local cloud, multi-backend drivers, the emulator-based advanced quick-start, with persistence/reset as one highlight. Rename slug emulator-persistence -> introducing-emulators. Add a shipped 'Emulators' milestone to the container-composition roadmap initiative (changelog: introducing-emulators, pr: 2647; progress 57 -> 63). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

github-actions · 2026-06-26T03:55:02Z

Warning

Release Documentation Required

This PR is labeled minor or major and requires documentation updates:

Changelog entry ✅

Roadmap update - Update website/src/data/roadmap.js with the new milestone

Alternatively: If this change doesn't require release documentation, remove the minor or major label.

…oadmap milestone The prior commit only captured the file rename; this lands the actual content. Rewrite the changelog from the narrow 'persistence' angle into a broad 'Introducing Emulators' announcement (the emulator component kind, atmos emulator CLI, credential-free local cloud, multi-backend drivers, the emulator-based advanced quick-start), with persistence/reset as one highlight. Add the shipped 'Emulators' milestone to the container-composition roadmap initiative (changelog: introducing-emulators, pr: 2647; progress 57 -> 63). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…components The advanced example was rewritten (vpc/vpc-flow-logs-bucket removed in favor of kms-key/s3-bucket/dynamodb-table/...). TestDescribeComponent_{Nested,Direct}ImportProvenance and TestDescribeComponentWithProvenance still referenced the removed components, so they errored with 'Could not find the component vpc[-flow-logs-bucket]' and then nil-deref panicked. Restore the updated tests (use kms-key) from the pre-reset work. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…re !terraform.state Example (advanced): - Remove the geodesic rootfs/Dockerfile/Makefile (deprecated); the emulator-native example is a single repo-root atmos.yaml, matching examples/emulator-aws. Drop the rootfs/Dockerfile mention from configure-project.mdx. - Wire cross-component coordinates with `!terraform.state <component> <output>` instead of hand-derived ARNs/names (s3-bucket+sns-topic KMS key, sqs topic_arn, and all of app-config's bucket_id/table_name/topic_arn/queue_url/kms_key_arn). Removes the hardcoded account IDs and the stale localstack.cloud queue URL; values always match what was deployed. - Remove the duplicate `.atmos.d/test.yaml` (identical to atmos.yaml's `test`); under `list_merge_strategy: replace` it was dropping the `operator` command. - Terraform modules: require s3 `kms_key_arn` (encryption always on, SSE no longer conditional); s3 `force_destroy` default false (example opts in via stack vars); KMS `deletion_window_in_days` 7-30 validation; dynamodb `billing_mode` PAY_PER_REQUEST validation; sqs subscription depends_on the queue policy; app-config injected coordinates required (no blank-string defaults written to SSM). - README: correct the "no providers.tf" claim (components carry a stock providers.tf with no endpoint/credentials config; the override is generated). Website (docs UI): - CodeBlock action buttons: reveal on touch/coarse-pointer devices (no hover). - KeyTakeaways bullets: forced-colors/high-contrast fallback marker. - Simple configure-project: fix link label "Configure CLI" -> "Configure the Project". - add-another-component: clarify `deploy --all` scope. - configure-secrets: move the "Next" CTA to the end of the page. Not changed (verified false positives): drawer routing is by pathname not title (pageTitle is display-only); plat-uw2-prod stack exists; backend state is namespaced per Terraform workspace. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

atmos-pro · 2026-06-27T10:21:27Z

Tip

Atmos Pro

No affected stacks workflow was detected for this pull request.
If this is expected, no action is needed.
Learn More. Ask AI.

github-actions · 2026-06-27T10:22:19Z

Warning

Release Documentation Required

This PR is labeled minor or major and requires documentation updates:

Changelog entry - Add a blog post in website/blog/YYYY-MM-DD-feature-name.mdx

Roadmap update - Update website/src/data/roadmap.js with the new milestone

Alternatively: If this change doesn't require release documentation, remove the minor or major label.

github-actions · 2026-06-28T01:53:35Z

These changes were released in v1.222.0-rc.11.

Erik Osterman (Cloud Posse) (osterman) requested a review from a team as a code owner June 21, 2026 14:57

Erik Osterman (Cloud Posse) (osterman) added the no-release Do not create a new release (wait for additional code changes) label Jun 21, 2026

github-actions Bot added the size/l Large size PR label Jun 21, 2026

mergify Bot added the stacked Stacked label Jun 21, 2026

Erik Osterman (Cloud Posse) (osterman) changed the title ~~Emulators: lock in PRDs and add driver-registry foundation~~ feat(emulator): emulator PRDs + driver-registry foundation Jun 21, 2026

Erik Osterman (Cloud Posse) (osterman) requested a review from a team as a code owner June 22, 2026 20:11

github-actions Bot added size/xxl and removed size/l Large size PR labels Jun 22, 2026

mergify Bot added the needs-cloudposse Needs Cloud Posse assistance label Jun 22, 2026

mergify Bot added conflict This PR has conflicts and removed conflict This PR has conflicts labels Jun 22, 2026

github-actions Bot deployed to preview June 22, 2026 20:39 View deployment

github-actions Bot deployed to preview June 23, 2026 03:01 View deployment

github-actions Bot deployed to preview June 23, 2026 03:48 View deployment

github-actions Bot had a problem deploying to preview June 23, 2026 04:03 Failure

github-actions Bot deployed to preview June 23, 2026 04:04 View deployment

github-actions Bot deployed to preview June 23, 2026 05:03 View deployment

github-actions Bot deployed to preview June 23, 2026 06:06 View deployment

github-actions Bot deployed to preview June 23, 2026 12:24 View deployment

mergify Bot added conflict This PR has conflicts and removed conflict This PR has conflicts labels Jun 23, 2026

mergify Bot added the conflict This PR has conflicts label Jun 25, 2026

Merge origin/main into emulator support

80c191a

mergify Bot removed the conflict This PR has conflicts label Jun 25, 2026

github-actions Bot deployed to preview June 25, 2026 13:56 View deployment

fix: address emulator review findings

c86b753

Erik Osterman (Cloud Posse) (osterman) force-pushed the osterman/emulator-support branch from 596f57b to c86b753 Compare June 25, 2026 21:20

github-actions Bot deployed to preview June 25, 2026 21:23 View deployment

github-actions Bot deployed to preview June 25, 2026 21:25 View deployment

Erik Osterman (Cloud Posse) (osterman) and others added 6 commits June 25, 2026 16:46

fix: parse docker published ports

9cb9bee

Merge remote-tracking branch 'origin/main' into osterman/emulator-sup…

525ba2f

…port

Erik Osterman (Cloud Posse) (osterman) and others added 4 commits June 25, 2026 22:55

Merge branch 'main' into osterman/emulator-support

6523621

Andriy Knysh (aknysh) approved these changes Jun 27, 2026

View reviewed changes

Erik Osterman (Cloud Posse) (osterman) mentioned this pull request Jun 28, 2026

feat: local Terraform tests against cloud emulators #2663

Merged

Uh oh!

Uh oh!

Conversation

Erik Osterman (Cloud Posse) (osterman) commented Jun 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

what

why

references

Uh oh!

atmos-pro Bot commented Jun 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Atmos Pro

Uh oh!

github-actions Bot commented Jun 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Dependency Review

Scanned Files

Uh oh!

codecov Bot commented Jun 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

mergify Bot commented Jun 22, 2026

This PR exceeds the recommended limit of 10,000 lines.

Uh oh!

mergify Bot commented Jun 22, 2026

Cloud Posse Engineering Team Review Required

Uh oh!

mergify Bot commented Jun 22, 2026

Uh oh!

Erik Osterman (Cloud Posse) (osterman) commented Jun 23, 2026

Uh oh!

coderabbitai Bot commented Jun 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mergify Bot commented Jun 23, 2026

Uh oh!

mergify Bot commented Jun 25, 2026

Uh oh!

Erik Osterman (Cloud Posse) (osterman) commented Jun 25, 2026

Uh oh!

coderabbitai Bot commented Jun 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Jun 26, 2026

Release Documentation Required

Uh oh!

github-actions Bot commented Jun 26, 2026

Release Documentation Required

Uh oh!

github-actions Bot commented Jun 26, 2026

Release Documentation Required

Uh oh!

atmos-pro Bot commented Jun 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Atmos Pro

Uh oh!

github-actions Bot commented Jun 27, 2026

Release Documentation Required

Uh oh!

github-actions Bot commented Jun 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Erik Osterman (Cloud Posse) (osterman) commented Jun 21, 2026 •

edited

Loading

atmos-pro Bot commented Jun 21, 2026 •

edited

Loading

github-actions Bot commented Jun 21, 2026 •

edited

Loading

codecov Bot commented Jun 21, 2026 •

edited

Loading

coderabbitai Bot commented Jun 23, 2026 •

edited

Loading

coderabbitai Bot commented Jun 25, 2026 •

edited

Loading

atmos-pro Bot commented Jun 27, 2026 •

edited

Loading