AWS AWSCloudFormation documentation change
Summary
Added comprehensive documentation for the new AutoScalingInstanceRefresh policy, including syntax, properties, considerations, and examples. Updated existing sections to reference the new policy and highlight limitations of AutoScalingRollingUpdate.
Security assessment
The change introduces documentation for AutoScalingInstanceRefresh which supports security features like instance maintenance policies, scale-in protection, and alarm-based rollback. However, there's no evidence of addressing a specific security vulnerability. The documentation enhances security awareness by explaining how to maintain security posture during updates.
Diff
diff --git a/AWSCloudFormation/latest/TemplateReference/aws-attribute-updatepolicy.md b/AWSCloudFormation/latest/TemplateReference/aws-attribute-updatepolicy.md index b95f1b052..0bec4292e 100644 --- a//AWSCloudFormation/latest/TemplateReference/aws-attribute-updatepolicy.md +++ b//AWSCloudFormation/latest/TemplateReference/aws-attribute-updatepolicy.md @@ -5 +5 @@ -OverviewWorkSpaces Applications update policyAutoScalingReplacingUpdate policyAutoScalingRollingUpdate policyAutoScalingScheduledAction policyUseOnlineResharding policyEnableVersionUpgrade policyCodeDeployLambdaAliasUpdate policyExamples +OverviewWorkSpaces Applications update policyAutoScalingReplacingUpdate policyAutoScalingRollingUpdate policyAutoScalingInstanceRefresh policyAutoScalingScheduledAction policyUseOnlineResharding policyEnableVersionUpgrade policyCodeDeployLambdaAliasUpdate policyExamples @@ -22,0 +23,2 @@ Use the `UpdatePolicy` attribute to specify how CloudFormation handles updates t + * AutoScalingInstanceRefresh policy + @@ -57,0 +60,2 @@ If both the `AutoScalingReplacingUpdate` and `AutoScalingRollingUpdate` policies + * `AutoScalingInstanceRefresh` policy – CloudFormation runs an Auto Scaling instance refresh when you change certain properties of the Auto Scaling group. Compared to `AutoScalingRollingUpdate`, this policy supports instance maintenance policies (including launch-before-terminate), termination policies, scale-in protection, root volume replacement, and additional Amazon EC2 Auto Scaling features. You can't specify both `AutoScalingInstanceRefresh` and `AutoScalingRollingUpdate` on the same Auto Scaling group. For more information, see the AutoScalingInstanceRefresh policy. + @@ -158,0 +163,4 @@ Things to consider when using an `AutoScalingRollingUpdate` policy: +###### Warning + +Rolling updates don't honor the instance maintenance policy configured on your Auto Scaling group. During a rolling update, healthy capacity can drop below the `MinHealthyPercentage` set on the group, and CloudFormation doesn't launch new instances before terminating existing ones, regardless of `MaxHealthyPercentage`. To preserve your instance maintenance policy during stack updates, use the AutoScalingInstanceRefresh policy instead. + @@ -162,0 +171,2 @@ Things to consider when using an `AutoScalingRollingUpdate` policy: +Alternatively, the `AutoScalingInstanceRefresh` policy supports all Auto Scaling group processes during stack updates, so you don't need to suspend them. If you need processes such as health checks and AZ rebalance to remain active, use `AutoScalingInstanceRefresh` instead. For more information, see the AutoScalingInstanceRefresh policy. + @@ -165 +175 @@ Things to consider when using an `AutoScalingRollingUpdate` policy: - * Amazon EC2 Auto Scaling features such as instance maintenance policies, termination policies, and scale-in protection are not available for use with CloudFormation rolling updates. Plan your rolling updates accordingly. + * Other Amazon EC2 Auto Scaling features such as termination policies and scale-in protection aren't available for use with CloudFormation rolling updates. If you need any of these features, use `AutoScalingInstanceRefresh` instead. For more information, see AutoScalingInstanceRefresh policy. @@ -299,0 +310,278 @@ _Required_ : Conditional. If you specify the `MinSuccessfulInstancesPercent` pro +## AutoScalingInstanceRefresh policy + +To update the instances in an Auto Scaling group by performing an Auto Scaling instance refresh, use the `AutoScalingInstanceRefresh` policy. For the full list of instance refresh capabilities, see [Use an instance refresh to update instances in an Auto Scaling group](https://docs.aws.amazon.com/autoscaling/ec2/userguide/asg-instance-refresh.html) in the _Amazon EC2 Auto Scaling User Guide_. + +CloudFormation performs an instance refresh only when you update one of the following properties of an `AWS::AutoScaling::AutoScalingGroup` resource: + + * `LaunchTemplate` + + * `MixedInstancesPolicy` + + * `VPCZoneIdentifier` + + * `AvailabilityZones` + + * `AvailabilityZoneIds` + + * `PlacementGroup` + + + + +When you use the `AutoScalingInstanceRefresh` policy, consider the following: + + * You can't specify both `AutoScalingInstanceRefresh` and `AutoScalingRollingUpdate` policies on the same Auto Scaling group. If you do, the stack update fails. + + * CloudFormation stack rollback is the rollback mechanism for `AutoScalingInstanceRefresh`. If an instance refresh fails, CloudFormation rolls back the stack and starts a new instance refresh to restore the group to its previous configuration. You can't use the Auto Scaling `RollbackInstanceRefresh` API operation on an instance refresh that CloudFormation has already started. To revert a refresh, use the `CancelInstanceRefresh` API or roll back the stack update. + + * An Auto Scaling group can run only one instance refresh at a time. If a user-initiated instance refresh is in progress when you start a stack update with the `AutoScalingInstanceRefresh` policy, the stack update may fail. + + * When you set the instance refresh `Strategy` to `ReplaceRootVolume`, only changes to `ImageId` within the launch template or mixed instances policy are allowed. Other property changes may cause the stack update to fail. For more information, see [Replace root volumes during instance refresh](https://docs.aws.amazon.com/autoscaling/ec2/userguide/replace-root-volume.html) in the _Amazon EC2 Auto Scaling User Guide_. + + * Each direction of the stack update (forward and rollback) is bounded by the CloudFormation resource timeout of 36 hours. + + * Long-running instance refreshes might exceed the lifetime of the temporary credentials CloudFormation uses to call Auto Scaling. To avoid this, configure a service role on the stack. For more information, see [CloudFormation service role](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-iam-servicerole.html). + + + + +###### Note + +Instance refresh doesn't support the [cfn-signal](./cfn-signal.html) helper script. For information about how to verify instance readiness during an instance refresh, see Verify instance readiness during an instance refresh. + +### Syntax + +#### JSON + + + "UpdatePolicy" : { + "AutoScalingInstanceRefresh" : { + "Strategy" : String, + "Preferences" : { + "AlarmSpecification" : { + "Alarms" : [ List of alarm names ] + }, + "BakeTime" : Integer, + "CheckpointDelay" : Integer, + "CheckpointPercentages" : [ List of integers ], + "InstanceWarmup" : Integer, + "MaxHealthyPercentage" : Integer, + "MinHealthyPercentage" : Integer, + "ScaleInProtectedInstances" : String, + "SkipMatching" : Boolean, + "StandbyInstances" : String + } + } + } + +#### YAML + + + UpdatePolicy: + AutoScalingInstanceRefresh: + Strategy: String + Preferences: + AlarmSpecification: + Alarms: + - List of alarm names + BakeTime: Integer + CheckpointDelay: Integer + CheckpointPercentages: + - List of integers + InstanceWarmup: Integer + MaxHealthyPercentage: Integer + MinHealthyPercentage: Integer + ScaleInProtectedInstances: String + SkipMatching: Boolean + StandbyInstances: String + +### Properties + +`Strategy` + + +The strategy to use for the instance refresh. Valid values are `Rolling` and `ReplaceRootVolume`. For information about the `ReplaceRootVolume` strategy, see [Replace root volumes during instance refresh](https://docs.aws.amazon.com/autoscaling/ec2/userguide/replace-root-volume.html) in the _Amazon EC2 Auto Scaling User Guide_. + +_Type_ : String + +_Required_ : Yes + +`Preferences` + + +Sets the preferences for the instance refresh. Includes the instance warmup time, the minimum and maximum healthy percentages, and the behaviors that Amazon EC2 Auto Scaling uses if instances are in `Standby` state or protected from scale in. You can also enable additional features: + + * Checkpoints + + * CloudWatch alarms + + * Skip matching + + * Bake time + + + + +_Type_ : Preferences + +_Required_ : No + +### Preferences + +`AlarmSpecification` + + +The CloudWatch alarm specification. You can use CloudWatch alarms to identify any issues during the instance refresh and roll back the stack if an alarm threshold is met. For more information, see [Start an instance refresh with auto rollback](https://docs.aws.amazon.com/autoscaling/ec2/userguide/instance-refresh-rollback.html#instance-refresh-using-auto-rollback) in the _Amazon EC2 Auto Scaling User Guide_. + +_Type_ : AlarmSpecification + +_Required_ : No + +`BakeTime` + + +The amount of time, in seconds, to wait at the end of an instance refresh before the instance refresh is considered complete. + +_Default_ : `0` + +_Minimum_ : `0` + +_Maximum_ : `172800` + +_Type_ : Integer + +_Required_ : No + +`CheckpointDelay` + + +The amount of time, in seconds, to wait after a checkpoint before continuing. If you specify a value for `CheckpointPercentages` but not for `CheckpointDelay`, the `CheckpointDelay` defaults to `3600` (1 hour). + +_Minimum_ : `0` + +_Maximum_ : `172800` + +_Type_ : Integer + +_Required_ : No + +`CheckpointPercentages` + + +Threshold values for each checkpoint in ascending order. Each number must be unique. To replace all instances in the Auto Scaling group, the last number in the array must be `100`. For usage examples, see [Add checkpoints to an instance refresh](https://docs.aws.amazon.com/autoscaling/ec2/userguide/asg-adding-checkpoints-instance-refresh.html) in the _Amazon EC2 Auto Scaling User Guide_. + +_Type_ : List of integers + +_Required_ : No + +`InstanceWarmup` + + +A time period, in seconds, during which an instance refresh waits before moving on to replacing the next instance after a new instance enters the `InService` state. + +If you don't specify `InstanceWarmup`, Auto Scaling uses the value for the `DefaultInstanceWarmup` property instead. We recommend that you set a value for `DefaultInstanceWarmup` in all use cases. + +If you don't specify a value for either property, Auto Scaling uses the value of the `HealthCheckGracePeriod` property.