DocsICP FilingConsole
Documentation

StartInstanceRefresh

Updated at:
Copy as MD
Product
My Favorites

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

Operation description

  • Only one instance refresh node can run in a scaling group at a time.

  • 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 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 proceed. However, scale-out operations use the desired configuration specified in the instance refresh node.

  • Instances that are manually added to the scaling group, or instances in the standby state or protection status, are ignored by the instance refresh node and do not participate in the 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 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 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.

m-2ze8cqacj7opnf***
ScalingConfigurationId

string

No

The ID of the scaling configuration.

asc-2zed7lqn4ts4****
LaunchTemplateId

string

No

The ID of the launch template from which the scaling group obtains launch configuration information.

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

When 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 overrides the launch template.

object

No

The instance type information that overrides 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 included in the instance.

Note

  • This parameter is supported only for Elastic Container Instance (ECI) scaling groups.

  • Only the container configurations that match Container.Name in the current scaling configuration container list are refreshed.

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 startup commands of the container. You can specify up to 20 commands. Each command can contain up to 256 characters.

string

No

The startup commands of the container. You can specify up to 20 commands. Each command can contain up to 256 characters.

sleep
Args

array

No

The arguments of the container startup command. You can specify up to 10 arguments.

string

No

The arguments of the container startup command. You can specify up to 10 arguments.

100
EnvironmentVars

array<object>

No

The environment variable information.

object

No

The environment variable information.

Key

string

No

The name of the environment variable. It can be 1 to 128 characters in length. Format requirement:[0-9a-zA-Z], and underscores, cannot start with a number.

PATH
Value

string

No

The value of the environment variable. The value must be 0 to 256 bits in length.

/usr/local/bin

FieldRefFieldPath

string

No

Note

This parameter is unavailable for use.

fieldPath
SkipMatching

boolean

No

Specifies whether to skip instances that already 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 are refreshed when the instance refresh task starts.

Default value: true.

true
Checkpoints

array<object>

No

The checkpoints for the refresh task. When the percentage of new instances reaches a specified value during the instance refresh, the task is automatically paused for CheckpointPauseTime minutes.

object

No

The checkpoints for the refresh task. When the percentage of new instances reaches a specified value during the instance refresh, the task is automatically paused for CheckpointPauseTime minutes.

Percentage

integer

No

The percentage of new instances relative to the total number of 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 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

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.