Update behaviour

What CloudFormation actually does to a running resource when you change a property — and why “Replacement” deserves to be red.

The four behaviours #

Every property in this reference carries one of four update behaviours. They describe what happens to the existing resource when only that property changes.

How replacement actually runs #

This is the part that determines whether a replacement is survivable.

Create-only properties #

A property marked create-only can be set at creation and never changed. Changing it in a template is not an error — it is a request to replace the resource, and CloudFormation will do exactly that.

The two are usually the same property. BucketName, RoleName, ImageId and SubnetId are all create-only and all cause replacement, because the underlying API has no way to change them on an existing resource.

Reading a change set before you trust it #

The single most useful habit around update behaviour:

aws cloudformation create-change-set \
  --stack-name payments-production \
  --change-set-name review \
  --template-body file://template.yaml \
  --capabilities CAPABILITY_IAM

aws cloudformation describe-change-set \
  --stack-name payments-production \
  --change-set-name review \
  --query 'Changes[?ResourceChange.Replacement==`True`].ResourceChange.{Id:LogicalResourceId,Type:ResourceType,Because:Scope}' \
  --output table

Deletion policies #

Two policies govern what happens to a resource CloudFormation wants to remove, and the distinction between them is the one people miss.