You can call this operation to create a scaling group.

Description

A scaling group is a group of ECS instances that are dynamically scaled based on the configured scenario.

  • A single account can have up to 50 scaling groups in a region.
  • A scaling group does not take effect immediately after being created. You must call the EnableScalingGroup operation to enable the scaling group to trigger scaling rules and execute scaling activities.
  • Each scaling group must be in the same region as the Server Load Balancer (SLB) instance and ApsaraDB for RDS instance that are associated with it. For more information, see Regions and zones.
  • If an SLB instance is specified for a scaling group, the scaling group automatically adds ECS instances to the backend server group of the specified SLB instance. The default weight of an ECS instance added to the backend server group is 50. The specified SLB instance must meet the following requirements:
    • The SLB instance must be in the Active state. You can call the DescribeLoadBalancers operation to query the status of the specified SLB instance.
    • Health check must be enabled on all listener ports configured for the SLB instance. Otherwise, the scaling group fails to be created.
  • If an RDS instance is specified for a scaling group, the scaling group automatically adds the internal IP addresses of its ECS instances to the whitelist of the specified RDS instance. The specified RDS instance must meet the following requirements:
    • The RDS instance must be in the Running state. You can call the DescribeDBInstances operation to query the status of the specified RDS instance.
    • The number of IP addresses in the RDS instance whitelist cannot exceed the upper limit. For more information, see Configure a whitelist.
  • If the MultiAZPolicy parameter of a scaling group is set to COST_OPTIMIZED (cost optimization policy):
    • When the OnDemandBaseCapacity, OnDemandPercentageAboveBaseCapacity, and SpotInstancePools parameters are specified,

      the scaling group will use the instance allocation method based on the cost optimization policy. This allocation method is prioritized during scaling activities.

    • When at least one of the OnDemandBaseCapacity, OnDemandPercentageAboveBaseCapacity, and SpotInstancePools parameters is not specified,

      the instance types available at the lowest cost are selected to create instances based on the cost optimization policy.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter Type Required Example Description
Action String No CreateScalingGroup

The operation that you want to perform. Set the value to CreateScalingGroup.

MaxSize Integer Yes 20

The maximum number of ECS instances in the scaling group. Valid values: 0 to 1000. When the number of ECS instances in the scaling group exceeds the value of MaxSize, Auto Scaling removes the ECS instances from the scaling group until the number of instances is equal to the value of MaxSize.

MinSize Integer Yes 2

The minimum number of ECS instances in the scaling group. Valid values: 0 to 1000. When the number of ECS instances in the scaling group is less than the value of MinSize, Auto Scaling automatically creates ECS instances until the number of instances is equal to the value of MinSize.

RegionId String Yes cn-qingdao

The ID of the region where the scaling group resides. For more information, see Regions and zones.

ScalingGroupName String No test-sg

The name of the scaling group. The name of a scaling group must be unique in a region. The name must be 2 to 64 characters in length and can contain letters, digits, underscores (_), hyphens (-), and periods (.). It must start with a letter or digit.

The default value is the ID of the scaling group.

LaunchTemplateId String No lt-m5e3ofjr1zn1aw7****

The ID of the instance launch template from which the scaling group obtains launch configurations.

LaunchTemplateVersion String No Default

The version of the instance launch template. Valid values:

  • The fixed template version number.
  • Default: The default template version is always used.
  • Latest: The latest template version is always used.
InstanceId String No i-28wt4****

The ID of the ECS instance from which the scaling group obtains configuration information of the specified instance.

DefaultCooldown Integer No 300

The cooldown period after a scaling activity (adding or removing ECS instances) is executed. Valid values: 0 to 86400. Unit: seconds.

Default value: 300

During the cooldown period, the scaling group does not execute any other scaling activities triggered by CloudMonitor event-triggered tasks.

LoadBalancerIds String No ["lb-idx", "lb-idy", "lb-idz"]

The IDs of SLB instances. This value can be a JSON array which contains up to five SLB instance IDs. Separate multiple IDs with commas (,).

DBInstanceIds String No ["rm-idx", "rm-idy", "rm-idz"]

The IDs of RDS instances. This value can be a JSON array which contains up to eight RDS instance IDs. Separate multiple IDs with commas (,).

RemovalPolicy.1 String No OldestScalingConfiguration

Specifies policy N for removing ECS instances from the scaling group. Valid values of N: 1 to 2.. Valid values:

  • OldestInstance: removes the ECS instance that is added to the scaling group at the earliest point in time.
  • NewestInstance: removes the ECS instance that is added to the scaling group at the latest point in time.
  • OldestScalingConfiguration: removes the ECS instance that is created based on the earliest scaling configuration.

Default value of RemovalPolicy.1: OldestScalingConfiguration.

Default value of RemovalPolicy.2: OldestInstance.

VSwitchId String No vsw-****

The ID of the specified VSwitch when a VPC-type scaling group is created.

VSwitchIds.N RepeatList No vsw-****

The IDs of one or more VSwitches. Valid values of N: 1 to 5. If you use the VSwitchIds.N parameter, the VSwitchId parameter is ignored.

This parameter is valid only when the network type of the scaling group is VPC. The specified VSwitch and the scaling group must be in the same VPC.

VSwitches can reside in different zones. VSwitches are sorted in ascending order based on the value of N. Value 1 indicates the highest priority. When an ECS instance cannot be created in the zone where the VSwitch with the highest priority resides, the system automatically uses the VSwitch with the next highest priority to create the ECS instance.

MultiAZPolicy String No PRIORITY

The ECS instance scaling policy for the multi-zone scaling group. Valid values:

  • PRIORITY: ECS instances are scaled based on the VSwitchIds.N parameter. When an ECS instance cannot be created in the zone where the VSwitch with the highest priority resides, the system automatically uses the VSwitch with the next highest priority to create the ECS instance.
  • COST_OPTIMIZED: ECS instances are created based on the unit prices of vCPUs in ascending order. Preemptible instances are preferentially created when preemptible instance types are specified for the scaling configuration. Pay-as-you-go instances are created automatically when all types of preemptible instances are unavailable due to issues such as insufficient ECS resources.
    Note COST_OPTIMIZED takes effect only when multiple instance types are specified or at least one preemptible instance type is specified.
  • BALANCE: ECS instances are distributed evenly in multiple zones specified in the scaling group. If ECS instances are unevenly distributed among the zones due to certain issues such as insufficient ECS resources, you can reallocate instances to make them evenly distributed by calling the RebalanceInstance operation.

Default value: PRIORITY

HealthCheckType String No ECS

The health check mode of the scaling group. Valid values:

  • NONE: The system performs no health check.
  • ECS: The system performs the health check on ECS instances in the scaling group.
LifecycleHook.N.LifecycleHookName String No lifecycle_hook

The name of the lifecycle hook. The name is used to specify a lifecycle hook and cannot be modified if it is set.

LifecycleHook.N.LifecycleTransition String No SCALE_OUT

The type of scaling activity to which the lifecycle hook applies. Valid values:

  • SCALE_OUT: scale-out activities of the scaling group.
  • SCALE_IN: scale-in activities of the scaling group.
LifecycleHook.N.DefaultResult String No CONTINUE

The action that the scaling group takes when the lifecycle hook times out. Valid values:

  • CONTINUE: The scaling group continues the scale-in or scale-out activity.
  • ABANDON: The scaling group releases the created ECS instances if the scaling activity type is scale-out or removes the ECS instances to be scaled in if the scaling activity type is scale-in.

Default value: CONTINUE

If the scaling group has multiple lifecycle hooks and one of them is terminated when the DefaultResult parameter is set to ABANDON during a scale-in activity, the remaining lifecycle hooks in the same scaling group are also terminated. Otherwise, the scaling activity will proceed normally after the wait period expires and continue with the action specified by the DefaultResult parameter.

LifecycleHook.N.HeartbeatTimeout Integer No 600

The wait period before the lifecycle hook times out. If the lifecycle hook times out, the scaling group performs the action specified in the DefaultResult parameter. Valid values: 30 to 21600. Unit: seconds.

Default value: 600

You can prevent the lifecycle hook from timing out by calling the RecordLifecycleActionHeartbeat operation. You can also terminate the lifecycle hook by calling the CompleteLifecycleAction operation.

LifecycleHook.N.NotificationMetadata String No Test

The fixed string that you want to include when Auto Scaling sends a message about the wait state of a scaling activity to the notification target. The parameter value can be up to 128 characters in length. Auto Scaling sends the specified NotificationMetadata parameter value along with the notification message so that you can easily categorize your notifications. The NotificationMetadata parameter is valid only after you set the NotificationArn parameter.

LifecycleHook.N.NotificationArn String No acs:ess:cn-hangzhou:1111111111:queue/queue2

The Alibaba Cloud Resource Name (ARN) of the notification object that Auto Scaling uses to notify you when an instance is in the transition state for the lifecycle hook. This object can be either an MNS queue or an MNS topic. The format of the parameter value is acs:ess:{region}:{account-id}:{resource-relative-id}.

  • region: the region where the scaling group resides.
  • account-id: the ID of the Alibaba Cloud account.

Examples:

  • MNS queue: acs:ess:{region}:{account-id}:queue/{queuename}
  • MNS topic: acs:ess:{region}:{account-id}:topic/{topicname}
VServerGroup.N.LoadBalancerId String No lb-****

The ID of the SLB instance with which the VServer group is associated.

For more information, see AttachVServerGroups.

VServerGroup.N.VServerGroupAttribute.N.VServerGroupId String No rsp-****

The ID of the VServer group.

For more information, see AttachVServerGroups.

VServerGroup.N.VServerGroupAttribute.N.Port Integer No 22

The port number that is used by Auto Scaling to add the ECS instances to the VServer group. Valid values: 1 to 65535.

For more information, see AttachVServerGroups.

VServerGroup.N.VServerGroupAttribute.N.Weight Integer No 100

The weight set for the ECS instances that are added to the VServer group. Valid values: 0 to 100.

Default value: 50

For more information, see AttachVServerGroups.

ScalingPolicy String No recycle

The reclaim policy of the scaling group. Valid values:

  • recycle: The scaling group is set to Shutdown and Reclaim Mode.
  • release: The scaling group is set to Release Mode.

For more information, see RemoveInstances.

ClientToken String No 123e4567-e89b-12d3-a456-42665544****

The client token that is used to ensure the idempotence of the request. You can use the client to generate the value, but you must ensure that it 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.

OnDemandBaseCapacity Integer No 30

The minimum number of pay-as-you-go instances required in the scaling group. Valid values: 0 to 1000. When the number of pay-as-you-go instances is less than this value, the scaling group will attempt to create pay-as-you-go instances over other instances.

OnDemandPercentageAboveBaseCapacity Integer No 20

The percentage of pay-as-you-go instances to create when instances are added to the scaling group.This parameter takes effect after the number of instances reaches the value of OnDemandBaseCapacity. Valid values: 0 to 100.

SpotInstanceRemedy Boolean No true

Specifies whether to supplement preemptible instances when the target capacity of preemptible instances is not fulfilled. When receiving a system message that a preemptible instance will be reclaimed, the scaling group will create a new instance to replace the instance to be reclaimed if this parameter is set to true.

SpotInstancePools Integer No 5

The number of available instance types. The scaling group will create preemptible instances of multiple instance types available at the lowest cost. Valid values: 0 to 10.

DesiredCapacity Integer No 5

The expected number of ECS instances in the scaling group. The scaling group automatically keeps the number of ECS instances at the expected value. The number of ECS instances cannot be greater than the value of MaxSize and cannot be less than the value of MinSize.

GroupDeletionProtection Boolean No true

Specifies whether the scaling group deletion protection is enabled. Valid values:

  • true: The scaling group deletion protection is enabled. You cannot delete the scaling group.
  • false: The scaling group deletion protection is disabled.

Default value: false

Tag.N.Key String No Department

The tag key of the scaling group.

Tag.N.Value String No Finance

The tag value of the scaling group.

Response parameters

Parameter Type Example Description
ScalingGroupId String asg-bp14wlu85wrpchm0****

The ID of the scaling group.

RequestId String 473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E

The ID of the request.

Examples

Sample requests

http://ess.aliyuncs.com/?Action=CreateScalingGroup
&RegionId=cn-qingdao
&MaxSize=20 
&MinSize=2
&LoadBalancerId=147b46d767c-cn-qingdao-cm5****
&DBInstanceId.1=rm-rdszzzyyuny****
&DBInstanceId.2=rm-rdsia3u3yia****
&<Common request parameters>

Sample success responses

XML format

<CreateScalingGroupResponse>
      <RequestId>473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E</RequestId>
      <ScalingGroupId>asg-bp14wlu85wrpchm0****</ScalingGroupId>
</CreateScalingGroupResponse>

JSON format

{
    "RequestId": "473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E",
    "ScalingGroupId": "asg-bp14wlu85wrpchm0****"
}

Error codes

For a list of error codes, visit the API Error Center.

HTTP status code

Error code

Error message

Description

400

IncorrectDBInstanceStatus

The current status of DB instance "XXX" does not support this action.

The error message returned because the specified RDS instance is not in the Running state.

400

IncorrectLoadBalancerHealthCheck

The current health check type of specified load balancer does not support this action.

The error message returned because health check is not enabled for the specified SLB instance.

400

IncorrectLoadBalancerStatus

The current status of the specified load balancer does not support this action.

The error message returned because the specified SLB instance is not in the Active state.

400

IncorrectVSwitchStatus

The current status of virtual switch does not support this operation.

The error message returned because the VSwitch is unavailable and ECS instances cannot be created.

400

InvalidDBInstanceId. RegionMismatch

DB instance "XXX" and the specified scaling group are not in the same Region.

The error message returned because the specified RDS instance and the specified scaling group are not in the same region.

400

InvalidLoadBalancerId.IncorrectAddressType

The current address type of specified load balancer does not support this action.

The error message returned because the network type of the specified SLB instance does not match the VSwitch.

400

InvalidLoadBalancerId.IncorrectInstanceNetworkType

The network type of the instance in specified Load Balancer does not support this action.

The error message returned because the network type of the ECS instance attached to the specified SLB instance is different from that of the scaling group.

400

InvalidLoadBalancerId.RegionMismatch

The specified Load Balancer and the specified scaling group are not in the same Region.

The error message returned because the specified SLB instance and the scaling group are not in the same region.

400

InvalidLoadBalancerId.VPCMismatch

The specified virtual switch and the instance in specified Load Balancer are not in the same VPC.

The error message returned because the VSwitch and the ECS instance attached to the SLB instance of the scaling group are not in the same VPC.

400

InvalidParameter

The specified value of parameter "ScalingPolicy" is not valid.

The error message returned because the specified value of the ScalingPolicy parameter is invalid.

400

InvalidParameter.Conflict

The value of parameter <parameter name> and parameter <parameter name> are conflict.

The error message returned because the specified value of MinSize is greater than the value of MaxSize.

400

InvalidScalingGroupName.Duplicate

The specified value of parameter <parameter name> is duplicated.

The error message returned because the specified scaling group name already exists.

400

QuotaExceeded.DBInstanceSecurityIP

Security IP quota exceeded in DB instance "XXX".

The error message returned because the number of IP addresses in the specified RDS instance whitelist reaches the upper limit.

400

QuotaExceeded.PrivateIpAddress

Private IP address quota exceeded in the specified virtual switch.

The error message returned because the private IP address quota of the VSwitch is exceeded.

400

QuotaExceeded.ScalingGroup

Scaling group quota exceeded.

The error message returned because the number of scaling groups reaches the upper limit.

400

QuotaExceeded.VPCInstance

Instance quota exceeded in the specified VPC.

The error message returned because the number of instances in the VPC reaches the upper limit.

404

InvalidDBInstanceId.NotFound

DB instance "XXX" does not exist.

The error message returned because the specified RDS instance does not exist.

404

InvalidLoadBalancerId.NotFound

The specified Load Balancer does not exist.

The error message returned because the specified SLB instance does not exist.

404

InvalidRegionId.NotFound

The specified region does not exist.

The error message returned because the specified region does not exist.

404

InvalidVSwitchId.NotFound

The specified virtual switch does not exist.

The error message returned because the specified VSwitch does not exist.

400

LaunchTemplateVersionSet.NotFound

The specific version of launch template does not exist.

The error message returned because the specified version of the instance launch template does not exist.

400

LaunchTemplateSet.NotFound

The specified launch template set is not found.

The error message returned because the specified instance launch template does not exist.

400

TemplateMissingParameter.ImageId

The input parameter "ImageId" that is mandatory for processing this request is not supplied.

The error message returned because the ImageId parameter required for the specified instance launch template is not specified.

400

TemplateMissingParameter.InstanceTypes

The input parameter "InstanceTypes" that is mandatory for processing this request is not supplied.

The error message returned because the InstanceTypes parameter required for the specified instance launch template is not specified.

400

TemplateMissingParameter.SecurityGroup

The input parameter "SecurityGroup" that is mandatory for processing this request is not supplied.

The error message returned because the SecurityGroup parameter required for the specified instance launch template is not specified.

400

TemplateVersion.NotNumber

The input parameter "LaunchTemplateVersion" is supposed to be a string representing the version number.

The error message returned because the LaunchTemplateVersion parameter of the specified instance launch template is not in digits.