You can call this operation to refresh instances in a scaling group. This operation applies a new scaling configuration or updates the image for the instances.
Description
A scaling group can have only one running instance refresh task at a time.
This feature is available only for Elastic Compute Service (ECS) scaling groups that use the Priority scale-out policy. This feature is not supported for scaling groups that calculate their capacity based on the number of vCPUs, or for scaling groups whose instance reclaim mode is set to Stop-billing or Force Stop-billing.
During an instance refresh, normal scale-out and scale-in activities can proceed. However, scale-out activities will use the desired configuration of the instance refresh.
Instances that are manually added to the scaling group, or are in the standby or protection state, are ignored by the instance refresh task and are not refreshed.
Test
Request parameters
Parameter | Type | Required | Example | Description |
Action | String | Yes | StartInstanceRefresh | A required parameter. Set the value to StartInstanceRefresh. |
RegionId | String | Yes | cn-hangzhou | The ID of the region where the scaling group is located. |
ClientToken | String | No | 123e4567-e89b-12d3-a456-42665544**** | Ensures the idempotence of the request. Generate a parameter value from your client to make sure that the value is unique among different requests. This parameter supports only ASCII characters and cannot exceed 64 characters in length. For more information, see How to ensure idempotence. |
ScalingGroupId | String | Yes | asg-bp18p2yfxow2dloq**** | The ID of the scaling group. |
MinHealthyPercentage | Integer | No | 80 | The percentage of instances that must be in the Normal state out of the total capacity of the scaling group during an instance refresh. Valid values: 0 to 100. Default value: 80. |
MaxHealthyPercentage | Integer | No | 100 | The percentage of instances that can exceed the total capacity of the scaling group during an instance refresh. Valid values: 100 to 200. Default value: 120. Note If MinHealthyPercentage and MaxHealthyPercentage are both set to 100, one instance is refreshed at a time. |
DesiredConfiguration.ImageId | String | No | m-2ze8cqacj7opnf*** | The ID of the image. Note
|
DesiredConfiguration.ScalingConfigurationId | String | No | asc-2zed7lqn4ts4**** | The ID of the scaling configuration. Note After the instance refresh task is complete, the active scaling configuration of the scaling group is updated to this configuration. |
DesiredConfiguration.LaunchTemplateId | String | No | lt-2ze2qli30u*** | The ID of the launch template. The scaling group uses this template to obtain launch configuration information. |
DesiredConfiguration.LaunchTemplateVersion | String | No | 8 | The version of the launch template. Valid values:
Note If you set the version to Default or Latest, you cannot roll back the instance refresh task. |
DesiredConfiguration.LaunchTemplateOverrides.N.InstanceType | String | No | ecs.g7.2xlarge | The instance type. This parameter overwrites the instance type specified in the launch template. |
DesiredConfiguration.Containers.N.Name | String | No | nginx | The name of the custom container. |
DesiredConfiguration.Containers.N.Image | String | No | registry-vpc.cn-hangzhou.aliyuncs.com/eci_open/nginx:latest | The container image. |
DesiredConfiguration.Containers.N.Commands.N | String | No | sleep | The container startup command. The command can be up to 256 characters in length. |
DesiredConfiguration.Containers.N.Args.N | String | No | 100 | The parameters for the container startup command. |
DesiredConfiguration.Containers.N.EnvironmentVars.N.Key | String | No | PATH | The name of the environment variable. The name must be 1 to 128 characters in length. It can contain digits, letters, and underscores (_). It cannot start with a digit. |
DesiredConfiguration.Containers.N.EnvironmentVars.N.Value | String | No | /usr/local/bin | The value of the environment variable. The value can be 0 to 256 characters in length. |
DesiredConfiguration.Containers.N.EnvironmentVars.N.FieldRefFieldPath | String | No | fieldPath | Note This parameter is not available. |
SkipMatching | Boolean | No | true | Specifies whether to skip instances that match the desired configuration. Note The system determines whether an instance matches based on the ID of the desired scaling configuration. The system does not compare specific configuration items. Valid values:
Default value: true. |
Checkpoints.N.Percentage | Integer | No | 20 | The percentage of new instances in the scaling group. When this percentage is reached, the task is automatically paused. Valid values: 1 to 100 (%). Note You must set the percentages in ascending order. The last percentage must be 100. |
CheckpointPauseTime | Integer | No | 10 | The duration for which the task pauses at a checkpoint.
|
Response parameters
Parameter | Type | Example | Description |
RequestId | String | 473469C7-AA6F-4DC5-B3DB-A3DC0DE3**** | The ID of the request. |
InstanceRefreshTaskId | String | ir-a12ds234fasd***** | The ID of the instance refresh task. |
Examples
Request example
http(s)://ess.aliyuncs.com/?Action=StartInstanceRefresh
&RegionId=cn-hangzhou
&ClientToken=123e4567-e89b-12d3-a456-42665544****
&ScalingGroupId=asg-bp18p2yfxow2dloq****
&MinHealthyPercentage=80
&MaxHealthyPercentage=100
&DesiredConfiguration={"ImageId":"m-2ze8cqacj7opnf***","ScalingConfigurationId":"asc-2zed7lqn4ts4****"}
&<Common request parameters>Response example
XML format
HTTP/1.1 200 OK
Content-Type:application/xml
<StartInstanceRefreshResponse>
<RequestId>473469C7-AA6F-4DC5-B3DB-A3DC0DE3****</RequestId>
<InstanceRefreshTaskId>ir-a12ds234fasd*****</InstanceRefreshTaskId>
</StartInstanceRefreshResponse>JSON format
HTTP/1.1 200 OK
Content-Type:application/json
{
"RequestId" : "473469C7-AA6F-4DC5-B3DB-A3DC0DE3****",
"InstanceRefreshTaskId" : "ir-a12ds234fasd*****"
}Error codes
For more information about error codes, see the Error Center.