Request Parameters Response Elements Errors Examples See Also

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 is 90. For InstanceWarmup, 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>