atmos aws cloudformation diff

Create a CloudFormation changeset for the component, render the predicted changes, and delete the changeset again without executing it. diff authenticates and calls the CloudFormation API — it previews what apply would actually do to the live stack, unlike render, which never leaves the local template.

Experimental

atmos aws cloudformation diff --help

Usage

atmos aws cloudformation diff <component> --stack <stack> [options]

atmos aws cloudformation diff vpc -s plat-ue2-dev

Diff all or affected components in dependency order:

atmos aws cloudformation diff --all -s plat-ue2-dev
atmos aws cloudformation diff --affected --base origin/main

Diff components filtered by tags or labels (composes with --all/--affected to narrow the selected set further):

atmos aws cloudformation diff --all --tags production,tier-1
atmos aws cloudformation diff --affected --labels cost-center=platform

Behavior

diff leaves nothing behind. It deletes the preview changeset after rendering it, including when the changeset would change nothing (CloudFormation reports that as a FAILED changeset, "didn't contain changes").

For a component that has never been deployed, CloudFormation registers an empty REVIEW_IN_PROGRESS stack as soon as the changeset is created. When diff created that stack itself, it deletes it again after removing the changeset, having first confirmed it is still REVIEW_IN_PROGRESS, so a preview never leaves a stub that list would show as managed. A stack that already existed, including an empty REVIEW_IN_PROGRESS stub left by an earlier run, is never deleted.

A stack in ROLLBACK_COMPLETE cannot be updated, so diff fails with an explanation and a hint to run atmos aws cloudformation delete for the component and apply again.

Flags

--stack, -s (required for a single component)

Atmos stack. Required when operating on a single component; optional (and used only to narrow the selected set) with --all/--affected.

--all (optional)

Process all aws/cloudformation components in dependency order.

--affected (optional)

Process affected aws/cloudformation components and their dependencies. Compares the working tree against a base: see --base and the Git flags below.

--include-dependents (optional)

With --affected, include dependent aws/cloudformation components.

--base (optional)

Git base ref or SHA to compare against for affected detection: --base=origin/main. A value that looks like a commit SHA is treated as --sha, anything else as --ref. Used with --affected.

--tags (optional)

Filter by tags (comma-separated, matches any): --tags=production,tier-1. Composes with --all/--affected to narrow the selected set further; cannot be combined with a single component argument.

--labels (optional)

Filter by labels (repeatable and/or comma-separated key=value or key:value pairs, matches all): --labels=cost-center=platform,compliance=sox. Composes with --all/--affected/--tags; cannot be combined with a single component argument.

--ci (optional)

Enable native CI integration (requires ci.enabled): writes the job summary and output variables for the operation. Also enabled by the CI and ATMOS_CI environment variables.

--ref (optional)

Git ref to compare against for affected detection. Used with --affected.

--sha (optional)

Git SHA to compare against for affected detection. Used with --affected.

--repo-path (optional)

Path to an already cloned target repository to use as the affected baseline. Used with --affected.

--clone-target-ref (optional)

Clone the target ref instead of checking it out in the current repository for affected detection. Used with --affected.

--ssh-key (optional)

Path to the SSH private key used to clone the target ref for affected detection. Used with --clone-target-ref.

--ssh-key-password (optional)

Password for the SSH private key used to clone the target ref for affected detection. Used with --clone-target-ref.

--skip-hooks (optional)

Skip lifecycle hooks for this invocation. --skip-hooks with no value skips every hook; --skip-hooks=name1,name2 skips only the named hooks. Equivalent to the ATMOS_SKIP_HOOKS environment variable.

note

atmos aws cloudformation plan is an alias for diff. Both fire the before.aws/cloudformation.diff/after.aws/cloudformation.diff hook events.