Elastic Compute Service：RunInstances

The ID of the region in which to create the instance. You can call the DescribeRegions operation to query the most recent region list.

The ID of the image. You can call the DescribeImages operation to query available images. If you do not use LaunchTemplateId or LaunchTemplateName to specify a launch template and do not set ImageFamily to obtain the latest available custom image from a specified image family, you must specify ImageId.

The name of the image family. You can set this parameter to obtain the latest available custom image from the specified image family to create instances.

The name must be 2 to 128 characters in length. The name cannot start with a digit, a special character, http://, or https://. The name can contain letters, digits, periods (.), underscores (_), hyphens (-), and colons (:).

Take note of the following items:

• If you specify ImageId, you cannot specify ImageFamily.
• If you do not specify ImageId but use LaunchTemplateId or LaunchTemplateName to specify a launch template that has ImageId specified, you cannot specify ImageFamily.
• If you do not specify ImageId but use LaunchTemplateId or LaunchTemplateName to specify a launch template that does not have ImageId specified, you can specify ImageFamily.
• If you do not specify ImageId, LaunchTemplateId, or LaunchTemplateName, you can specify ImageFamily.

The instance type. If you do not use LaunchTemplateId or LaunchTemplateName to specify a launch template, you must set the InstanceType parameter.

• Select an instance type. See Instance families or call the DescribeInstanceTypes operation to query the performance data of an instance type, or see Best practices for instance type selection to learn about how to select instance types.
• Query available resources. Call the DescribeAvailableResource operation to query available resources in a specific region or zone.

The ID of the security group to which you want to assign the instance. Instances in the same security group can communicate with each other. The maximum number of instances allowed in a security group varies based on the type of the security group. For more information, see the "Security group limits" section in Limits .

If you do not use LaunchTemplateId or LaunchTemplateName to specify a launch template, you must specify a security group ID. Take note of the following items:

• You can set SecurityGroupId to specify a single security group or set SecurityGroupIds.N to specify one or more security groups. However, you cannot specify both SecurityGroupId and SecurityGroupIds.N in the same request.
• If NetworkInterface.N.InstanceType is set to Primary, you cannot specify SecurityGroupId or SecurityGroupIds.N but can specify NetworkInterface.N.SecurityGroupId or NetworkInterface.N.SecurityGroupIds.N.

The ID of the vSwitch to which to connect to the instance. You must set this parameter when you create an instance of the VPC type. The specified vSwitch and security group must belong to the same VPC. You can call the DescribeVSwitches operation to query available vSwitches.

Take note of the following items:

• If you specify the VSwitchId parameter, the zone specified by the ZoneId parameter must be the zone where the specified vSwitch is located. You can also leave the ZoneId parameter empty. Then, the system selects the zone where the specified vSwitch resides.
• If NetworkInterface.N.InstanceType is set to Primary, you cannot specify VSwitchId but can specify NetworkInterface.N.VSwitchId.

The name of the instance. The name must be 2 to 128 characters in length and can contain letters, digits, colons (:), underscores (_), periods (.), and hyphens (-). The default value of this parameter is the InstanceId value.

When you batch create instances, you can batch configure sequential names for the instances. The sequential names can contain brackets ([ ]) and commas (,). For more information, see Batch configure sequential names or hostnames for multiple instances.

The description of the instance. The description must be 2 to 256 characters in length, and cannot start with http:// or https://.

The maximum inbound public bandwidth. Unit: Mbit/s. Valid values:

• When the purchased outbound public bandwidth is less than or equal to 10 Mbit/s, the valid values of InternetMaxBandwidthIn are 1 to 10, and the default value is 10.
• When the purchased outbound public bandwidth is greater than 10 Mbit/s, the valid values of this parameter are 1 to the InternetMaxBandwidthOut value and the default value is the InternetMaxBandwidthOut value.

The maximum outbound public bandwidth. Unit: Mbit/s. Valid values: 0 to 100.

Default value: 0.

The hostname of the instance. Take note of the following items:

• The hostname cannot start or end with a period (.) or hyphen (-). It cannot contain consecutive periods (.) or hyphens (-).

• For Windows instances, the hostname must be 2 to 15 characters in length and cannot contain periods (.) or contain only digits. It can contain letters, digits, and hyphens (-).

• For instances that run other operating systems such as Linux, take note of the following items:

  • The hostname must be 2 to 64 characters in length. You can use periods (.) to separate a hostname into multiple segments. Each segment can contain letters, digits, and hyphens (-).
  • You can use the ${instance_id} placeholder to pass instance IDs into the hostname specified by HostName. For example, if you set HostName to k8s-${instance_id} and the instance is assigned an ID of i-123abc****, the hostname of the instance is k8s-i-123abc****.

When you create multiple instances, you can perform the following operations:

• Batch configure sequential hostnames for the instances. For more information, see Batch configure sequential names or hostnames for multiple instances.
• Use the HostNames.N parameter to configure different hostnames for instances. You cannot specify both the HostName and HostNames.N parameters.

Specifies whether to automatically append incremental suffixes to the hostname specified by the HostName parameter and to the instance name specified by the InstanceName parameter when you batch create instances. The incremental suffixes can range from 001 to 999. Valid values:

• true
• false

Default value: false.

When the HostName or InstanceName value is set in the name_prefix[begin_number,bits] format without name_suffix, the UniqueSuffix parameter does not take effect. The names are sorted in the specified sequence.

For more information, see Batch configure sequential names or hostnames for multiple instances.

The password of the instance. The password must be 8 to 30 characters in length and contain at least three of the following character types: uppercase letters, lowercase letters, digits, and special characters. Special characters include:

()`~!@#$%^&*-_+=|{}[]:;'<>,.?/

For Windows instances, the password cannot start with a forward slash (/).

Specifies whether to use the password preset in the image. Valid values:

• true: uses the preset password.
• false: does not use the preset password.

Default value: false.

The ID of the zone in which to create the instance. You can call the DescribeZones operation to query the most recent zone list.

This parameter is empty by default.

The billing method for network usage. Valid values:

• PayByBandwidth: pay-by-bandwidth
• PayByTraffic: pay-by-traffic

Default value: PayByTraffic.

The size of the system disk. Unit: GiB. Valid values:

• Basic disk: 20 to 500.

• ESSD: Valid values vary based on the performance level of the ESSD.

  • PL0 ESSD: 1 to 2048.
  • PL1 ESSD: 20 to 2048.
  • PL2 ESSD: 461 to 2048.
  • PL3 ESSD: 1261 to 2048.

• ESSD AutoPL disk: 1 to 2048.

• Other disk categories: 20 to 2048.

The value of this parameter must be at least 1 and greater than or equal to the image size.

Default value: 40 or the image size, whichever is greater.

The category of the system disk. Valid values:

• cloud_efficiency: utra disk
• cloud_ssd: standard SSD
• cloud_essd: enhanced SSD (ESSD)
• cloud: basic disk
• cloud_auto: ESSD AutoPL disk
• cloud_essd_entry: ESSD Entry disk

For non-I/O optimized instances of retired instance types, the default value is cloud. For other types of instances, the default value is cloud_efficiency.

The name of the system disk. The name must be 2 to 128 characters in length and support Unicode characters under the Decimal Number category and the categories whose names contain Letter. The name can contain colons (:), underscores (_), periods (.), and hyphens (-).

The description of the system disk. The description must be 2 to 256 characters in length. The description can contain letters but cannot start with http:// or https://.

The performance level of the ESSD to use as the system disk. Default value: PL1. Valid values:

• PL0: A single ESSD can deliver up to 10,000 random read/write IOPS.
• PL1: A single ESSD can deliver up to 50,000 random read/write IOPS.
• PL2: A single ESSD can deliver up to 100,000 random read/write IOPS.
• PL3: A single ESSD can deliver up to 1,000,000 random read/write IOPS.

For more information about ESSD performance levels, see ESSDs .

The ID of the automatic snapshot policy to apply to the system disk.

Specifies whether the instance is I/O optimized. For instances of retired instance types, the default value is none. For instances of other instance types, the default value is optimized. Valid values:

• none: The instance is not I/O optimized.
• optimized: The instance is I/O optimized.

The user data of the instance. You must specify Base64-encoded data. The instance user data cannot exceed 32 KB in size before Base64 encoding.

For information about the limits, formats, and running frequencies of instance user data, see Instance user data.

The name of the key pair.

The name of the Resource Access Management (RAM) role. You can call the ListRoles operation provided by RAM to query the instance RAM roles that you created.

The desired number of ECS instances that you want to create. Valid values: 1 to 100.

The number of ECS instances that can be created varies based on the Amount and MinAmount values.

• If you do not specify MinAmount, the RunInstances operation creates ECS instances based on the Amount value. If the available resources are insufficient to create the desired number of ECS instances, the RunInstances operation returns an error response and no ECS instances are created.

• If you specify MinAmount, take note of the following items:

  • If the available resources are insufficient to create the minimum number of ECS instances, no ECS instances are created and the RunInstances operation returns an error response.
  • If the available resources are insufficient to create the desired number of ECS instances but are sufficient to create the minimum number of ECS instances, the RunInstances operation uses the available resources to create ECS instances and returns a success response. In this case, the number of ECS instances that can be created is less than the desired number of ECS instances.
  • If the available resources are sufficient to create the desired number of ECS instances, the RunInstances operation uses the available resources to create the desired number of ECS instances and returns a success response.

Default value: 1.

The minimum number of ECS instances that you want to create. Valid values: 1 to 100.

The number of ECS instances that can be created varies based on the Amount and MinAmount values.

• If you do not specify MinAmount, the RunInstances operation creates ECS instances based on the Amount value. If the available resources are insufficient to create the desired number of ECS instances, the RunInstances operation returns an error response and no ECS instances are created.

• If you specify MinAmount, take note of the following items:

  • If the available resources are insufficient to create the minimum number of ECS instances, no ECS instances are created and the RunInstances operation returns an error response.
  • If the available resources are insufficient to create the desired number of ECS instances but are sufficient to create the minimum number of ECS instances, the RunInstances operation uses the available resources to create ECS instances and returns a success response. In this case, the number of ECS instances that can be created is less than the desired number of ECS instances.
  • If the available resources are sufficient to create the desired number of ECS instances, the RunInstances operation uses the available resources to create the desired number of ECS instances and returns a success response.

The time when to automatically release the pay-as-you-go instance. Specify the time in the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. The time must be in UTC.

• If the value of seconds (ss) is not 00, the start time is automatically rounded to the nearest minute based on the value of minutes (mm).
• The specified time must be at least 30 minutes later than the current time.
• The specified time can be at most three years later than the current time.

The bidding policy for the pay-as-you-go instance. This parameter is valid only when the InstanceChargeType parameter is set to PostPaid. Valid values:

• NoSpot: The instance is created as a pay-as-you-go instance.
• SpotWithPriceLimit: The instance is created as a preemptible instance with a user-defined maximum hourly price.
• SpotAsPriceGo: The instance is created as a preemptible instance for which the market price at the time of purchase is automatically used as the bid price.

Default value: NoSpot.

The protection period of the preemptible instance. Unit: hours. Default value: 1. Valid values:

• 1: After a preemptible instance is created, Alibaba Cloud ensures that the instance is not automatically released within 1 hour. After the 1-hour protection period ends, the system compares the bid price with the market price and checks the resource inventory to determine whether to retain or release the instance.
• 0: After a preemptible instance is created, Alibaba Cloud does not ensure that the instance runs for 1 hour. The system compares the bid price with the market price and checks the resource inventory to determine whether to retain or release the instance.

Alibaba Cloud sends an ECS system event to notify you 5 minutes before the instance is released. Preemptible instances are billed by second. We recommend that you specify an appropriate protection period based on your business requirements.

The maximum hourly price of the instance. The value is accurate to three decimal places. This parameter is valid only when the SpotStrategy parameter is set to SpotWithPriceLimit.

The interruption mode of the preemptible instance. Valid values:

• Terminate: The instance is released.

• Stop: The instance is stopped in economical mode.

  For information about the economical mode, see Economical mode.

Default value: Terminate.

Specifies whether to enable security hardening. Valid values:

• Active: enables security hardening. This value is applicable only to public images.
• Deactive: does not enable security hardening. This value is applicable to all images.

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

The ID of the high performance computing (HPC) cluster to which the instance belongs.

This parameter is required when you create instances of a Supper Computing Cluster (SCC) instance type. For information about how to create an HPC cluster, see CreateHpcCluster .

Specifies whether to check the validity of the request without actually making the request. Default value: false. Valid values:

• true: The validity of the request is checked but the request is not made. Check items include whether required parameters are specified, the request format, service limits, and available ECS resources. If the check fails, the corresponding error code is returned. If the check succeeds, the DryRunOperation error code is returned.
• false: The validity of the request is checked, and the request is made if the check succeeds.

The ID of the dedicated host on which to create the instance. Preemptible instances cannot be created on dedicated hosts. If you specify DedicatedHostId, SpotStrategy and SpotPriceLimit are ignored.

You can call the DescribeDedicatedHosts operation to query the list of dedicated host IDs.

The ID of the launch template. For more information, call the DescribeLaunchTemplates operation.

To use a launch template to create an instance, you must use the LaunchTemplateId or LaunchTemplateName parameter to specify the launch template.

The name of the launch template.

To use a launch template to create an instance, you must use the LaunchTemplateId or LaunchTemplateName parameter to specify the launch template.

The version of the launch template. If you set the LaunchTemplateId or LaunchTemplateName parameter but do not set the version number of the launch template, the default template version is used.

The ID of the resource group to which to assign the instance.

The subscription period of the instance. The unit is specified by the PeriodUnit parameter. This parameter is valid and required only when InstanceChargeType is set to PrePaid. If the DedicatedHostId parameter is specified, the value of Period must not exceed the subscription period of the specified dedicated host. Valid values:

• Valid values when PeriodUnit is set to Week: 1, 2, 3, and 4.
• Valid values when PeriodUnit is set to Month: 1, 2, 3, 4, 5, 6, 7, 8, 9, 12, 24, 36, 48, and 60.

The unit of the subscription period. Default value: Month. Valid values:

• Week
• Month

Specifies whether to enable auto-renewal for the instance. This parameter is valid only when the InstanceChargeType parameter is set to PrePaid. Valid values:

• true: enables auto-renewal.
• false: does not enable auto-renewal.

Default value: false.

The auto-renewal period of the instance. Valid values:

• Valid values when PeriodUnit is set to Week: 1, 2, and 3.
• Valid values when PeriodUnit is set to Month: 1, 2, 3, 6, 12, 24, 36, 48, and 60.

Default value: 1.

The billing method of the instance. Valid values:

• PrePaid: subscription
• PostPaid: pay-as-you-go

Default value: PostPaid.

If you set this parameter to PrePaid, make sure that your account has sufficient balance or credit. Otherwise, an InvalidPayMethod error is returned.

The ID of the deployment set to which to deploy the instance.

The number of the deployment set group to which to deploy the instance. If the deployment set specified by the DeploymentSetId parameter uses the high availability group strategy (AvailabilityGroup), you can use the DeploymentSetGroupNo parameter to specify a deployment set group in the deployment set. Valid values: 1 to 7.

The private IP address to assign to the instance. To assign a private IP address to an instance that resides in a VPC, make sure that the IP address is an idle IP address within the CIDR block of the vSwitch specified by VSwitchId.

Take note of the following items:

• If PrivateIpAddress is specified, take note of the following items:

  • If Amount is set to 1, a single instance is created and the specified private IP address is assigned to the instance.
  • If Amount is set to a numeric value greater than 1, the specified number of instances are created and consecutive private IP addresses starting from the specified one are assigned to the instances. In this case, you cannot specify parameters that start with NetworkInterface.N to attach secondary ENIs to the instances.

• If NetworkInterface.N.InstanceType is set to Primary, you cannot specify PrivateIpAddress but can specify NetworkInterface.N.PrimaryIpAddress.

The performance mode of the burstable instance. Valid values:

• Standard: the standard mode. For more information, see the "Standard mode" section in Overview of burstable instances.
• Unlimited: the unlimited mode. For more information, see the "Unlimited mode" section in Burstable instances.

The number of IPv6 addresses to randomly generate for the primary ENI. Valid values: 1 to 10.

Take note of the following items:

• You cannot specify both the Ipv6Addresses.N and Ipv6AddressCount parameters.
• If NetworkInterface.N.InstanceType is set to Primary, you cannot specify Ipv6Address.N or Ipv6AddressCount but can specify NetworkInterface.N.Ipv6Address.N or NetworkInterface.N.Ipv6AddressCount.

The number of queues supported by the primary ENI. Take note of the following items:

• The value of this parameter cannot exceed the maximum number of queues per ENI allowed for the instance type.
• The total number of queues for all ENIs on the instance cannot exceed the queue quota for the instance type. To query the maximum number of queues per ENI and the queue quota for an instance type, you can call the DescribeInstanceTypes operation to query the MaximumQueueNumberPerEni and TotalEniQueueQuantity values.
• If NetworkInterface.N.InstanceType is set to Primary, you cannot specify NetworkInterfaceQueueNumber but can specify NetworkInterface.N.QueueNumber.

Specifies whether to enable release protection for the instance. This parameter determines whether you can use the ECS console or call the DeleteInstance operation to release the instance. Valid values:

• true: enables release protection for the instance.
• false: disables release protection for the instance.

Default value: false.

Specifies whether to associate an instance on a dedicated host with the dedicated host. Valid values:

• default: does not associate the instance with the dedicated host. When you start an instance that was stopped in economical mode, the instance is automatically deployed to another dedicated host in the automatic deployment resource pool if the available resources of the original dedicated host are insufficient.
• host: associates the instance with the dedicated host. When you start an instance that was stopped in economical mode, the instance remains on the original dedicated host. If the available resources of the original dedicated host are insufficient, the instance cannot be started.

Default value: default.

Specifies whether to create the instance on a dedicated host. Valid values:

• default: creates the instance on a non-dedicated host.
• host: creates the instance on a dedicated host. If you do not set the DedicatedHostId parameter, Alibaba Cloud selects a dedicated host for the instance.

Default value: default.

The ID of the storage set.

The maximum number of partitions in the storage set. Valid values: greater than or equal to 2.

The number of CPU cores. This parameter cannot be specified but only uses its default value.

For information about the default value, see Customize CPU options.

The number of threads per CPU core. The following formula is used to calculate the number of vCPUs of the instance: CpuOptions.Core value × CpuOptions.ThreadsPerCore value.

• If CpuOptionsThreadPerCore is set to 1, Hyper-Threading (HT) is disabled.
• This parameter is applicable only to specific instance types.

This parameter is no longer used.

The CPU topology type of the instance. Valid values:

• ContinuousCoreToHTMapping: The HT technology allows continuous threads to run on the same core in the CPU topology of the instance.``
• DiscreteCoreToHTMapping: The HT technology allows discrete threads to run on the same core in the CPU topology of the instance.``

This parameter is empty by default.

The trusted system mode. Set the value to vTPM.

The trusted system mode supports the following instance families:

• g7, c7, and r7
• Security-enhanced instance families: g7t, c7t, and r7t

When you create instances of the preceding instance families, you must set this parameter. Take note of the following items:

• To use the Alibaba Cloud trusted system, set this parameter to vTPM. Then, the Alibaba Cloud trusted system performs trust verifications when the instances start.
• If you do not want to use the Alibaba Cloud trusted system, leave this parameter empty. Note that if your created instances use an enclave-based confidential computing environment (with SecurityOptions.ConfidentialComputingMode set to Enclave), the Alibaba Cloud trusted system is enabled for the instances.
• When you use the ECS API to create instances that use the trusted system, you can call only the RunInstances operation. The CreateInstance operation does not support the SecurityOptions.TrustedSystemMode parameter.

For more information about the trusted system, see Overview .

The confidential computing mode. Set the value to Enclave.

A value of Enclave indicates that an enclave-based confidential computing environment is built on the instance. When you call the RunInstances operation, you can set this parameter only for c7, g7, or r7 instances to use enclave-based confidential computing. Take note of the following items:

• The confidential computing feature is in invitational preview.
• When you use the ECS API to create instances that support enclave-based confidential computing, you can call only the RunInstances operation. The CreateInstance operation does not support the SecurityOptions.ConfidentialComputingMode parameter.
• Enclave-based confidential computing is implemented based on Alibaba Cloud Trusted System (vTPM). When you build a confidential computing environment on an instance by using Enclave, Alibaba Cloud Trusted System is enabled for the instance. If you set SecurityOptions.ConfidentialComputingMode to Enclave when you call this operation, the created instances use enclave-based confidential computing and Alibaba Cloud Trusted System regardless of whether SecurityOptions.TrustedSystemMode is set to vTPM.

For more information about confidential computing, see Build a confidential computing environment by using Enclave.

Specifies whether to enable the access channel for instance metadata. Valid values:

• enabled
• disabled

Default value: enabled.

Specifies whether to forcefully use the security-enhanced mode (IMDSv2) to access instance metadata. Valid values:

• optional: does not forcefully use the security-enhanced mode (IMDSv2).
• required: forcefully uses the security-enhanced mode (IMDSv2). After you set this parameter to required, you cannot access instance metadata in normal mode.

Default value: optional.

The HTTP PUT response hop limit for accessing instance metadata. Valid values: 1 to 64.

Default value: 1.

The type of the private pool to use to create the instance. A private pool is generated after an elasticity assurance or a capacity reservation takes effect. You can select the private pool when you start an instance. Valid values:

• Open: open private pool. The system selects a matching open private pool to create the instance. If no matching open private pools are found, resources in the public pool are used. When you set this parameter to Open, you can leave the PrivatePoolOptions.Id parameter empty.
• Target: specified private pool. The system uses the capacity in a specified private pool to create the instance. If the specified private pool is unavailable, the instance cannot be created. If you set this parameter to Target, you must specify the PrivatePoolOptions.Id parameter.
• None: no private pool. The capacity in private pools is not used.

Default value: None.

In the following scenarios, the PrivatePoolOptions.MatchCriteria parameter can be set only to None or left empty:

• A preemptible instance is created.
• The instance is created in the classic network.
• The instance is created on a dedicated host.

The ID of the private pool. The ID of a private pool is the same as that of the elasticity assurance or capacity reservation for which the private pool is generated.

The ID of the dedicated host cluster in which to create the instance. After this parameter is specified, the system selects one dedicated host from the specified cluster to create the instance.

When you specify both the DedicatedHostId and SchedulerOptions.DedicatedHostClusterId parameters, take note of the following items:

• If the specified dedicated host belongs to the specified dedicated host cluster, the instance is preferentially deployed on the specified dedicated host.
• If the specified dedicated host does not belong to the specified dedicated host cluster, the instance cannot be created.

You can call the DescribeDedicatedHostClusters operation to query the list of dedicated host cluster IDs.

The ID of security group N to which to assign the instance. The valid values of N vary based on the maximum number of security groups to which an instance can belong. For more information, see the Security group limits section of the "Limits" topic.

Take note of the following items:

• You cannot specify both SecurityGroupId and SecurityGroupIds.N in the same request.
• If NetworkInterface.N.InstanceType is set to Primary, you cannot specify SecurityGroupId or SecurityGroupIds.N but can specify NetworkInterface.N.SecurityGroupId or NetworkInterface.N.SecurityGroupIds.N.

The hostname of instance N. You can use this parameter to specify different hostnames for multiple instances.

The data disks.

The information of the elastic network interfaces (ENIs).

The tags to add to the instance, disks, and primary ENI.

IPv6 address N to be assigned to the primary ENI. Valid values of N: 1 to 10.

Example: Ipv6Address.1=2001:db8:1234:1a00::***.

Take note of the following items:

• If the Ipv6Address.N parameter is specified, you must set the Amount parameter to 1 and leave the Ipv6AddressCount parameter empty.
• If NetworkInterface.N.InstanceType is set to Primary, you cannot set Ipv6Addresses.N or Ipv6AddressCount and must set NetworkInterface.N.Ipv6Addresses.N or NetworkInterface.N.Ipv6AddressCount.

The parameters related to the system disk. You can use StorageClusterId to specify the ID of a dedicated block storage cluster.

Details about the image options.

Details about network options.

Specifies whether to automatically complete the payment for instance creation. Valid values:

• true: The payment is automatically completed.

  **

  Note Make sure that your account balance is sufficient. Otherwise, your order becomes invalid and is canceled. If your account balance is insufficient, you can set AutoPay to false to generate an unpaid order. Then, you can log on to the ECS console to pay for the order.

• false: An order is generated but no payment is made.

  **

  Note When InstanceChargeType is set to PostPaid, AutoPay cannot be set to false.

Default value: true.