Use the CreateAutoProvisioningGroup API operation to batch create ECS instances in pay-as-you-go scenarios - Elastic Compute Service

Call CreateAutoProvisioningGroup to batch create pay-as-you-go ECS instances across zones, instance types, and billing methods.

Background

RunInstances is the most common API operation for creating pay-as-you-go ECS instances. A single RunInstances call creates up to 100 instances, but using RunInstances to create more than 100 in a production environment can cause bottlenecks. See Issues when creating instances with RunInstances.

Note

If you already understand the bottlenecks of RunInstances for batch creation, skip the Issues when creating instances with RunInstances section.

Alibaba Cloud provides auto provisioning groups for large-scale instance creation. Call CreateAutoProvisioningGroup to deploy an instance cluster across billing methods, zones, and instance types in a single action. Compared to RunInstances, CreateAutoProvisioningGroup better suits scenarios that require many ECS instances. See Comparison of RunInstances and CreateAutoProvisioningGroup and Benefits of auto provisioning groups.

Compare RunInstances and CreateAutoProvisioningGroup

The following table compares the RunInstances and CreateAutoProvisioningGroup API operations to help you choose the right method.

Item	RunInstances	CreateAutoProvisioningGroup
Max instances per batch	100	1,000 (up to 10,000 vCPUs)
Capacity delivery method	Instance count	Number of instances, vCPU cores, instance type weights, and more.
Multi-zone support	No	Yes
Multiple instance type support	No	Yes
Multiple disk type support	No	Yes
Instance creation policies	No	Yes. The following policies are provided: Pay-as-you-go instances Cost optimization: Creates lowest-cost instances among specified types. Priority-based: Creates instances based on the specified instance type priority. Spot instances Cost optimization: Creates lowest-cost instances among specified types. Balanced distribution: Evenly distributes instances across specified zones. Capacity-optimized distribution: Creates instances from optimal types and zones based on spot instance inventory.
Delivery stability	Highly affected by resource inventory	Multiple zones and instance types reduce inventory impact
API response format	Synchronous	Synchronous

Sample migration scenarios from RunInstances to CreateAutoProvisioningGroup:

If you used RunInstances to create instances of a single type in one zone, switch to CreateAutoProvisioningGroup and configure multiple instance type and zone combinations.
If you used a manual deployment plan with RunInstances, switch to CreateAutoProvisioningGroup for one-click deployment across zones, instance types, and disk configurations with built-in creation policies.

For example, if you previously traversed multiple instance types and zones with RunInstances to improve creation success rates, CreateAutoProvisioningGroup handles this automatically — configure the combinations, select a policy, and the group creates instances.

Important

Auto provisioning groups can create up to 1,000 instances at a time. If you specify WeightedCapacity for instance types, the maximum total weighted capacity per creation is 10,000.

Issues with RunInstances for batch creation

The RunInstances operation has the following limitations when creating many instances.

Issue	Description	Solution
Limited batch capacity	A single RunInstances call creates up to 100 instances.	Call the operation multiple times in a loop or concurrently.
Insufficient batch stability	RunInstances supports only a single zone and instance type, so batch creation may fail due to: Insufficient inventory for the specified instance type. The instance type is discontinued. The instance type is available only in certain zones. The instance type requires specific disk types.	Insufficient inventory is the main cause of batch creation failures. Call DescribeAvailableResource to query inventory for specific instance types and zones. After confirming multiple zone-instance type combinations with sufficient inventory, batch create instances. This approach improves delivery stability. Example: After confirming multiple valid combinations, build a creation strategy. For instance, create 100 instances in sequence by combination. If the first combination supports only 50 instances, use the second combination for the remaining 50. Instance types have usage limits. Call DescribeAvailableResource to query limits and create a fault tolerance plan. Note You can also check instance type limits in Instance families. Example: `ecs.g6e.large` supports only ESSD disks, but the `cn-beijing-x` zone does not support ESSD.
Overly simple creation policy	RunInstances supports only a single zone and instance type. Multi-zone disaster recovery or lowest-cost creation requires a self-built deployment plan, which has the following issues: High development cost. The plan must handle insufficient inventory, cost optimization for spot instances during scale-out, and more. Low stability. Building and testing a professional deployment plan for Alibaba Cloud resources on your own poses production risks.	Resolve the issues yourself or contact Alibaba Cloud for help.

Benefits of auto provisioning groups

Auto provisioning groups address the limitations of RunInstances by supporting one-click deployment across billing methods, zones, and instance types. They provide stable computing power, mitigate spot instance reclamation risks, and eliminate repeated manual creation.

Benefit	Description
Higher batch limit	Up to 1,000 instances per batch.
Multiple zones, instance types, and disk types	Configure up to 10 instance type or zone combinations and up to 5 disk types for high availability batch creation. Example: With the balanced distribution policy, instances are distributed evenly across zones. If creation fails in one zone, the group creates pending instances in other available zones. With multiple disk types specified, the group uses them in priority order. If one type is unavailable, it automatically switches to the next. Note If all specified disk types are unavailable, the group switches to another creation method.
Multiple creation policies	Available creation policies: Pay-as-you-go instances Cost optimization: Creates lowest-cost instances among specified types. Priority-based: Creates instances based on the specified instance type priority. Spot instances Cost optimization: Creates lowest-cost instances among specified types. Balanced distribution: Evenly distributes instances across specified zones. Capacity-optimized distribution: Creates instances from optimal types and zones based on spot instance inventory.
Improved spot instance availability	Spot instances offer low prices but are subject to price fluctuations and reclamation. Auto provisioning groups improve spot instance availability while keeping costs low: The default cost optimization policy creates instances in ascending order of price. Inventories for different spot instance type and zone combinations are isolated. Multiple combinations reduce the probability of full inventory depletion. Configure multiple alternative disk types so the group automatically selects suitable types during creation. Set `SpotInstancePoolsToUseCount` to spread spot instances across multiple lowest-price pools, preventing computing power loss if one type is reclaimed.

Best practices for CreateAutoProvisioningGroup

The following Java code sample demonstrates how to call CreateAutoProvisioningGroup.

Install the ECS SDK for Java and the Alibaba Cloud core library.

See SDK overview.

Call CreateAutoProvisioningGroup with Java.

Code sample:

import com.aliyun.ecs20140526.Client;
import com.aliyun.ecs20140526.models.CreateAutoProvisioningGroupRequest;
import com.aliyun.ecs20140526.models.CreateAutoProvisioningGroupResponse;
import com.aliyun.teaopenapi.models.Config;
import com.aliyun.teautil.models.RuntimeOptions;
import com.google.gson.Gson;

public class Test {
    public static void main(String[] args_) throws Exception {
        Config config = new Config()
                .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
                .setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"))
                .setEndpoint("ecs.cn-heyuan.aliyuncs.com");
        Client client = new Client(config);

        CreateAutoProvisioningGroupRequest.CreateAutoProvisioningGroupRequestLaunchTemplateConfig launchTemplateConfig = new CreateAutoProvisioningGroupRequest.CreateAutoProvisioningGroupRequestLaunchTemplateConfig()
                .setVSwitchId("vsw-f8zadqudz*********")
                .setInstanceType("ecs.s6-c1m1.small")
                .setWeightedCapacity(1.0);

        CreateAutoProvisioningGroupRequest.CreateAutoProvisioningGroupRequestLaunchConfiguration launchConfiguration = new CreateAutoProvisioningGroupRequest.CreateAutoProvisioningGroupRequestLaunchConfiguration()
                .setSecurityGroupId("sg-f8zf6vg51*********")
                .setImageId("aliyun_3_x64_20G_alibase_20250629.vhd")
                .setSystemDiskCategory("cloud_ssd")
                .setSystemDiskSize(40);
        CreateAutoProvisioningGroupRequest createAutoProvisioningGroupRequest = new CreateAutoProvisioningGroupRequest()
                .setAutoProvisioningGroupType("instant")
                .setRegionId("cn-heyuan")
                // Set the creation policy for spot instances.
                .setSpotAllocationStrategy("lowest-price")
                // Set the creation policy for pay-as-you-go instances.
                .setPayAsYouGoAllocationStrategy("prioritized")
                .setTotalTargetCapacity("5")
                .setPayAsYouGoTargetCapacity("3")
                .setSpotTargetCapacity("2")
                .setLaunchConfiguration(launchConfiguration)
                .setLaunchTemplateConfig(java.util.Arrays.asList(
                        launchTemplateConfig
                ))
                .setClientToken("0c593ea1-3bea******************");
        RuntimeOptions runtime = new RuntimeOptions();
        CreateAutoProvisioningGroupResponse response = client.createAutoProvisioningGroupWithOptions(createAutoProvisioningGroupRequest, runtime);
        System.out.println(new Gson().toJson(response.getBody()));
    }
}

Sample JSON response:

{
    "autoProvisioningGroupId": "apg-**************",
    "launchResults": {
        "launchResult": [
            {
                "amount": 0,
                "errorCode": "NoInstanceStock",
                "errorMsg": "The instanceTypes are out of usage",
                "instanceType": "ecs.s6-c1m1.small",
                "spotStrategy": "NoSpot",
                "zoneId": "cn-heyuan-b"
            },
            {
                "amount": 2,
                "instanceIds": {
                    "instanceId": [
                        "i-f8z8**************icn5",
                        "i-f8z8**************icn6"
                    ]
                },
                "instanceType": "ecs.s6-c1m1.small",
                "spotStrategy": "SpotAsPriceGo",
                "zoneId": "cn-heyuan-b"
            }
        ]
    },
    "requestId": "CDA21119-7CFD-5B40-A2D0-******8"
}

With CreateAutoProvisioningGroup, you configure the batch creation parameters and the group handles the creation process on a best-effort basis.

Note

Best-effort delivery means that if some resource combinations cannot create instances, the group automatically switches to other available combinations. This process takes time and the actual result may slightly differ from the specified policy.