aws cloudformation create-change-set: Preview Stack Changes
aws cloudformation create-change-set computes the difference between a deployed stack and a new template, so a pipeline can review (and gate on) what will change before executing it.
Change sets are CloudFormation's dry run. In CI you create one, inspect it, optionally require approval, then execute, instead of letting deploy apply blindly.
What it does
aws cloudformation create-change-set builds a named set of proposed changes for --stack-name from --template-body/--template-url and --parameters. You then describe-change-set to see additions, modifications, and replacements, and execute-change-set to apply. --change-set-type CREATE is required when the stack does not exist yet.
Common usage
aws cloudformation create-change-set \
--stack-name my-service \
--change-set-name "cs-$GITHUB_SHA" \
--template-body file://template.yaml \
--capabilities CAPABILITY_NAMED_IAM \
--parameters ParameterKey=Stage,ParameterValue=prod
aws cloudformation wait change-set-create-complete \
--stack-name my-service --change-set-name "cs-$GITHUB_SHA"
aws cloudformation describe-change-set \
--stack-name my-service --change-set-name "cs-$GITHUB_SHA" \
--query 'Changes[].ResourceChange.{Action:Action,Type:ResourceType,Id:LogicalResourceId}'Options
| Flag | What it does |
|---|---|
| --stack-name <name> | Target stack (required) |
| --change-set-name <name> | Name for this change set (required) |
| --template-body file://<f> | New template to diff against |
| --change-set-type CREATE|UPDATE | CREATE for a non-existent stack |
| --capabilities CAPABILITY_NAMED_IAM | Acknowledge IAM resource creation |
| --parameters ParameterKey=..,ParameterValue=.. | Stack parameters |
In CI
Use --change-set-type CREATE for first deploys; the default UPDATE fails if the stack does not exist. Acknowledge CAPABILITY_NAMED_IAM (or CAPABILITY_IAM) when the template creates roles/policies, or creation is rejected. Watch for "didn't contain changes": a no-op change set still appears as FAILED with a benign reason, so special-case that string before failing the job.
Common errors in CI
"An error occurred (InsufficientCapabilitiesException): Requires capabilities : [CAPABILITY_NAMED_IAM]" means the template creates named IAM resources; add the flag. A change set whose StatusReason is "The submitted information didn't contain changes" or "No updates are to be performed" is a benign no-op, not a real failure. "ValidationError: Stack ... does not exist" with UPDATE means you need --change-set-type CREATE. "AlreadyExistsException" means a change set with that name already exists; use a unique name like the SHA.