This section provides examples of the change sets that CloudFormation would create for common stack changes. They show how to edit a template directly; modify a single input parameter; plan for resource recreation (replacements), which prevents you from losing data that wasn't backed up or interrupting applications that are running in your stack; and add and remove resources. To illustrate how change sets work, we'll walk through the changes that were submitted and discuss the resulting change set. Because each example builds on and assumes that you understand the previous example, we recommend that you read them in order. For a description of each field in a change set, see the Change data type in the AWS CloudFormation API Reference.
You can use the console, AWS CLI, or CloudFormation DescribeChangeSet API operation to view change set details.
We generated each of the following change sets from a stack with the
following sample template
{
"AWSTemplateFormatVersion" : "2010-09-09",
"Description" : "A sample EC2 instance template for testing change sets.",
"Parameters" : {
"Purpose" : {
"Type" : "String",
"Default" : "testing",
"AllowedValues" : ["testing", "production"],
"Description" : "The purpose of this instance."
},
"KeyPairName" : {
"Type": "AWS::EC2::KeyPair::KeyName",
"Description" : "Name of an existing EC2 KeyPair to enable SSH access to the instance"
},
"InstanceType" : {
"Type" : "String",
"Default" : "t2.micro",
"AllowedValues" : ["t2.micro", "t2.small", "t2.medium"],
"Description" : "The EC2 instance type."
}
},
"Resources" : {
"MyEC2Instance" : {
"Type" : "AWS::EC2::Instance",
"Properties" : {
"KeyName" : { "Ref" : "KeyPairName" },
"InstanceType" : { "Ref" : "InstanceType" },
"ImageId" : "ami-8fcee4e5",
"Tags" : [
{
"Key" : "Purpose",
"Value" : { "Ref" : "Purpose" }
}
]
}
}
}
}
Directly editing a template
When you directly modify resources in the stack's template to generate a change set,
CloudFormation classifies the change as a direct modification, as opposed to changes initiated
by an updated parameter value. The following change set, which added a new tag to the
i-1abc23d4
instance, is an example of a direct modification. All other input
values, such as the parameter values and capabilities, are unchanged, so we'll focus on the
Changes
structure.
{
"StackId": "arn:aws:cloudformation:us-east-1:123456789012:stack/MyStack/1a2345b6-0000-00a0-a123-00abc0abc000",
"Status": "CREATE_COMPLETE",
"ChangeSetName": "SampleChangeSet-direct",
"Parameters": [
{
"ParameterValue": "testing",
"ParameterKey": "Purpose"
},
{
"ParameterValue": "MyKeyName",
"ParameterKey": "KeyPairName"
},
{
"ParameterValue": "t2.micro",
"ParameterKey": "InstanceType"
}
],
"Changes": [
{
"ResourceChange": {
"ResourceType": "AWS::EC2::Instance",
"PhysicalResourceId": "i-1abc23d4",
"Details": [
{
"ChangeSource": "DirectModification",
"Evaluation": "Static",
"Target": {
"Attribute": "Tags",
"RequiresRecreation": "Never"
}
}
],
"Action": "Modify",
"Scope": [
"Tags"
],
"LogicalResourceId": "MyEC2Instance",
"Replacement": "False"
},
"Type": "Resource"
}
],
"CreationTime": "2020-11-18T23:35:25.813Z",
"Capabilities": [],
"StackName": "MyStack",
"NotificationARNs": [],
"ChangeSetId": "arn:aws:cloudformation:us-east-1:123456789012:changeSet/SampleChangeSet-direct/1a2345b6-0000-00a0-a123-00abc0abc000"
}
In the Changes
structure, there's only one ResourceChange
structure. This structure describes information such as the type of resource CloudFormation will
change, the action CloudFormation will take, the ID of the resource, the scope of the change,
and whether the change requires a replacement (where CloudFormation creates a new resource and
then deletes the old one). In the example, the change set indicates that CloudFormation will
modify the Tags
attribute of the i-1abc23d4
EC2 instance, and
doesn't require the instance to be replaced.
In the Details
structure, CloudFormation labels this change as a direct
modification that will never require the instance to be recreated (replaced). You can
confidently execute this change, knowing that CloudFormation won't replace the instance.
CloudFormation shows this change as a Static
evaluation. A static evaluation
means that CloudFormation can determine the tag's value before executing the change set. In some
cases, CloudFormation can determine a value only after you execute a change set. CloudFormation
labels those changes as Dynamic
evaluations. For example, if you reference an
updated resource that's conditionally replaced, CloudFormation can't determine whether the
reference to the updated resource will change.
Modifying an input parameter value
When you modify an input parameter value, CloudFormation generates two changes for each
resource that uses the updated parameter value. In this example, we want to highlight what
those changes look like and which information you should focus on. The following example was
generated by changing the value of the Purpose
input parameter only.
The Purpose
parameter specifies a tag key value for the EC2 instance. In
the example, the parameter value was changed from testing
to
production
. The new value is shown in the Parameters
structure.
{
"StackId": "arn:aws:cloudformation:us-east-1:123456789012:stack/MyStack/1a2345b6-0000-00a0-a123-00abc0abc000",
"Status": "CREATE_COMPLETE",
"ChangeSetName": "SampleChangeSet",
"Parameters": [
{
"ParameterValue": "production",
"ParameterKey": "Purpose"
},
{
"ParameterValue": "MyKeyName",
"ParameterKey": "KeyPairName"
},
{
"ParameterValue": "t2.micro",
"ParameterKey": "InstanceType"
}
],
"Changes": [
{
"ResourceChange": {
"ResourceType": "AWS::EC2::Instance",
"PhysicalResourceId": "i-1abc23d4",
"Details": [
{
"ChangeSource": "DirectModification",
"Evaluation": "Dynamic",
"Target": {
"Attribute": "Tags",
"RequiresRecreation": "Never"
}
},
{
"CausingEntity": "Purpose",
"ChangeSource": "ParameterReference",
"Evaluation": "Static",
"Target": {
"Attribute": "Tags",
"RequiresRecreation": "Never"
}
}
],
"Action": "Modify",
"Scope": [
"Tags"
],
"LogicalResourceId": "MyEC2Instance",
"Replacement": "False"
},
"Type": "Resource"
}
],
"CreationTime": "2020-11-18T23:59:18.447Z",
"Capabilities": [],
"StackName": "MyStack",
"NotificationARNs": [],
"ChangeSetId": "arn:aws:cloudformation:us-east-1:123456789012:changeSet/SampleChangeSet/1a2345b6-0000-00a0-a123-00abc0abc000"
}
The Changes
structure functions similar to way it does in the Directly editing a template
example. There's only one ResourceChange
structure; it describes a change to
the Tags
attribute of the i-1abc23d4
EC2 instance.
However, in the Details
structure, the change set shows two changes for the
Tags
attribute, even though only a single parameter value was changed.
Resources that reference a changed parameter value (using the Ref
intrinsic
function) always result in two changes: one with a Dynamic
evaluation and
another with a Static
evaluation. You can see these types of changes by viewing
the following fields:
-
For the
Static
evaluation change, view theChangeSource
field. In this example, theChangeSource
field equalsParameterReference
, meaning that this change is a result of an updated parameter reference value. The change set must contain a similarDynamic
evaluation change. -
You can find the matching
Dynamic
evaluation change by comparing theTarget
structure for both changes, which will contain the same information. In this example, theTarget
structures for both changes contain the same values for theAttribute
andRequireRecreation
fields.
For these types of changes, focus on the static evaluation, which gives you the most
detailed information about the change. In this example, the static evaluation shows that the
change is the result of a change in a parameter reference value
(ParameterReference
). The exact parameter that was changed is indicated by
the CauseEntity
field (the Purpose
parameter).
Determining the value of the replacement field
The Replacement
field in a ResourceChange
structure indicates
whether CloudFormation will recreate the resource. Planning for resource recreation
(replacements) prevents you from losing data that wasn't backed up or interrupting
applications that are running in your stack.
The value in the Replacement
field depends on whether a change requires a
replacement, indicated by the RequiresRecreation
field in a change's
Target
structure. For example, if the RequiresRecreation
field
is Never
, the Replacement
field is False
. However, if
there are multiple changes on a single resource and each change has a different value for
the RequiresRecreation
field, CloudFormation updates the resource using the most
intrusive behavior. In other words, if only one of the many changes requires a replacement,
CloudFormation must replace the resource and, therefore, sets the Replacement
field
to True
.
The following change set was generated by changing the values for every parameter
(Purpose
, InstanceType
, and KeyPairName
), which are
all used by the EC2 instance. With these changes, CloudFormation will be required to replace the
instance because the Replacement
field is equal to True
.
{
"StackId": "arn:aws:cloudformation:us-east-1:123456789012:stack/MyStack/1a2345b6-0000-00a0-a123-00abc0abc000",
"Status": "CREATE_COMPLETE",
"ChangeSetName": "SampleChangeSet-multiple",
"Parameters": [
{
"ParameterValue": "production",
"ParameterKey": "Purpose"
},
{
"ParameterValue": "MyNewKeyName",
"ParameterKey": "KeyPairName"
},
{
"ParameterValue": "t2.small",
"ParameterKey": "InstanceType"
}
],
"Changes": [
{
"ResourceChange": {
"ResourceType": "AWS::EC2::Instance",
"PhysicalResourceId": "i-7bef86f8",
"Details": [
{
"ChangeSource": "DirectModification",
"Evaluation": "Dynamic",
"Target": {
"Attribute": "Properties",
"Name": "KeyName",
"RequiresRecreation": "Always"
}
},
{
"ChangeSource": "DirectModification",
"Evaluation": "Dynamic",
"Target": {
"Attribute": "Properties",
"Name": "InstanceType",
"RequiresRecreation": "Conditionally"
}
},
{
"ChangeSource": "DirectModification",
"Evaluation": "Dynamic",
"Target": {
"Attribute": "Tags",
"RequiresRecreation": "Never"
}
},
{
"CausingEntity": "KeyPairName",
"ChangeSource": "ParameterReference",
"Evaluation": "Static",
"Target": {
"Attribute": "Properties",
"Name": "KeyName",
"RequiresRecreation": "Always"
}
},
{
"CausingEntity": "InstanceType",
"ChangeSource": "ParameterReference",
"Evaluation": "Static",
"Target": {
"Attribute": "Properties",
"Name": "InstanceType",
"RequiresRecreation": "Conditionally"
}
},
{
"CausingEntity": "Purpose",
"ChangeSource": "ParameterReference",
"Evaluation": "Static",
"Target": {
"Attribute": "Tags",
"RequiresRecreation": "Never"
}
}
],
"Action": "Modify",
"Scope": [
"Tags",
"Properties"
],
"LogicalResourceId": "MyEC2Instance",
"Replacement": "True"
},
"Type": "Resource"
}
],
"CreationTime": "2020-11-18T00:39:35.974Z",
"Capabilities": [],
"StackName": "MyStack",
"NotificationARNs": [],
"ChangeSetId": "arn:aws:cloudformation:us-east-1:123456789012:changeSet/SampleChangeSet-multiple/1a2345b6-0000-00a0-a123-00abc0abc000"
}
Identify the change that requires the resource to be replaced by viewing each change
(the static evaluations in the Details
structure). In this example, each change
has a different value for the RequireRecreation
field, but the change to the
KeyName
property has the most intrusive update behavior, always requiring a
recreation. CloudFormation will replace the instance because the key name was changed.
If the key name were unchanged, the change to the InstanceType
property
would have the most intrusive update behavior (Conditionally
), so the
Replacement
field would be Conditionally
. To find the conditions
in which CloudFormation replaces the instance, view the update behavior for the
InstanceType
property of the AWS::EC2::Instance resource type.
Adding and removing resources
The following example was generated by submitting a modified template that removes the EC2 instance and adds an Auto Scaling group and launch configuration.
{
"StackId": "arn:aws:cloudformation:us-east-1:123456789012:stack/MyStack/1a2345b6-0000-00a0-a123-00abc0abc000",
"Status": "CREATE_COMPLETE",
"ChangeSetName": "SampleChangeSet-addremove",
"Parameters": [
{
"ParameterValue": "testing",
"ParameterKey": "Purpose"
},
{
"ParameterValue": "MyKeyName",
"ParameterKey": "KeyPairName"
},
{
"ParameterValue": "t2.micro",
"ParameterKey": "InstanceType"
}
],
"Changes": [
{
"ResourceChange": {
"Action": "Add",
"ResourceType": "AWS::AutoScaling::AutoScalingGroup",
"Scope": [],
"Details": [],
"LogicalResourceId": "AutoScalingGroup"
},
"Type": "Resource"
},
{
"ResourceChange": {
"Action": "Add",
"ResourceType": "AWS::AutoScaling::LaunchConfiguration",
"Scope": [],
"Details": [],
"LogicalResourceId": "LaunchConfig"
},
"Type": "Resource"
},
{
"ResourceChange": {
"ResourceType": "AWS::EC2::Instance",
"PhysicalResourceId": "i-1abc23d4",
"Details": [],
"Action": "Remove",
"Scope": [],
"LogicalResourceId": "MyEC2Instance"
},
"Type": "Resource"
}
],
"CreationTime": "2020-11-18T01:44:08.444Z",
"Capabilities": [],
"StackName": "MyStack",
"NotificationARNs": [],
"ChangeSetId": "arn:aws:cloudformation:us-east-1:123456789012:changeSet/SampleChangeSet-addremove/1a2345b6-0000-00a0-a123-00abc0abc000"
}
In the Changes
structure, there are three ResourceChange
structures, one for each resource. For each resource, the Action
field
indicates whether CloudFormation adds or removes the resource. The Scope
and
Details
fields are empty because they apply only to modified
resources.
For new resources, CloudFormation can't determine the value of some fields until you execute the change set. For example, CloudFormation doesn't provide the physical IDs of the Auto Scaling group and launch configuration because they don't exist yet. CloudFormation creates the new resources when you execute the change set.
Viewing property-level changes
The following example shows property-level changes to the Tag
property of
an Amazon EC2 instance. The tag Value
and Key
will change to
Test
.
"ChangeSetName": "SampleChangeSet",
"ChangeSetId": "arn:aws:cloudformation:us-east-1:123456789012:changeSet/SampleChangeSet/38d91d27-798d-4736-9bf1-fb7c46207807",
"StackId": "arn:aws:cloudformation:us-east-1:123456789012:stack/SampleEc2Template/68edcdc0-f6b6-11ee-966c-126d572cdd11",
"StackName": "SampleEc2Template",
"Description": "A sample EC2 instance template for testing change sets.",
"Parameters": [
{
"ParameterKey": "KeyPairName",
"ParameterValue": "BatchTest"
},
{
"ParameterKey": "Purpose",
"ParameterValue": "testing"
},
{
"ParameterKey": "InstanceType",
"ParameterValue": "t2.micro"
}
],
"CreationTime": "2024-04-09T21:29:10.759000+00:00",
"ExecutionStatus": "AVAILABLE",
"Status": "CREATE_COMPLETE",
"StatusReason": null,
"NotificationARNs": [],
"RollbackConfiguration": {
:...skipping...
{
"Changes": [
{
"Type": "Resource",
"ResourceChange": {
"Action": "Modify",
"LogicalResourceId": "MyEC2Instance",
"PhysicalResourceId": "i-0cc7856a36315e62b",
"ResourceType": "AWS::EC2::Instance",
"Replacement": "False",
"Scope": [
"Tags"
],
"Details": [
{
"Target": {
"Attribute": "Tags",
"RequiresRecreation": "Never",
"Path": "/Properties/Tags/0/Value",
"BeforeValue": "testing",
"AfterValue": "Test",
"AttributeChangeType": "Modify"
},
"Evaluation": "Static",
"ChangeSource": "DirectModification"
},
{
"Target": {
"Attribute": "Tags",
"RequiresRecreation": "Never",
"Path": "/Properties/Tags/0/Key",
"BeforeValue": "Purpose",
"AfterValue": "Test",
"AttributeChangeType": "Modify"
},
"Evaluation": "Static",
"ChangeSource": "DirectModification"
}
],
"BeforeContext": "{\"Properties\":{\"KeyName\":\"BatchTest\",\"ImageId\":\"ami-8fcee4e5\",\"InstanceType\":\"t2.micro\",\"Tags\":[{\"Value\":\"testing\",\"Key\":\"Purpose\"}]}}",
"AfterContext": "{\"Properties\":{\"KeyName\":\"BatchTest\",\"ImageId\":\"ami-8fcee4e5\",\"InstanceType\":\"t2.micro\",\"Tags\":[{\"Value\":\"Test\",\"Key\":\"Test\"}]}}"
}
}
]
The Details
structure shows the values for Key
and
Value
before the change set is executed, and what they will be after the
change set is executed.