Refresh ECS Instances with StartInstanceRefresh API - Auto Scaling - Alibaba Cloud - Auto Scaling

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

Only one instance refresh node can run in a scaling group at a time.
This feature supports only 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 revoke pattern is set to Shutdown and Revoke Pattern or Forced Shutdown and Revoke Pattern 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 of the instance refresh.
Instances that are manually added to the scaling group, instances in the standby state, and instances in the protection status are ignored by the instance refresh node 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
ScalingGroupId	string	Yes	The ID of the scaling group.	asg-bp18p2yfxow2dloq****
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****
RegionId	string	Yes	The region ID of the scaling group.	cn-hangzhou
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 When MinHealthyPercentage = MaxHealthyPercentage = 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. If this parameter is left empty, the currently active configuration of the scaling group is used for the refresh. After the instance refresh task is completed, the active scaling configuration of the scaling group is updated to this configuration.
ImageId	string	No	The image ID. Note After the instance refresh task is completed, the image in the currently 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.	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 version of the template. Latest: always uses the latest version of the template. Note Rollback is not supported for instance refresh tasks when the version is set to Default or Latest.	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. Note This parameter takes effect only when the LaunchTemplateId parameter specifies a launch template.	ecs.c5.2xlarge
Containers	array<object>	No	The list of containers in the instance. Note This parameter is supported only for Elastic Container Instance (ECI) scaling groups. Only container configurations whose names match `Container.Name` in the current scaling configuration container list are refreshed.
	array<object>	No	The list of containers 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 commands. A maximum of 20 commands are supported. Each 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 arguments for the container startup command. A maximum of 10 arguments are supported.	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 individual configuration items. Valid values: true: Instances that were already created with the desired configuration are skipped. false: All instances in the scaling group at the time the refresh task starts are refreshed. Default value: true.	true
Checkpoints	array<object>	No	The checkpoints for the refresh task. Specifies that the task is automatically paused for CheckpointPauseTime minutes 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 `CheckpointPauseTime` minutes 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 at which the task is automatically paused. 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 duration for which the task is paused when a 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: The system cloud disk of existing instances is replaced by specifying DesiredConfiguration.image to update the system cloud disk. 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.