UpdatePolicy attribute - AWS CloudFormation (original) (raw)

Use the UpdatePolicy attribute to specify how AWS CloudFormation handles updates to certain resources during stack update operations.

Topics

Overview

By using the UpdatePolicy attribute, you can control how the following resources are updated, as described here:

The sections that follow describe the syntax and properties for theUpdatePolicy attribute supported by each resource type.

AppStream 2.0 update policy

To stop an AppStream 2.0 fleet before an update and restart it after an update, use the AppStream 2.0 update policy.

Syntax

JSON

{
    "UpdatePolicy": {
        "StopBeforeUpdate": {
            "Type": "Boolean"
        },
        "StartAfterUpdate": {
            "Type": "Boolean"
        }
    }
}

YAML

UpdatePolicy:
  StopBeforeUpdate:
    Type: Boolean
  StartAfterUpdate:
    Type: Boolean

StopBeforeUpdate

Stops the specified fleet before the update.

Required: No

StartAfterUpdate

Starts the specified fleet after the update.

Required: No

AutoScalingReplacingUpdate policy

To replace the Auto Scaling group and the instances it contains, use theAutoScalingReplacingUpdate policy.

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

Syntax

JSON

"UpdatePolicy" : {
  "AutoScalingReplacingUpdate" : {
    "WillReplace" : Boolean
  }
}

YAML

UpdatePolicy:
  AutoScalingReplacingUpdate:
    WillReplace: Boolean

Properties

WillReplace

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

While CloudFormation creates the new group, it doesn't detach or attach any instances. After successfully creating the new Auto Scaling group, 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 theCreationPolicy policy), the replacement update fails and CloudFormation rolls back to the old Auto Scaling group.

Type: Boolean

Required: No

AutoScalingRollingUpdate policy

To perform a rolling update of the instances in an Auto Scaling group rather than wait for scaling activities to gradually replace older instances with newer instances, use theAutoScalingRollingUpdate policy. This policy provides you the flexibility to specify whether CloudFormation replaces instances that are in an Auto Scaling group in batches or all at once without replacing the entire resource.

Things to consider when using an AutoScalingRollingUpdate policy:

Syntax

JSON

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

YAML

UpdatePolicy:
  AutoScalingRollingUpdate:
    MaxBatchSize: Integer
    MinActiveInstancesPercent: Integer
    MinInstancesInService: Integer
    MinSuccessfulInstancesPercent: Integer
    PauseTime: String
    SuspendProcesses:
      - List of processes
    WaitOnResourceSignals: Boolean

Properties

MaxBatchSize

Specifies the maximum number of instances that can be replaced simultaneously.

Default: 1

Maximum: 100

Type: Integer

Required: No

MinActiveInstancesPercent

Specifies the percentage of instances in an Auto Scaling group that must be in theInService state relative to that group's desired capacity during a rolling update for an update to succeed. You can specify a value from 0 to 100. CloudFormation rounds to the nearest tenth of a percent. For example, if you update five instances with a minimum InService percentage of 50, at least three instances must be in the InService state. If an instance doesn't transition to the InService state within a fixed time of 1 hour, CloudFormation assumes that the instance wasn't updated.

Setting MinActiveInstancesPercent in your UpdatePolicy will also affect instances launched when the DesiredCapacity property of the AWS::AutoScaling::AutoScalingGroup resource is set higher than the current desired capacity of that Auto Scaling group.

Default: 100

Type: Integer

Required: No

MinInstancesInService

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

Warning

We recommend that you set the value of the MinInstancesInService property to at least the MinSize of the Auto Scaling group. This avoids potential availability issues during a rolling update due to 0 instances serving customer traffic.

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. 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 thePauseTime property, CloudFormation assumes that the instance wasn't updated.

We recommend that you set the value of theMinSuccessfulInstancesPercent property to a value greater than 0. When the MinSuccessfulInstancesPercent property is set to 0, CloudFormation waits for 0% of the capacity instances to be in an InService state.MinSuccessfulInstancesPercent returns immediately and before considering the Auto Scaling group status as UPDATE_COMPLETE to move on to the subsequent resources defined in the stack template. If other Auto Scaling groups are defined in your CloudFormation template, they will update simultaneously. When all Auto Scaling groups are deployed at once with 0% of the capacity instances in an InService state, then you will experience availability issues, due to 0 instances serving customer traffic.

Default: 100

Type: Integer

Required: No

PauseTime

The amount of time that CloudFormation pauses after making a change to a batch of instances to give those instances time to start software applications.

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

Warning

When WaitOnResourceSignals is set to true,PauseTime acts as a timeout value. It determines the maximum time that CloudFormation waits to receive the required number of valid signals from the instances being replaced during a rolling update and from new instances being added by increasing the DesiredCapacity property of theAWS::AutoScaling::AutoScalingGroup resource. If thePauseTime is exceeded before CloudFormation receives the expected signals, the update fails. For best results, specify a time period that provides sufficient time for your applications to start up. If the update needs to be rolled back, a short PauseTime can cause the rollback to fail.

Default: PT5M (5 minutes) when theWaitOnResourceSignals property is set to true. Otherwise, no default value is set.

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 initiate scaling policies associated with an alarm. For valid values, see Types of processes in the Amazon EC2 Auto Scaling User Guide.

Default: Not specified

Type: List of Auto Scaling processes

Required: No

WaitOnResourceSignals

Specifies whether CloudFormation waits for success signals from new instances before continuing the update. CloudFormation waits for the specified PauseTime duration for success signals.

To signal the Auto Scaling group, use the cfn-signal helper script. For Auto Scaling groups associated with Elastic Load Balancing, consider adding a health check to ensure that instances are healthy before signaling success by using the cfn-init helper script. For an example, see the verify_instance_health command in the sample templates for Amazon EC2 Auto Scaling rolling updates in our GitHub repository.

Default: false

Type: Boolean

Required: Conditional. If you specify theMinSuccessfulInstancesPercent property, theWaitOnResourceSignals property must be set to true.

AutoScalingScheduledAction policy

To specify how CloudFormation handles updates for the MinSize,MaxSize, and DesiredCapacity properties when theAWS::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, CloudFormation always sets the group size property values of your Auto Scaling group to the values that are defined in theAWS::AutoScaling::AutoScalingGroup resource of your template, even if a scheduled action is in effect.

If you don't want CloudFormation to change any of the group size property values when you have a scheduled action in effect, use the AutoScalingScheduledAction update policy and set IgnoreUnmodifiedGroupSizeProperties to true to prevent CloudFormation from changing the MinSize, MaxSize, orDesiredCapacity properties unless you have modified these values in your template.

Syntax

JSON

"UpdatePolicy" : {
  "AutoScalingScheduledAction" : {
    "IgnoreUnmodifiedGroupSizeProperties" : Boolean
  }
}

Properties

IgnoreUnmodifiedGroupSizeProperties

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

Note

This property is ignored during a stack rollback.

Default: false

Type: Boolean

Required: No

UseOnlineResharding policy

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

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

The UseOnlineResharding update policy has no properties.

Things to consider when setting the UseOnlineResharding update policy totrue:

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 eachNodeGroupConfiguration 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 can't be updated later. Therefore, after updating the number of node groups in this way, you should remove the value specified for theSlots property of each NodeGroupConfiguration from the stack template, as it no longer reflects the actual values in each node group.

For more information on modifying replication groups, see ModifyReplicationGroupShardConfiguration in the_Amazon ElastiCache API Reference_.

Syntax

JSON

"UpdatePolicy" : {
  "UseOnlineResharding" : Boolean
}

YAML

UpdatePolicy:
  UseOnlineResharding: Boolean

EnableVersionUpgrade policy

To upgrade an OpenSearch Service domain to a new version of OpenSearch or Elasticsearch rather than replacing the entire AWS::OpenSearchService::Domain or AWS::Elasticsearch::Domain resource, use the EnableVersionUpgrade update policy.

If EnableVersionUpgrade is set to true, you can update theEngineVersion property of the AWS::OpenSearchService::Domain resource (or the ElasticsearchVersion property of the legacyAWS::Elasticsearch::Domain resource), and CloudFormation will update that property without interruption. When EnableVersionUpgrade is set to false, or not specified, updating the EngineVersion or ElasticsearchVersion property results in CloudFormation replacing the entireAWS::OpenSearchService::Domain/AWS::Elasticsearch::Domain resource.

The EnableVersionUpgrade update policy has no properties.

For more information, see Upgrading OpenSearch Service domains in the Amazon OpenSearch Service Developer Guide.

Syntax

JSON

"UpdatePolicy" : {
  "EnableVersionUpgrade" : Boolean
}

YAML

UpdatePolicy:
  EnableVersionUpgrade: Boolean

CodeDeployLambdaAliasUpdate policy

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

Syntax

JSON

"UpdatePolicy" : {
  "CodeDeployLambdaAliasUpdate" : {
    "AfterAllowTrafficHook" : String,
    "ApplicationName" : String,
    "BeforeAllowTrafficHook" : String,
    "DeploymentGroupName" : String
  }
}

YAML

UpdatePolicy:
  CodeDeployLambdaAliasUpdate:
    AfterAllowTrafficHook: String
    ApplicationName: String
    BeforeAllowTrafficHook: String
    DeploymentGroupName: String

Properties

AfterAllowTrafficHook

The name of the Lambda function to run after traffic routing completes.

Required: No

Type: String

ApplicationName

The name of the CodeDeploy application.

Required: Yes

Type: String

BeforeAllowTrafficHook

The name of the Lambda function to run before traffic routing starts.

Required: No

Type: String

DeploymentGroupName

The name of the CodeDeploy deployment group. This is where the traffic-shifting policy is set.

Required: Yes

Type: String

For an example that specifies the UpdatePolicy attribute for anAWS::Lambda::Alias resource, see Lambda alias update policy.

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.

JSON

"ASG" : {
  "Type":"AWS::AutoScaling::AutoScalingGroup",
  "Properties":{
    "VPCZoneIdentifier":[ "subnetIdAz1", "subnetIdAz2", "subnetIdAz3" ],
    "LaunchTemplate":{
      "LaunchTemplateId":{
        "Ref":"logicalName"
      },
      "Version":{
        "Fn::GetAtt":[
          "logicalName",
          "LatestVersionNumber"
        ]
      }
    },
    "MaxSize":"4",
    "MinSize":"1"
  },
  "UpdatePolicy":{
    "AutoScalingScheduledAction":{
      "IgnoreUnmodifiedGroupSizeProperties":"true"
    },
    "AutoScalingRollingUpdate":{
      "MinInstancesInService":"1",
      "MaxBatchSize":"2",
      "WaitOnResourceSignals":"true",
      "PauseTime":"PT10M",
      "SuspendProcesses":[
        "HealthCheck",
        "ReplaceUnhealthy",
        "AZRebalance",
        "AlarmNotification",
        "ScheduledActions",
        "InstanceRefresh"
      ]
    }
  }
}

YAML

ASG:
  Type: 'AWS::AutoScaling::AutoScalingGroup'
  Properties:
    VPCZoneIdentifier:
      - subnetIdAz1
      - subnetIdAz2
      - subnetIdAz3
    LaunchTemplate:
      LaunchTemplateId: !Ref logicalName
      Version: !GetAtt logicalName.LatestVersionNumber
    MaxSize: '4'
    MinSize: '1'
  UpdatePolicy:
    AutoScalingScheduledAction:
      IgnoreUnmodifiedGroupSizeProperties: 'true'
    AutoScalingRollingUpdate:
      MinInstancesInService: '1'
      MaxBatchSize: '2'
      WaitOnResourceSignals: 'true'
      PauseTime: PT10M
      SuspendProcesses:
        - HealthCheck
        - ReplaceUnhealthy
        - AZRebalance
        - AlarmNotification
        - ScheduledActions
        - InstanceRefresh

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 theTimeout period.

JSON

"UpdatePolicy" : {
  "AutoScalingReplacingUpdate" : {
    "WillReplace" : true
  }
},
"CreationPolicy" : {
  "ResourceSignal" : {
    "Count" : { "Ref" : "ResourceSignalsOnCreate"},
    "Timeout" : "PT10M"
  },
  "AutoScalingCreationPolicy" : {
    "MinSuccessfulInstancesPercent" : { "Ref" : "MinSuccessfulPercentParameter" }
  }
}

YAML

UpdatePolicy:
  AutoScalingReplacingUpdate:
    WillReplace: true
CreationPolicy:
  ResourceSignal:
    Count: !Ref 'ResourceSignalsOnCreate'
    Timeout: PT10M
  AutoScalingCreationPolicy:
    MinSuccessfulInstancesPercent: !Ref 'MinSuccessfulPercentParameter'

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. 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 CloudFormation updates your instances one batch at a time.

Important

Forcing a rolling update requires 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). CloudFormation triggers 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" : {
    ...
    }
  }
}

Lambda alias update policy

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

JSON

"Alias": {
  "Type": "AWS::Lambda::Alias",
  "Properties": {
    "FunctionName": {
      "Ref": "LambdaFunction"
    },
    "FunctionVersion": {
      "Fn::GetAtt": [
        "FunctionVersionTwo",
        "Version"
      ]
    },
    "Name": "MyAlias"
  },
  "UpdatePolicy": {
    "CodeDeployLambdaAliasUpdate": {
      "ApplicationName": {
        "Ref": "CodeDeployApplication"
      },
      "DeploymentGroupName": {
        "Ref": "CodeDeployDeploymentGroup"
      },
      "BeforeAllowTrafficHook": {
        "Ref": "PreHookLambdaFunction"
      },
      "AfterAllowTrafficHook": {
        "Ref": "PreHookLambdaFunction"
      }
    }
  }
}

YAML

Alias:
  Type: 'AWS::Lambda::Alias'
  Properties:
    FunctionName: !Ref LambdaFunction
    FunctionVersion: !GetAtt FunctionVersionTwo.Version
    Name: MyAlias
  UpdatePolicy:
    CodeDeployLambdaAliasUpdate:
      ApplicationName: !Ref CodeDeployApplication
      DeploymentGroupName: !Ref CodeDeployDeploymentGroup
      BeforeAllowTrafficHook: !Ref PreHookLambdaFunction
      AfterAllowTrafficHook: !Ref PreHookLambdaFunction