Menu
AWS CloudFormation
User Guide (API Version 2010-05-15)

UpdatePolicy Attribute

You can use the UpdatePolicy attribute to specify how AWS CloudFormation handles updates to the AWS::AutoScaling::AutoScalingGroup resource.

The update policy is invoked under the following conditions:

  • The AutoScalingRollingUpdate policy is applied when you make a change to the Auto Scaling placement group, launch configuration, or subnet group membership of the Auto Scaling group.

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

Syntax

"UpdatePolicy" : {
  "AutoScalingRollingUpdate" : {
    "MaxBatchSize" : Integer,
    "MinInstancesInService" : Integer,
    "MinSuccessfulInstancesPercent" : Integer
    "PauseTime" : String,
    "SuspendProcesses" : [ List of processes ],
    "WaitOnResourceSignals" : Boolean
  },
  "AutoScalingScheduledAction" : {
    "IgnoreUnmodifiedGroupSizeProperties" : Boolean
  }
}

AutoScalingRollingUpdate Properties

You can use the AutoScalingRollingUpdate policy to specify how AWS CloudFormation handles rolling updates for a particular resource.

Important

If you have an Auto Scaling group with rolling updates and scheduled actions enabled, you must suspend scheduled actions before you can update the group. Use the SuspendProcesses property to suspend scheduled actions during a rolling update.

MaxBatchSize

The maximum number of instances that are terminated at a given time.

Default: 1

Type: Integer

Required: No

MinInstancesInService

The minimum number of instances that must be in service within the Auto Scaling group while obsolete instances are being terminated.

Default: 0

Type: Integer

Required: No

MinSuccessfulInstancesPercent

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 specified pause time, AWS CloudFormation assumes the instance did not successfully update.

If you specify this property, you must enable the WaitOnResourceSignals property.

Default: 100

Type: Integer

Required: No

PauseTime

The amount of time to pause after AWS CloudFormation makes a change to a batch of instances, such as when you scale up the number of instances in an Auto Scaling group. Use the pause time to give your instances time to bootstrap software applications.

If you enable the WaitOnResourceSignals property, the amount of time to wait until the Auto Scaling group receives the required number of valid signals from added or replaced instances. If the pause time is exceeded before the Auto Scaling group receives the required number of signals, the update times out and fails. For best results, specify a period of time that gives your instances plenty of time to get up and running. In the event of a rollback, a shorter pause time can cause update rollback failures.

The value must be in ISO8601 duration format, in the form: "PT#H#M#S", where each # is the number of hours, minutes, and/or seconds, respectively. The maximum amount of time that can be specified for the pause time 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

The Auto Scaling processes to suspend during a stack update. Suspending processes is useful when you don't want Auto Scaling to potentially interfere with a stack update. For example, you can suspend alarming so that Auto Scaling doesn't execute scaling policies that are associated with an alarm. For valid values, see the ScalingProcesses.member.N parameter for the SuspendProcesses action in the Auto Scaling API Reference.

Default: Not specified

Type: List of Auto Scaling processes

Required: No

WaitOnResourceSignals

Indicates whether the Auto Scaling group waits on signals during an update. AWS CloudFormation suspends the update of an Auto Scaling group after any new Amazon EC2 instances are launched into the group. AWS CloudFormation must receive a signal from each new instance within the specified pause time before AWS CloudFormation continues the update. You can use the cfn-signal helper script or SignalResource API to signal the Auto Scaling group. This property is useful when you want to ensure instances have completed installing and configuring applications before the Auto Scaling group update proceeds.

Default: false

Type: Boolean

Required: Conditional. If you specify the MinSuccessfulInstancesPercent property, you must enable this property.

AutoScalingScheduledAction Properties

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

With scheduled actions, the group size properties (minimum size, maximum size, and desired capacity) of an Auto Scaling group can change at any time. Whenever you update a stack with an Auto Scaling group and scheduled action, AWS CloudFormation always sets 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. However, you might not want AWS CloudFormation to change any of the group size property values, such as when you have a scheduled action in effect. You can use the AutoScalingScheduledAction update policy to prevent AWS CloudFormation from changing the min size, max size, or desired capacity unless you modified the individual values in your template.

IgnoreUnmodifiedGroupSizeProperties

During a stack update, indicates whether AWS CloudFormation ignores any group size property differences between your current Auto Scaling group and the Auto Scaling group that is described in the AWS::AutoScaling::AutoScalingGroup resource of your template. However, if you modified any group size property values in your template, AWS CloudFormation will always use the modified values and update your Auto Scaling group.

Default: false

Type: Boolean

Required: No.

Examples

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 will update instances in batches of two and keep a minimum of one instance in service. With the WaitOnResourceSignals flag, 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 proceeds to update the next batch of instances.

"ASG" : {
   "Type" : "AWS :  : AutoScaling :  : AutoScalingGroup",
   "Properties" : {
      "AvailabilityZones" : [
         "us-east-1a",
         "us-east-1b"
      ],
      "DesiredCapacity" : "1",
      "LaunchConfigurationName" : {
         "Ref" : "LaunchConfig"
      },
      "MaxSize" : "4",
      "MinSize" : "1"
   },
   "UpdatePolicy" : {
      "AutoScalingScheduledAction" : {
         "IgnoreUnmodifiedGroupSizeProperties" : "true"
      },
      "AutoScalingRollingUpdate" : {
         "MinInstancesInService" : "1",
         "MaxBatchSize" : "2",
         "WaitOnResourceSignals" : "true",
         "PauseTime" : "PT10M"
      }
   }
 },
"ScheduledAction" : {
   "Type" : "AWS :  : AutoScaling :  : ScheduledAction",
   "Properties" : {
      "AutoScalingGroupName" : {
         "Ref" : "ASG"
      },
      "DesiredCapacity" : "2",
      "StartTime" : "2017-06-02T20 : 00 : 00Z"
   }
}

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

Typically, when you install software application on your instances, you might use the AWS::CloudFormation::Init metadata key and the cfn-init helper script to bootstrap instances in your Auto Scaling group. AWS CloudFormation installs the packages, runs the commands, and performs other bootstrapping actions that are described in the metdata. When you update only the metdata (for example, updating a package to another version), you might use the cfn-hup helper script to detect and apply those updates. However, the cfn-hup daemon runs independently on each instance. If, by chance, the daemon runs at the same time on all instances, your application or service might be unavailable during the update. If want to guarantee availability, you can force a rolling update so that your instances are updated one batch at a time.

Note

Forcing a rolling update requires your instances to be replaced, meaning AWS CloudFormation will create a new instance and then delete the old one. Any information stored on the old instance will be lost.

To force a rolling update, change the logical ID of the launch configuration resource, and then update the stack. You'll also need to update any references pointing to the original logic ID, such as the associated Auto Scaling group. AWS CloudFormation will trigger a rolling update on the Auto Scaling group, replacing all instances.

Original Template

"LaunchConfig": {
  "Type" : "AWS::AutoScaling::LaunchConfiguration",
  "Metadata" : {
    "Comment" : "Install a simple PHP application",
    "AWS::CloudFormation::Init" : {
    ...
    }
  }
}

Updated Logical ID

"LaunchConfigUpdateRubygemsPkg": {
  "Type" : "AWS::AutoScaling::LaunchConfiguration",
  "Metadata" : {
    "Comment" : "Install a simple PHP application",
    "AWS::CloudFormation::Init" : {
    ...
    }
  }
}