StartInstanceRefresh
Starts a new instance refresh operation, which triggers a rolling replacement of all previously launched instances in the Auto Scaling group with a new group of instances.
If successful, this call creates a new instance refresh request with a unique ID that you can use to track its progress. To query its status, call the DescribeInstanceRefreshes API. To describe the instance refreshes that have already run, call the DescribeInstanceRefreshes API. To cancel an instance refresh operation in progress, use the CancelInstanceRefresh API.
For more information, see Replacing Auto Scaling Instances Based on an Instance Refresh.
Request Parameters
For information about the parameters that are common to all actions, see Common Parameters.
- AutoScalingGroupName
-
The name of the Auto Scaling group.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 255.
Pattern:
[\u0020-\uD7FF\uE000-\uFFFD\uD800\uDC00-\uDBFF\uDFFF\r\n\t]*
Required: Yes
- Preferences
-
Set of preferences associated with the instance refresh request.
If not provided, the default values are used. For
MinHealthyPercentage
, the default value is90
. ForInstanceWarmup
, the default is to use the value specified for the health check grace period for the Auto Scaling group.Type: RefreshPreferences object
Required: No
- Strategy
-
The strategy to use for the instance refresh. The only valid value is
Rolling
.A rolling update is an update that is applied to all instances in an Auto Scaling group until all instances have been updated. A rolling update can fail due to failed health checks or if instances are on standby or are protected from scale in. If the rolling update process fails, any instances that were already replaced are not rolled back to their previous configuration.
Type: String
Valid Values:
Rolling
Required: No
Response Elements
The following element is returned by the service.
- InstanceRefreshId
-
A unique ID for tracking the progress of the request.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 255.
Pattern:
[\u0020-\uD7FF\uE000-\uFFFD\uD800\uDC00-\uDBFF\uDFFF\r\n\t]*
Errors
For information about the errors that are common to all actions, see Common Errors.
- InstanceRefreshInProgress
-
The request failed because an active instance refresh operation already exists for the specified Auto Scaling group.
HTTP Status Code: 400
- LimitExceeded
-
You have already reached a limit for your Amazon EC2 Auto Scaling resources (for example, Auto Scaling groups, launch configurations, or lifecycle hooks). For more information, see DescribeAccountLimits.
HTTP Status Code: 400
- ResourceContention
-
You already have a pending update to an Amazon EC2 Auto Scaling resource (for example, an Auto Scaling group, instance, or load balancer).
HTTP Status Code: 500
Examples
Example
This example illustrates one usage of StartInstanceRefresh.
Sample Request
https://autoscaling.amazonaws.com/?Action=StartInstanceRefresh
&AutoScalingGroupName=my-asg
&Preferences.InstanceWarmup=400
&Preferences.MinHealthyPercentage=50
&Version=2011-01-01
&AUTHPARAMS
Sample Response
<StartInstanceRefreshResponse xmlns="http://autoscaling.amazonaws.com/doc/2011-01-01/">
<StartInstanceRefreshResult>
<InstanceRefreshId>ccfd3c2f-edb3-470d-af32-52cc57d201ca</InstanceRefreshId>
</StartInstanceRefreshResult>
<ResponseMetadata>
<RequestId>a9bbb1dd-ba59-4753-80a2-c662036187eb</RequestId>
</ResponseMetadata>
</StartInstanceRefreshResponse>
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following: