All Products
Search
Document Center

Auto Scaling:AttachInstances

Last Updated:Oct 26, 2026

Manually adds ECS instances to a scaling group.

Operation description

Operation description

  • Before you invoke this operation, make sure that the following conditions are met:

    • The scaling group is in the Active state.

    • No scaling activities are in progress in the scaling group.

  • Limits on ECS instances or Elastic Container Instance (ECI) instances to be added to the scaling group:

    • The instances must be in the same region as the scaling group.

    • The instances must be in the Running state.

    • The instances must not be added to other scaling groups.

    • The billing method of the instances must be subscription, pay-as-you-go, or spot instance.

    • If VSwitchId is specified for the scaling group, classic network-connected ECS instances or ECI instances and ECS instances or ECI instances in other VPCs cannot be added to the scaling group.

    • If VSwitchId is not specified for the scaling group, VPC-connected ECS instances or ECI instances cannot be added to the scaling group.

  • Limits on managed instances to be added to the scaling group:

    • The managed instances must be in the same region as the scaling group.

    • Only managed instances that are not added to any scaling group can be added to an ECS scaling group.

    • Managed instances do not support lifecycle hooks, association with load balancing, or the health check feature.

    • After managed instances are added to an ECS scaling group, the scaling group does not manage the lifecycle of the managed instances.

    • Managed instances can only be manually added to or removed from the scaling group. Removed managed instances are not released.

  • Precautions for using this operation:

    • If no scaling activities are in progress in the scaling group, this operation can bypass the cooldown time and be executed directly.

    • A successful response only indicates that the Auto Scaling service accepts the invocation request and the scaling activity can be executed. It does not mean that the scaling activity will be executed successfully. You must use the returned ScalingActivityId to check the execution status of the scaling activity.

    • If the sum of the number of instances specified in this operation and the current total number of instances in the scaling group is greater than the maximum number of instances allowed, the invocation fails.

    • ECS instances, ECI instances, or managed instances manually added by using this operation are not associated with the active scaling configuration of the scaling group.

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:AttachInstances

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****

Entrusted

boolean

No

Specifies whether to entrust the lifecycle of an existing instance to the scaling group when the instance is manually added to the scaling group. Valid values:

  • true: The lifecycle is entrusted. The lifecycle of the instance is managed by Auto Scaling, which is the same as that of instances automatically created by the scaling group. The instance is automatically released when it is removed from the scaling group, excluding instances removed when you invoke the DetachInstances operation.

  • false: The lifecycle is not entrusted. The instance is not released when it is removed from the scaling group.

Note

Settings for this parameter are not supported for subscription instances, managed instances, or stopped instances in the scaling group.

Default value: false.

false

InstanceId

array

No

InstanceId.N specifies instance ID of the ECS instance, ECI instance, managed instance, or stopped instance in the scaling group to be added. Valid values of N: 1 to 20.

Examples:

  • Instance ID of the ECS instance to be added is i-28wt4****.

  • Instance ID of the ECI instance to be added is eci-bp17gw49eu09yiwm****.

  • Instance ID of the managed instance to be added is mi-2cx*****.

  • Instance ID of the stopped instance in the scaling group to be restarted is i-2cd2f****.

Note

Only one type of instance can be processed in a single request.

i-28wt4****

string

No

InstanceId.N specifies instance ID of the ECS instance, ECI instance, managed instance, or stopped instance in the scaling group to be added. Valid values of N: 1 to 20.

Examples:

  • Instance ID of the ECS instance to be added is i-28wt4****.

  • Instance ID of the ECI instance to be added is eci-bp17gw49eu09yiwm****.

  • Instance ID of the managed instance to be added is mi-2cx*****.

  • Instance ID of the stopped instance in the scaling group to be restarted is i-2cd2f****.

Note

Only one type of instance can be processed in a single request.

i-28wt4****

LoadBalancerWeight

array

No

The weight of the ECS instance or ECI instance as a load balancing backend server.

Note

Settings for this parameter are not supported for managed instances or stopped instances in the scaling group.

50

integer

No

LoadBalancerWeight.N specifies the weight of the ECS instance or ECI instance as a backend server of the load balancing instance. Valid values of N: 1 to 20. Valid values of this parameter: 1 to 100.

Note

Settings for this parameter are not supported for managed instances or stopped instances in the scaling group.

Default value: 50.

50

LifecycleHook

boolean

No

Specifies whether to trigger the scale-out lifecycle hook when instances are added to the scaling group. Valid values:

  • true: Triggered.

  • false: Not triggered.

Note

This parameter is not supported for managed instances or stopped instances in the scaling group.

Default value: false.

false

RegionId

string

No

The region ID of the scaling group.

cn-qingdao

ClientToken

string

No

The client token that is used to ensure the idempotence of the request.

You can generate the value from your client to ensure that the value is unique among different requests. The token can only contain ASCII characters and cannot exceed 64 characters in length. For more information, see How to ensure idempotence.

123e4567-e89b-12d3-a456-42665544****

IgnoreInvalidInstance

boolean

No

Specifies whether to ignore invalid instances when a batch of instances is added to the scaling group. Valid values:

  • true: Invalid instances are ignored. If invalid instances exist and valid instances are successfully added, the execution status of the scaling activity is displayed as Warning. You can view the invalid instances in the scaling activity details.

  • false: Invalid instances are not ignored. If invalid instances exist in the batch, the request returns an error.

Default value: false.

false

Response elements

Element

Type

Description

Example

object

ScalingActivityId

string

The ID of the scaling activity.

asa-bp1crxor24s28xf1****

RequestId

string

The request ID.

473469C7-AA6F-4DC5-B3DB-A3DC0DE3****

Examples

Success response

JSON format

{
  "ScalingActivityId": "asa-bp1crxor24s28xf1****",
  "RequestId": "473469C7-AA6F-4DC5-B3DB-A3DC0DE3****"
}

Error codes

HTTP status code

Error code

Error message

Description

500 InternalError The request processing has failed due to some unknown error, exception or failure.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.