View a markdown version of this page

Launching instances with synchronous provisioning - Amazon EC2 Auto Scaling
PrerequisitesLaunch instances with synchronous provisioningHandle launch failures and retries

Launching instances with synchronous provisioning

You can use the LaunchInstances API to synchronously launch a specific number of instances in your Auto Scaling group. The API launches instances in the Availability Zone or subnet that you specify and immediately returns the instance IDs or error information.

Prerequisites

Before you can use the LaunchInstances API, you must have:

  • An Auto Scaling group that uses a launch template (launch configurations are not supported)

  • You must have permissions for the following IAM actions:

    • autoscaling:LaunchInstances

    • ec2:CreateFleet

    • ec2:DescribeLaunchTemplateVersions

Launch instances with synchronous provisioning

You can launch instances with synchronous provisioning through the AWS CLI.

AWS CLI

To launch instances with synchronous provisioning:

aws autoscaling launch-instances \
        --auto-scaling-group-name group-name \
        --requested-capacity number \
        [--availability-zones zone-name] \
        [--subnet-ids subnet-id] \
        [--availability-zone-ids zone-id] \
        [--retry-strategy none|retry-with-group-configuration] \
        [--client-token token]

Examples

Launching instances in a specific Availability Zone

aws autoscaling launch-instances \
        --auto-scaling-group-name my-asg \
        --requested-capacity 3 \
        --availability-zones us-east-1a \
        --retry-strategy retry-with-group-configuration

Launching instances in a specific subnet

aws autoscaling launch-instances \
        --auto-scaling-group-name my-asg \
        --requested-capacity 2 \
        --subnet-ids subnet-12345678 \
        --retry-strategy none \
        --client-token my-unique-token-123

Handling responses

Example of a successful response:


{
    "AutoScalingGroupName": "my-asg",
    "ClientToken": "my-unique-token-123",
    "Instances": [
        {
            "InstanceType": "m5.xlarge",
            "AvailabilityZone": "us-east-1a",
            "AvailabilityZoneId": "use1-az1",
            "SubnetId": "subnet-12345678",
            "MarketType": "OnDemand",
            "InstanceIds": ["i-0123456789abcdef0", "i-0fedcba9876543210"]
        }
    ],
    "Errors": []
}

Example of a response with errors


{
    "AutoScalingGroupName": "my-asg",
    "ClientToken": "my-unique-token-123",
    "Instances": [],
    "Errors": [
       {
        "InstanceType": "m5.large",
        "AvailabilityZone": "us-east-1a",
        "AvailabilityZoneId": "use1-az1",
        "SubnetId": "subnet-12345678",
        "MarketType": "OnDemand",
        "ErrorCode": "InsufficientInstanceCapacity",
        "ErrorMessage": "There is not enough capacity to fulfill your request for instance type 'm5.large' in 'us-east-1a'"
        }
    ]
}

Handle launch failures and retries

When the LaunchInstances API encounters failures, you can implement retry strategies using idempotency tokens and appropriate retry policies.

You can use the client-token parameter to retry requests. You can also use the following retry strategies:

  • RetryStrategy: none (default) - If the API call fails, the Auto Scaling group's desired capacity remains unchanged and no automatic retry occurs.

  • RetryStrategy: retry-with-group-configuration - If the API call fails, the Auto Scaling group's desired capacity is increased by the requested amount, and Auto Scaling will automatically retry launching instances using the group's standard configuration and processes.

Retry behavior for RetryStrategy: retry-with-group-configuration depends on the failure type:

  • Validation errors: Desired capacity is not increased since the operation can't proceed. For example, invalid parameters or unsupported configurations.

  • Capacity errors: Desired capacity is increased and Auto Scaling will retry launching instances asynchronously using the group's normal scaling processes.

Using client tokens for idempotency

The client-token parameter ensures idempotent operations and enables safe retries of launch requests.

Key behaviors:

  • Client tokens have an 8-hour lifetime from the initial request

  • Retrying with the same client token within 8 hours returns the cached response instead of launching new instances

  • After 8 hours, the same client token will initiate a new launch operation