aws cloudformation deploy: Deploy a Stack in CI

Create or update a CloudFormation stack idempotently using change sets.

aws cloudformation deploy packages and applies a template, creating a change set and executing it. It also underpins sam deploy. In CI it deploys serverless and infrastructure stacks, with --capabilities required when the stack creates IAM resources.

Common flags

--template-file - the template to deploy (required)
--stack-name - the target stack (required)
--parameter-overrides Key=Value - pass template parameters
--capabilities CAPABILITY_IAM CAPABILITY_NAMED_IAM - acknowledge IAM resource creation
--no-fail-on-empty-changeset - treat "no changes" as success in CI

Example in CI

Deploy a stack that creates IAM roles.

shell

aws cloudformation deploy --template-file template.yml --stack-name my-app --capabilities CAPABILITY_IAM --parameter-overrides Env=prod --no-fail-on-empty-changeset

Common errors in CI

No changes to deploy. Stack ... is up to date - exits non-zero unless --no-fail-on-empty-changeset
An error occurred (InsufficientCapabilitiesException) - add --capabilities CAPABILITY_IAM
Failed to create/update the stack ... ROLLBACK_COMPLETE - delete the failed stack and redeploy
An error occurred (ValidationError) - template or parameter validation failed

Key takeaways

deploy is idempotent via change sets - it creates or updates as needed.
Add --no-fail-on-empty-changeset so "no changes" does not fail the CI job.
Stacks creating IAM resources need --capabilities CAPABILITY_IAM (or NAMED_IAM).