💾 Archived View for cfdocs.wetterberg.nu › aws-attribute-updatepolicy.gemini captured on 2024-05-12 at 16:01:06. Gemini links have been rewritten to link to archived content
⬅️ Previous capture (2021-12-03)
-=-=-=-=-=-=-
Use the `UpdatePolicy` attribute to specify how AWS CloudFormation handles updates to the https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-as-group.html, https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-elasticache-replicationgroup, https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-elasticsearch-domain.html, or https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-alias.html resources.
https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-as-group.html
https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-alias.html
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.
Before attempting an update, ensure that you have sufficient Amazon EC2 capacity for both your old and new Auto Scaling groups.
"UpdatePolicy" : {
"AutoScalingReplacingUpdate" : {
"WillReplace" : Boolean
}
}
UpdatePolicy:
AutoScalingReplacingUpdate:
WillReplace: Boolean
`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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-attribute-creationpolicy.html)`. 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.
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.
During a rolling update, some Auto Scaling processes might make changes to the Auto Scaling group before AWS CloudFormation completes the rolling update. These changes might cause the rolling update to fail. To prevent Auto Scaling from running processes during a rolling update, use the `SuspendProcesses` property. For more information, see What are some recommended best practices for performing Auto Scaling group rolling updates?
What are some recommended best practices for performing Auto Scaling group rolling updates?
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.
"UpdatePolicy" : {
"AutoScalingRollingUpdate" : {
"MaxBatchSize" : Integer,
"MinInstancesInService" : Integer,
"MinSuccessfulInstancesPercent" : Integer,
"PauseTime" : String,
"SuspendProcesses" : [ List of processes ],
"WaitOnResourceSignals" : Boolean
}
}
UpdatePolicy:
AutoScalingRollingUpdate:
MaxBatchSize: Integer
MinInstancesInService: Integer
MinSuccessfulInstancesPercent: Integer
PauseTime: String
SuspendProcesses:
- List of processes
WaitOnResourceSignals: Boolean
`MaxBatchSize`
Specifies the maximum number of instances that AWS CloudFormation updates.
`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.
`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.
AWS::AutoScaling::AutoScalingGroup
`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`).
`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*.
`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 https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_SignalResource.html 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.
https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_SignalResource.html
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 and set `IgnoreUnmodifiedGroupSizeProperties` to `true` to prevent AWS CloudFormation from changing the `MinSize`, `MaxSize`, or `DesiredCapacity` properties unless you have modified these values in your template.
"UpdatePolicy" : {
"AutoScalingScheduledAction" : {
"IgnoreUnmodifiedGroupSizeProperties" : Boolean
}
}
UpdatePolicy:
AutoScalingScheduledAction:
IgnoreUnmodifiedGroupSizeProperties: Boolean
`IgnoreUnmodifiedGroupSizeProperties`
If `true`, 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.
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.
AWS::ElastiCache::ReplicationGroup
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`:
https://console.aws.amazon.com/elasticache/
https://console.aws.amazon.com/elasticache/
For more information on modifying replication groups, see ModifyReplicationGroupShardConfiguration in the *Amazon ElastiCache API Reference*.
ModifyReplicationGroupShardConfiguration
"UpdatePolicy" : {
"UseOnlineResharding" : Boolean
}
UpdatePolicy: UseOnlineResharding: Boolean
To upgrade an Amazon ES domain to a new version of Elasticsearch rather than replacing the entire AWS::Elasticsearch::Domain resource, use the `EnableVersionUpgrade` update policy.
If `EnableVersionUpgrade` is set to `true`, you can update the `ElasticsearchVersion` property of the `AWS::Elasticsearch::Domain` resource, and CloudFormation will update that property without interruption. When `EnableVersionUpgrade` is set to `false`, or not specified, updating the `ElasticsearchVersion` property results in CloudFormation replacing the entire `AWS::Elasticsearch::Domain` resource.
The `EnableVersionUpgrade` update policy has no properties.
For more information about upgrading Amazon ES domains, see UpgradeElasticsearchDomain in the Amazon Elasticsearch Service Developer Guide.
"UpdatePolicy" : {
"EnableVersionUpgrade" : Boolean
}
UpdatePolicy: EnableVersionUpgrade: Boolean
To perform an CodeDeploy deployment when the version changes on an `AWS::Lambda::Alias` resource, use the `CodeDeployLambdaAliasUpdate` update policy.
"UpdatePolicy" : {
"CodeDeployLambdaAliasUpdate" : {
"AfterAllowTrafficHook" : String,
"ApplicationName" : String,
"BeforeAllowTrafficHook" : String,
"DeploymentGroupName" : String
}
}
UpdatePolicy:
CodeDeployLambdaAliasUpdate:
AfterAllowTrafficHook: String
ApplicationName: String
BeforeAllowTrafficHook: String
DeploymentGroupName: String
`AfterAllowTrafficHook`
The name of the Lambda function to run after traffic routing completes.
`ApplicationName`
The name of the CodeDeploy application.
`BeforeAllowTrafficHook`
The name of the Lambda function to run before traffic routing starts.
`DeploymentGroupName`
The name of the CodeDeploy deployment group. This is where the traffic-shifting policy is set.
For an example that specifies the `UpdatePolicy` attribute for an `AWS::Lambda::Alias` resource, see Lambda alias update policy.
The following examples show how to add an update policy to an Auto Scaling group and how to maintain availability when updating metadata.
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.
"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"
}
}
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'
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.
"UpdatePolicy" : {
"AutoScalingReplacingUpdate" : {
"WillReplace" : "true"
}
},
"CreationPolicy" : {
"ResourceSignal" : {
"Count" : { "Ref" : "ResourceSignalsOnCreate"},
"Timeout" : "PT10M"
},
"AutoScalingCreationPolicy" : {
"MinSuccessfulInstancesPercent" : { "Ref" : "MinSuccessfulPercentParameter" }
}
}
UpdatePolicy:
AutoScalingReplacingUpdate:
WillReplace: 'true'
CreationPolicy:
ResourceSignal:
Count: !Ref 'ResourceSignalsOnCreate'
Timeout: PT10M
AutoScalingCreationPolicy:
MinSuccessfulInstancesPercent: !Ref 'MinSuccessfulPercentParameter'
When you install software applications on your instances, you might use the https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-init.html metadata key and the https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-init.html 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.
https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-init.html
https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-init.html
When you update only the metadata (for example, when updating a package to another version), you can use the `[cfn\-hup](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-hup.html)` 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.
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.
"LaunchConfig": {
"Type" : "AWS::AutoScaling::LaunchConfiguration",
"Metadata" : {
"Comment" : "Install a simple PHP application",
"AWS::CloudFormation::Init" : {
...
}
}
}
"LaunchConfigUpdateRubygemsPkg": {
"Type" : "AWS::AutoScaling::LaunchConfiguration",
"Metadata" : {
"Comment" : "Install a simple PHP application",
"AWS::CloudFormation::Init" : {
...
}
}
}
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.
"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"
}
}
}
}
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