StartInstanceRefresh - Auto Scaling - Alibaba Cloud Documentation Center

Refreshes instances in a scaling group when you need to apply a new scaling configuration or update the image of instances in the scaling group.

Operation description

A scaling group can have only one instance refresh task running at a time.
Currently, this feature is supported only for ECS scaling groups whose scale-out policy is set to Priority Policy. Scaling groups that use vCPU-based Capacity Calculation and scaling groups whose instance reclaim mode is set to Shutdown and Reclaim Mode or Forced Shutdown and Reclaim Mode do not support this feature.
During an instance refresh, normal scale-out and scale-in operations can be performed. However, scale-out operations use the desired configuration specified in the instance refresh task.
Instances that are manually added to the scaling group, instances in the standby state, and instances in the protected state are ignored by the instance refresh task and do not participate in the instance refresh.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

ess:StartInstanceRefresh

update

*ScalingGroup

acs:ess:{#regionId}:{#accountId}:scalinggroup/{#ScalingGroupId}

None

Request parameters

Parameter	Type	Required	Description	Example
RegionId	string	Yes	The region ID of the scaling group.	cn-hangzhou
ClientToken	string	No	The client token that is used to ensure the idempotence of the request. You can use the client to generate the token, but you must make sure that the token is unique among different requests. The token can contain only ASCII characters and cannot exceed 64 characters in length. For more information, see How to ensure idempotence.	123e4567-e89b-12d3-a456-42665544****
ScalingGroupId	string	Yes	The ID of the scaling group.	asg-bp18p2yfxow2dloq****
MinHealthyPercentage	integer	No	The minimum percentage of instances that must remain in service in the scaling group during the instance refresh. Valid values: 0 to 100. Default value: 80.	80
MaxHealthyPercentage	integer	No	The maximum percentage by which the number of instances in the scaling group can exceed the scaling group capacity during the instance refresh. Valid values: 100 to 200. Default value: 120. Note If you set both MinHealthyPercentage and MaxHealthyPercentage to 100, one instance is refreshed at a time.	100
DesiredConfiguration	object	No	The desired configuration for the instance refresh. Note You cannot specify ScalingConfigurationId, ImageId, LaunchTemplateId, and Containers at the same time. You must specify one of them. The refresh task skips instances in the scaling group that already match the desired configuration.
ImageId	string	No	The image ID. Note After the instance refresh task is completed, the image configuration in the active configuration of the scaling group is updated to this image. This parameter is not supported when the instance configuration source of the scaling group is a launch template. Images that contain data cloud disks are not supported.	m-2ze8cqacj7opnf***
ScalingConfigurationId	string	No	The ID of the scaling configuration. Note After the instance refresh task is completed, the active scaling configuration of the scaling group is updated to this configuration.	asc-2zed7lqn4ts4****
LaunchTemplateId	string	No	The ID of the launch template. This parameter specifies that the scaling group obtains launch configuration information from the launch template.	lt-2ze2qli30u***
LaunchTemplateVersion	string	No	The version of the launch template. Valid values: A fixed template version number. Default: always uses the default template version. Latest: always uses the latest template version. Note If the version is set to Default or Latest, the instance refresh task does not support rollback.	8
LaunchTemplateOverrides	array<object>	No	The instance type information that extends the launch template.
	object	No	The instance type information that extends the launch template.
InstanceType	string	No	The instance type that overrides the instance type specified in the launch template.	ecs.g7.2xlarge
Containers	array<object>	No	The list of containers included in the instance.
	array<object>	No	The list of containers included in the instance.
Name	string	No	The custom container name.	nginx
Image	string	No	The container image.	registry-vpc.cn-hangzhou.aliyuncs.com/eci_open/nginx:latest
Commands	array	No	The container startup commands. A maximum of 20 commands are supported. Each command can contain up to 256 characters.
	string	No	The container startup command. The command can contain up to 256 characters.	sleep
Args	array	No	The arguments for the container startup command. A maximum of 10 arguments are supported.
	string	No	The argument for the container startup command.	100
EnvironmentVars	array<object>	No	The environment variable information.
	object	No	The environment variable information.
Key	string	No	The name of the environment variable. The name must be 1 to 128 characters in length and can contain digits, letters, and underscores (_). It cannot start with a digit.	PATH
Value	string	No	The value of the environment variable. The value can be 0 to 256 characters in length.	/usr/local/bin
FieldRefFieldPath	string	No	Note This parameter is not publicly available.	fieldPath
SkipMatching	boolean	No	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, not by comparing specific configuration items. Valid values: true: Skips matching instances. When the instance refresh task starts, the system checks the configuration of each instance. Instances that were already created with the desired configuration are not refreshed. false: Does not skip matching instances. After the instance refresh task starts, all instances in the scaling group are refreshed. Default value: true.	true
Checkpoints	array<object>	No	The checkpoints for the refresh task. Specifies that the task is automatically paused for the duration specified by CheckpointPauseTime when the percentage of new instances reaches the specified value during the instance refresh.
	object	No	The checkpoints for the refresh task. Specifies that the task is automatically paused for the duration specified by CheckpointPauseTime when the percentage of new instances reaches the specified value during the instance refresh.
Percentage	integer	No	The percentage of new instances to total instances in the scaling group. The task is automatically paused when this percentage is reached. Valid values: 1 to 100 (%). Note The values must be specified in ascending order, and the last percentage value must be 100.	20
CheckpointPauseTime	integer	No	The pause duration when a refresh task checkpoint is reached. Unit: minutes. Valid values: 1 to 2880. Default value: 60.	10
Strategy	string	No	The execution strategy for the instance refresh task. Valid values: Rolling: The instance refresh task creates new instances and releases old instances to refresh instances. ReplaceSystemDisk: Updates the system cloud disk on existing instances by specifying DesiredConfiguration.image to replace the system cloud disk of instances. Default value: Rolling.	Rolling

Response elements

Element	Type	Description	Example
	object
RequestId	string	The request ID.	473469C7-AA6F-4DC5-B3DB-A3DC0DE3****
InstanceRefreshTaskId	string	The ID of the instance refresh task.	ir-a12ds234fasd*****

Examples

Success response

JSON format

{
  "RequestId": "473469C7-AA6F-4DC5-B3DB-A3DC0DE3****",
  "InstanceRefreshTaskId": "ir-a12ds234fasd*****"
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.