Call the AllocateDedicatedHosts operation to apply for one or multiple subscription-based DDHs.

Usage notes

Creating DDHs incurs charges. We recommend that you understand the resource billing methods in advance. For more information, see DDH and instance billing.

After creating a DDH, you can call the RunInstances operation to create one or more ECS instances on it for hosting your workloads. These instances will have exclusive access to the physical resources of the host.

You can also call the ModifyInstancePlacement operation to migrate an ECS instance from a shared host to a DDH, or to move instances between different DDHs.

Debugging

API Explorer

You can initiate calls online through API Explorer without paying attention to the signature generation process and quickly obtain the call results.

Go to debug

Request parameters

Only the request parameters specific to this operation and some common parameters are listed below. For more information, please refer to Common parameters.

Action string required Sample value: AllocateDedicatedHosts

The action that you want to perform. Value: AllocateDedicatedHosts.

Version string required Sample value: 2020-04-01

The API version. Valid value: 2020-04-01.

AutoPlacement string Optional Sample value: Off

Specifies whether to add the DDH to the automatic deployment pool. Valid values:

On: Adds the DDH to the automatic deployment pool. When you create an instance without specifying a DDH, the system will automatically select a suitable DDH from this pool for instance deployment.

Off (default): Does not add the DDH to the automatic deployment pool. You need to manually deploy the instance on a DDH by specifying the DDH when creating the instance.

For the operations of creating an instance, refer to RunInstances.

AutoRenew boolean Optional Sample value: true

Indicates whether to automatically renew the DDH upon expiration.

true: Enables automatic renewal

false (default): Disables automatic renewal

AutoRenewPeriod integer Optional Sample value: 1

The renewal length for each automatic renewal.

When AutoRenew is set to True, this parameter is valid.

When the value of PeriodUnit is Month, the value of AutoRenewPeriod can be 1, 2, 3, 6, or 12. The default value is 1.

ChargeType string Optional Sample value: PostPaid

The billing method of the DDH. Valid values:

PrePaid: Subscription.

ClientToken string Optional Sample value: 333456899ff****

The ClientToken is used to ensure the request idempotency. You can use the client to automatically generate a token, but you must make sure that the token is unique among different requests. This prevents repeated actions due to multiple client retries when the call of the API operation times out or an internal server error occurs.

Value: Only ASCII characters are supported. The length is no more than 64 ASCII characters.

Count integer Optional Sample value: 1

The number of DDHs to be created. Value range: 1–100.

The value defaults to 1 if you enter a value of 0.

CpuOvercommitRatio double Optional Sample value: 4

CPU oversubscription ratio, used to increase the available vCPUs of the DDH. The available vCPUs of a DDH = Number of physical CPU cores * 2 * CPU oversubscription ratio.

Value range: 1–4.

Default value: The maximum oversubscription ratio supported.

DedicatedHostClusterId string Optional Sample value: dc-ycle6b76kgv2wrsm****

The ID of the dedicated host cluster.

You can call DescribeDedicatedHostClusters to query DDH clusters.

DedicatedHostName string required Sample value: dedicated-host-test

The name of the DDH.

Cannot start with a number, underscore "_", or hyphen "-".

Can only contain Chinese characters, letters, digits, underscores "_" and hyphens "-"

The length limit is 1 to 128 characters.

Special characters are currently not supported.

DedicatedHostRecovery string Optional Sample value: On

Specifies whether to enable automatic migration upon a DDH failure when the DDH enters the TempUnavailable (temporarily unavailable) state. Valid values:

On: Enables automatic migration when the DDH fails. After this feature is enabled, when the DDH fails, instances will be automatically migrated to a healthy DDH.

Off (default): Does not enable automatic migration when the DDH fails. You can call RedeployDedicatedHost to manually replace the host.

DedicatedHostTypeId string required Sample value: ecs.ddhr2s

The DDH type.

To obtain the DDH type, call the DescribeDedicatedHostTypes operation.

Description string Optional Sample value: DDH for testing

Description of the DDH. Default value: empty string.

Start with a letter or Chinese character only.

Only Chinese characters, letters, numbers, dots (.), spaces, underscores (_), hyphen (-), equal signs (=), English comma (,), Chinese comma (，), and Chinese period (。) are allowed.

The length is limited to 255 characters.

DryRun boolean Optional Sample value: false

Whether to only precheck this request. Value:

true: Sends a check request without creating the DDH. Check items include whether the required parameters are provided, the request format, business limits, and resource inventory. If the check fails, the corresponding error is returned. If the check passes, the error code DryRunOperation is returned.

tip

When the value of DryRun is true, if the Count parameter is specified, its value must be 1.

false (default): Sends a normal request and directly creates a DDH after the check passes.

Period integer Optional Sample value: 12

The subscription duration of resource (unit: month).

Values: 1, 2, 3, 4, 5, 6, 7, 8, 9, 12, 24, 36

PeriodUnit string Optional Sample value: Month

The unit of the resource subscription duration.

Value: Month

ZoneId stringrequired Sample value: cn-beijing-a

The ID of the availability zone where the DDH is deployed.

You can call the DescribeZones operation to query the availability zones in the same region.

Response parameters

Only the response parameters specific to this operation are listed below. For more information, refer to response structure.

DedicatedHostIds string[] Sample value: [dh-3tigy72q3u3vj0x2**** ]

Dedicated host ID.

Sample request

Sample response

Error codes

The table below lists the business-related error codes of the operation. For more information, refer to Common error codes.

Status code	Error code	Error message	Description
400	IdempotentParameterMismatch	The request uses the same client token as a previous, but non-identical request. Do not reuse a client token with different requests, unless the requests are identical.	The idempotent parameters are inconsistent.
400	Insufficient.Balance	The request is denied due to the lack of balance.	The account balance is insufficient.
400	InvalidArgument	The specified argument is invalid.	The specified parameter is invalid.
400	InvalidAutoPlacement.Malformed	The specified AutoPlacement is malformed.	The specified AutoPlacement value is invalid.
400	InvalidChargeType.Malformed	The specified ChargeType is malformed.	The specified billing method is invalid.
400	InvalidClientToken.Malformed	The specified ClientToken is malformed.	The specified ClientToken is invalid.
400	InvalidCount.Malformed	The specified count is malformed.	The specified Count is invalid.
400	InvalidCpuOvercommitRatio.Malformed	The specified CpuOvercommitRatio is malformed.	The specified oversubscription ratio is invalid.
400	InvalidDedicatedHostName.Malformed	The specified DedicatedHostName is malformed.	The specified DedicatedHostName value is invalid.
400	InvalidDedicatedHostRecovery.Malformed	The specified DedicatedHostRecovery is malformed.	The specified DedicatedHostRecovery value is invalid.
400	InvalidDescription.Malformed	The specified Description is malformed.	The specified description is invalid.
400	InvalidPeriod.Malformed	The specified period is malformed.	The specified billing cycle is invalid.
400	InvalidPeriodUnit.Malformed	The specified PeriodUnit is malformed.	The specified billing cycle is invalid.
400	MissingParameter.DedicatedHostName	The required parameter DedicatedHostName is not supplied.	The parameter DedicatedHostName cannot be empty.
400	MissingParameter.DedicatedHostTypeId	The required parameter DedicatedHostTypeId is not supplied.	The parameter DedicatedHostTypeId cannot be empty.
400	MissingParameter.ZoneId	The required parameter ZoneId is not supplied.	Availability zone ID can not be empty.
400	QuotaExceeded.MaximumDedicatedHosts	You've reached the limit on the number of dedicated hosts that you can allocate, please submit ticket to request an increase in quota.	Insufficient quota for DDH types. Please submit a ticket to request a quota increase.
400	QuotaExceeded.MaximumGeneralCpus	You've reached the limit on the number of general instances CPU that you can create, please submit ticket or sign-on to the Console to request an increase in [general_vcpu] quota.	The CPU quota of the General-purpose instances is insufficient. Please submit a ticket or go to the console to request a quota increase.
400	QuotaExceeded.MaximumGpuBasicNums	You've reached the limit on the GPU number of GPU-accelerated instances that you can create, please submit ticket or sign-on to the Console to request an increase in [gpu_basic] quota.	The GPU card quota for GPU Accelerated instances is insufficient. Please submit a ticket or go to the console to request a quota increase.
400	QuotaExceeded.MaximumHighPerformanceGpus	You've reached the limit on the GPU number of High Performance Computing GPU instances that you can create, please submit ticket or sign-on to the Console to request an increase in [gpu_high_performance] quota.	The GPU card quota for HPC-optimized instances is insufficient. Please submit a ticket or go to the console to request a quota increase.
400	QuotaExceeded.MaximumLocalVolumeCpus	You've reached the limit on the number of local volume instances CPU that you can create, please submit ticket or sign-on to the Console to request an increase in [local_volume_vcpu] quota.	The CPU quota of the Local SSD instances is insufficient. Please submit a ticket or go to the console to request a quota increase.
400	QuotaExceeded.MaximumReservedInstanceGeneralCpus	You've reached the limit on the number of general reserved instances CPU that you can create, please submit ticket or sign-on to the Console to request an increase in [general_vcpu_ri_regional] quota.	The CPU quota of the general-purpose instances that can be deducted by regional RIs is insufficient. Please submit a ticket or go to the console to request a quota increase.
400	QuotaExceeded.MaximumReservedInstanceGpuBasicNums	You've reached the limit on the GPU number of GPU-accelerated reserved instances that you can create, please submit ticket or sign-on to the Console to request an increase in [gpu_basic_ri_regional] quota.	The GPU card quota of regional RIs that can be used for purchasing GPU Accelerated instances is insufficient. Please submit a ticket or go to the console to request a quota increase.
400	QuotaExceeded.MaximumReservedInstanceHighPerformanceGpus	You've reached the limit on the GPU number of High Performance Computing GPU reserved instances that you can create, please submit ticket or sign-on to the Console to request an increase in [gpu_high_performance_ri_regional] quota.	The GPU card quota for HPC-optimized instances that can be deducted by regional RIs is insufficient. Please submit a ticket or go to the console to request a quota increase.
400	QuotaExceeded.MaximumReservedInstanceLocalVolumeCpus	You've reached the limit on the number of local volume reserved instances CPU that you can create, please submit ticket or sign-on to the Console to request an increase in [local_volume_vcpu_ri_regional] quota.	The CPU quota of regional RIs that can be used for purchasing Local SSD instances is insufficient. Please submit a ticket or go to the console to request a quota increase.
404	InvalidDedicatedHostCluster.NotFound	The specified dedicated host cluster does not exist.	The specified dedicated host cluster does not exist.
404	InvalidDedicatedHostType.NotFound	The specified DedicatedHostTypeId does not exist.	The specified DDH type does not exist.
404	InvalidZone.NotFound	The specified zone does not exist.	The specified availability zone does not exist.
412	DryRunOperation	Your request has been validated by the DryRunOperation.	Your request has been validated by "DryRun".
412	IdempotentProcessing	The request uses the same client token as a previous one that is still in process.	The previous idempotent request is still in process. Please try again later.
500	Insufficient.DedicatedHostCapacity	There is not enough capacity to fulfill your request.	The resources are currently insufficient. Try again later or select other dedicated host types.
500	InternalError	An internal error has occurred.	An internal error occurred. Try again. If multiple attempts fail, submit a ticket.

Elastic Compute Service