UpdatePolicy Attribute

For AWS::AutoScaling::AutoScalingGroup resources, AWS CloudFormation invokes one of three update policies depending on the
type of change you make or whether a scheduled action is associated with the Auto
Scaling group.

The AutoScalingReplacingUpdate and AutoScalingRollingUpdate
policies apply only when you do one or more of the following:

Update an Auto Scaling group that contains instances that don't match the current
LaunchConfiguration.

If both the AutoScalingReplacingUpdate and AutoScalingRollingUpdate policies are specified, setting the WillReplace property to true gives AutoScalingReplacingUpdate precedence.

The AutoScalingScheduledAction policy applies when you update a stack that includes an Auto Scaling group with an
associated scheduled action.

For AWS::Lambda::Alias resources, AWS CloudFormation performs an CodeDeploy deployment when the version
changes on the alias.
For more information, see CodeDeployLambdaAliasUpdate Policy.

For AWS::ElastiCache::ReplicationGroup resources, AWS CloudFormation can modify a replication group's shards by adding or
removing shards, rather than replacing
the entire resource. For more information, see UseOnlineResharding Policy.

AutoScalingReplacingUpdate Policy

To specify how AWS CloudFormation handles replacement updates for an Auto Scaling
group, use the AutoScalingReplacingUpdate policy. This policy enables you to specify whether AWS CloudFormation replaces an
Auto Scaling group with a new one or replaces only the instances in the Auto Scaling
group.

Important

Before attempting an update, ensure that you have sufficient Amazon EC2 capacity for
both your old and new Auto Scaling groups.

Syntax

JSON

YAML

Properties

WillReplace

Specifies whether an Auto Scaling group and the instances it contains are replaced
during an update. During replacement, AWS CloudFormation retains the old group until
it finishes creating the new one. If the update fails, AWS CloudFormation can roll
back to the old Auto Scaling group and delete the new Auto Scaling group.

While AWS CloudFormation creates the new group, it doesn't detach or attach any instances.
After successfully creating the new Auto Scaling group, AWS CloudFormation deletes
the old Auto Scaling group during the cleanup process.

When you set the WillReplace parameter, remember to specify a matching CreationPolicy. If the minimum number of instances (specified by the MinSuccessfulInstancesPercent property) don't signal success within the Timeout period (specified in the CreationPolicy policy), the replacement update fails and AWS CloudFormation rolls back to the old
Auto Scaling group.

Type: Boolean

Required: No

AutoScalingRollingUpdate Policy

To specify how AWS CloudFormation handles rolling updates for an Auto Scaling group,
use the AutoScalingRollingUpdate policy. Rolling updates enable you to specify whether AWS CloudFormation updates
instances that are in an Auto Scaling group in batches or all at once.

Be aware that, during stack update rollback operations, CloudFormation uses the
UpdatePolicy configuration specified in the template before the current stack
update operation. For example, suppose you have updated the MaxBatchSize in your
stack template's UpdatePolicy from 1 to 10. You then perform a stack update, and
that update fails and CloudFormation initiates an update rollback operation. In such
a case,
CloudFormation will use 1 as the maximum batch size, rather than 10. For this reason,
we
recommend you make changes to the UpdatePolicy configuration in a stack update
separate from, and prior to, any updates to the
AWS::AutoScaling::AutoScalingGroup resource that are likely to trigger rolling
updates.

Properties

MaxBatchSize

Specifies the maximum number of instances that AWS CloudFormation updates.

Default: 1

Type: Integer

Required: No

MinInstancesInService

Specifies the minimum number of instances that must be in service within the Auto
Scaling group while AWS CloudFormation updates old instances. This value must be less
than the MaxSize of
the Auto Scaling group.

Default: 0

Type: Integer

Required: No

MinSuccessfulInstancesPercent

Specifies the percentage of instances in an Auto Scaling rolling update that must
signal
success for an update to succeed. You can specify a value from 0 to
100. AWS CloudFormation rounds to the nearest tenth of a percent. For example, if
you update five instances with a minimum successful percentage of 50,
three instances must signal success.

If an instance doesn't send a signal within the time specified in the PauseTime property, AWS CloudFormation assumes that the instance wasn't updated.

If you specify this property, you must also enable the
WaitOnResourceSignals and PauseTime properties.

The MinSuccessfulInstancesPercent parameter applies only to instances only for signaling purpose. To specify the number
of instances in your autoscaling group, see the MinSize, MaxSize, and DesiredCapacity properties fo the AWS::AutoScaling::AutoScalingGroup resource.

Default: 100

Type: Integer

Required: No

PauseTime

The amount of time that AWS CloudFormation pauses after making a change to a batch
of instances to give those instances time to start software applications. For example,
you might need to specify PauseTime when scaling up the number of instances in an Auto Scaling group.

If you enable the WaitOnResourceSignals property, PauseTime is the amount of time that AWS CloudFormation should wait for the Auto Scaling group
to receive the required number of valid signals from added or replaced instances.
If the PauseTime is exceeded before the Auto Scaling group receives the required number of signals,
the update fails. For best results, specify a time period that gives your applications
sufficient time to get started. If the update needs to be
rolled back, a short PauseTime can cause the rollback to fail.

Specify PauseTime in the ISO8601 duration
format (in the format
PT#H#M#S,
where each # is the number of hours, minutes, and seconds,
respectively). The maximum PauseTime is one hour
(PT1H).

Default: PT0S (zero seconds). If the
WaitOnResourceSignals property is set to true, the default
is PT5M.

Type: String

Required: No

SuspendProcesses

Specifies the Auto Scaling processes to suspend during a stack update. Suspending
processes prevents Auto Scaling from interfering with a stack update. For example,
you can
suspend alarming so that Amazon EC2 Auto Scaling doesn't execute scaling policies
associated with an
alarm. For valid values, see the ScalingProcesses.member.N parameter for
the SuspendProcesses action
in the Amazon EC2 Auto Scaling API Reference.

Default: Not specified

Type: List of Auto Scaling processes

Required: No

WaitOnResourceSignals

Specifies whether the Auto Scaling group waits on signals from new instances during
an update. Use this property to ensure that instances have completed installing and
configuring applications before the Auto Scaling group update proceeds. AWS CloudFormation
suspends the update of an Auto Scaling group after new EC2 instances are launched
into the group. AWS CloudFormation must receive a signal from each new instance within
the specified PauseTime before continuing the update. To signal the Auto Scaling group, use the
cfn-signal helper script or SignalResource API.

To have instances wait for an Elastic Load Balancing health check before they signal
success, add a
health-check verification by using the cfn-init helper script. For an example, see the
verify_instance_health command in the Auto Scaling rolling updates sample template.

Default: false

Type: Boolean

Required: Conditional. If you specify the
MinSuccessfulInstancesPercent property, you must also enable the
WaitOnResourceSignals and PauseTime properties.

AutoScalingScheduledAction Policy

To specify how AWS CloudFormation handles updates for the MinSize, MaxSize,
and DesiredCapacity properties when the
AWS::AutoScaling::AutoScalingGroup resource has an associated scheduled action,
use the AutoScalingScheduledAction policy.

With scheduled actions, the group size properties of an Auto Scaling group can change
at any time.
When you update a stack with an Auto Scaling group and scheduled action, AWS CloudFormation
always sets the group
size property values of your Auto Scaling group to the values that are defined in
the
AWS::AutoScaling::AutoScalingGroup resource of your template, even if a
scheduled action is in effect.

If you do not want AWS CloudFormation to change any of the group size property values
when you have a
scheduled action in effect, use the AutoScalingScheduledAction update policy to
prevent AWS CloudFormation from changing the MinSize, MaxSize, or
DesiredCapacity properties unless you have modified these values in your
template.

Syntax

JSON

YAML

Properties

IgnoreUnmodifiedGroupSizeProperties

Specifies whether AWS CloudFormation ignores differences in group size properties
between your
current Auto Scaling group and the Auto Scaling group described in the
AWS::AutoScaling::AutoScalingGroup resource of your template during a
stack update. If you modify any of the group size property values in your template,
AWS CloudFormation uses the modified values and updates your Auto Scaling group.

Default: false

Type: Boolean

Required: No

CodeDeployLambdaAliasUpdate Policy

To perform an CodeDeploy deployment when the version changes on an AWS::Lambda::Alias resource, use the CodeDeployLambdaAliasUpdate update policy.

UseOnlineResharding Policy

To modify a replication group's shards by adding or removing shards, rather than replacing
the entire AWS::ElastiCache::ReplicationGroup resource, use the
UseOnlineResharding update policy.

If UseOnlineResharding is set to true, you can update the
NumNodeGroups and NodeGroupConfiguration properties of the
AWS::ElastiCache::ReplicationGroup resource, and CloudFormation will update those
properties without interruption. When UseOnlineResharding is set to
false, or not specified, updating the NumNodeGroups and
NodeGroupConfiguration properties results in CloudFormation replacing the entire
AWS::ElastiCache::ReplicationGroup resource.

The UseOnlineResharding update policy has no properties.

Things to consider when setting the UseOnlineResharding update policy to
true:

We strongly recommend you perform updates to the NumNodeGroups and
NodeGroupConfiguration properties as the only updates in a given stack
update operation.

Updating the node group configuration of a replication group is a resource-intensive
operation. If a stack update fails, CloudFormation does not roll back changes to the
node
group configuration of a replication group. However, CloudFormation will roll back
any
other properties that were changed as part of the failed update operation.

Any node group updates require identifying all node groups

If you specify the NodeGroupConfiguration property, you must also specify
the NodeGroupId for each node group configuration in order for CloudFormation to update
the number of nodes without interruption.

When creating a replication group, if you do not specify an ID for each node group,
ElastiCache automatically generates an ID for each node group. To update the replication
group
without interruption, use the ElastiCache console (https://console.aws.amazon.com/elasticache/) or DescribeReplicationGroups
to retrieve the IDs for all node groups in the replication group. Then specify the
ID for
each node group in your stack template before attempting to add or remove shards.

Note

As a best practice, when you create a replication group in a stack template, include
an
ID for each node group you specify.

In addition, updating the number of nodes without interruption requires that you have
accurately specified the PrimaryAvailabilityZone, ReplicaAvailabilityZones, and ReplicaCount properties for each NodeGroupConfiguration as well. Again, you can use the ElastiCache console (https://console.aws.amazon.com/elasticache/) or DescribeReplicationGroups to retrieve the actual values for each node group and compare them to the values
in your stack template. You can update the property values of the node groups as a
separate stack update, or as part of the same stack update that changes the number
of node groups.

When you use an UseOnlineResharding update policy to update the number
of node groups without interruption, ElastiCache evenly distributes the keyspaces
between the specified number of slots. This cannot be updated later. Therefore, after
updating the number of node groups in this way, you should remove the value specified
for the Slots property of each NodeGroupConfiguration from the stack template, as it no longer reflects the actual values in each node
group.

Actual node group removal results may vary

When you specify a NumNodeGroups value that is less than the current
number of node groups, CloudFormation instructs ElastiCache to remove as many node
groups as
necessary to reach the specified number of nodes. However, ElastiCache may not always
be able to
remove the desired number of node groups. In the event ElastiCache cannot remove the
desired
number of node groups, CloudFormation generates a stack event alerting you to this.
In
cases where ElastiCache cannot remove any node groups, the CloudFormation
resource update fails.

Syntax

JSON

YAML

Examples

The following examples show how to add an update policy to an Auto Scaling group and
how to
maintain availability when updating metadata.

Add an UpdatePolicy to an Auto Scaling Group

The following example shows how to add an update policy. During an update, the Auto
Scaling
group updates instances in batches of two and keeps a minimum of one instance in service.
Because the WaitOnResourceSignals flag is set, the Auto Scaling group waits for new
instances that are added to the group. The new instances must signal the Auto Scaling
group before
it updates the next batch of instances.

AutoScalingReplacingUpdate Policy

The following example declares a policy that forces an associated Auto Scaling group
to be replaced during an update. For the update to succeed, a percentage of instances
(specified by the MinSuccessfulPercentParameter parameter) must signal success within the Timeout period.

Maintain Availability When Updating the Metadata for the cfn-init Helper
Script

When you install software applications on your instances, you might use the AWS::CloudFormation::Init
metadata key and the cfn-init helper script to bootstrap the instances in your
Auto Scaling group. AWS CloudFormation installs the packages, runs the commands, and
performs other bootstrapping
actions described in the metadata.

When you update only the metadata (for example, when updating a package to another
version), you can use the cfn-hup helper daemon to detect and apply the updates. However, the
cfn-hup daemon runs independently on each instance. If the daemon
happens to runs at the same time on all instances, your application or service might
be
unavailable during the update. To guarantee availability, you can force a rolling
update so
that AWS CloudFormation updates your instances one batch at a time.

Important

Forcing a rolling update requires AWS CloudFormation to create a new instance and
then delete the old one. Any information stored on the old instance is lost.

To force a rolling update, change the logical ID of the launch configuration resource,
and then update the stack and any references pointing to the original logic ID (such
as the associated Auto Scaling group). AWS CloudFormation triggers a rolling update
on the Auto Scaling group, replacing all instances.

Updated Logical ID

Lambda Alias Update Policy

The following example specifies the UpdatePolicy attribute for an AWS::Lambda::Alias resource.
All the details for the deployment are defined by the application and deployment
group that are passed into the policy.