You can call this operation to create one or more subscription dedicated hosts. Alibaba Cloud Dedicated Host provides dedicated physical resources for each tenant. You can create Elastic Compute Service (ECS) instances on a dedicated host and obtain the attributes of the physical servers.

Description

Before you create a dedicated host, you can call the DescribeAvailableResource operation to view the available resources in the specified region or zone.

When you create a dedicated host, fees apply for resources used by the dedicated host. We recommend that you learn more about the billing methods for dedicated hosts before you create a dedicated host. For more information, see Billing overview.

  • You can create a maximum of 100 subscription dedicated hosts at a time.
  • After one or more dedicated hosts are created, a dedicated host ID list is returned. You can call the DescribeDedicatedHosts operation to query the status of a dedicated host.
  • If the status of the created dedicated host is Available, you can then create ECS instances on the dedicated host. For more information about the life cycle of a dedicated host, see Life cycle of a dedicated host.
  • After you submit a dedicated host creation task, an error may occur if the parameters are invalid or the dedicated host resources are insufficient. For more information, see Error codes.
  • After a dedicated host is created, you can call the ModifyInstanceDeployment operation to migrate ECS instances from a shared host to the created dedicated host. You can also migrate ECS instances from another dedicated host to the created dedicated host.

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
DedicatedHostType String Yes ddh.c5

The type of the dedicated host. You can call DescribeDedicatedHostTypes to obtain the latest dedicated host type list.

RegionId String Yes cn-hangzhou

The region ID of the dedicated host. You can call the DescribeRegions operation to query the latest region list.

Action String No AllocateDedicatedHosts

The operation that you want to perform. Set this parameter to AllocateDedicatedHosts.

ActionOnMaintenance String No Migrate

The policy used to migrate the instances from the dedicated host when the dedicated host fails or needs to be repaired online. Valid values:

  • Migrate: Instances are migrated to another physical server and restarted.

    If the dedicated host is attached with disks that are not local disks, the default value is Migrate.

  • Stop: Instances on the dedicated host are stopped. If the dedicated host cannot be repaired, the instances are migrated to another physical server and restarted.

    If the dedicated host is attached with local disks, the default value is Stop.

AutoPlacement String No off

Specifies whether the dedicated host is added to the resource pool for automatic deployment. If you do not specify the DedicatedHostId parameter when you create an instance on a dedicated host, Alibaba Cloud automatically selects a dedicated host from the resource pool to host the instance. For more information, see Automatic deployment. Valid values:

  • on: The dedicated host is added to the resource pool for automatic deployment.
  • off: The dedicated host is not added to the resource pool for automatic deployment.

Default value: on.

Note When you create a dedicated host:
  • If you do not specify this parameter, the dedicated host is added to the automatic deployment resource pool.
  • If you do not want to add the dedicated host to the automatic deployment resource pool, set the value to off.
AutoReleaseTime String No 2019-08-21T12:30:24Z

The automatic release time of the dedicated host. Specify the time in the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. The time must be in UTC+0. The format is YYYY-MM-DDThh:mm:ssZ.

Note
  • It must be at least half an hour later than the current time.
  • It cannot be more than three years later than the current time.
  • If the value of the seconds (ss) is not 00, it is automatically set to 00.
AutoRenew Boolean No false

Specifies whether the subscription dedicated host is automatically renewed.

Note The AutoRenew parameter only takes effect when the ChargeType parameter is set to PrePaid.

Default value: false.

AutoRenewPeriod Integer No 1

The auto-renewal period of the dedicated host. Unit: months. Valid values: 1, 2, 3, 6, and 12.

Note The AutoRenewPeriod parameter is only required and takes effect when the AutoRenew parameter is set to true.
ChargeType String No PrePaid

The billing method of the dedicated host. Valid values: PrePaid (subscription).

ClientToken String No 123e4567-e89b-12d3-a456-426655440000

The client token that is used to ensure the idempotence of the request. The value of this parameter is generated by the client and is unique among different requests. It can contain a maximum of 64 ASCII characters. For more information, see How to ensure idempotence.

DedicatedHostName String No myDDH

The name of the dedicated host. It must be 2 to 128 characters in length. It must start with a letter but cannot start with http:// or https://. It can contain letters, digits, colons (:), underscores (_), and hyphens (-).

Description String No This-is-my-DDH

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

NetworkAttributes.SlbUdpTimeout Integer No 60

The duration of UDP timeout for sessions between Server Load Balancer (SLB) and the dedicated host. Unit: seconds. Valid values: 15 to 310.

NetworkAttributes.UdpTimeout Integer No 60

The duration of UDP timeout for sessions between users and instances on the dedicated host. Unit: seconds. Valid values: 15 to 310.

Period Integer No 6

The subscription duration of the dedicated host. The Period parameter takes effect and is only required when the ChargeType parameter is set to PrePaid.

If you use an account of the China site to call this operation, the Period parameter has the following valid values:

  • PeriodUnit=Week:1, 2, and 3.
  • PeriodUnit=Month:1, 2, 3, 4, 5, 6, 7, 8, and 9.
  • PeriodUnit=Year:1, 2, 3, 4, and 5.

If you use an account of the international site to call this API, the Period parameter has the following valid values:

  • PeriodUnit=Month:1, 2, 3, and 6.
  • PeriodUnit=Year:1.
PeriodUnit String No Month

The subscription period of the dedicated host. Valid values: Month and Year. Default value: Month.

Quantity Integer No 1

The number of dedicated hosts that you want to create. Valid values: 1 to 100.

Default value: 1.

ResourceGroupId String No myResourceGroupID

The ID of the resource group to which the dedicated host belongs.

Tag.N.Key String No Environment

The Nth tag key of the dedicated host. Valid values of N: 1 to 20. It cannot be a null string. It can be a maximum of 64 characters in length and it cannot start with aliyun, acs:, http://, or https://.

Tag.N.Value String No Production

The Nth tag value of the dedicated host. Valid values of N: 1 to 20. It can be a null string. Each value of this parameter can be up to 64 characters in length. It cannot start with aliyun, acs:, http://, or https://.

ZoneId String No cn-hangzhou-f

The zone ID of the dedicated host.

If you do not specify a zone, the system automatically selects a zone.

Response parameters

Parameter Type Example Description
DedicatedHostIdSets "DedicatedHostIdSets":{ "DedicatedHostId":[ "dh-dedicatedhost1", "dh-dedicatedhost2" ]

The list of dedicated host IDs (DedicatedHostId).

DedicatedHostId

The ID of a dedicated host.

RequestId String E2A664A6-2933-4C64-88AE-5033D003EADF

The ID of the request.

Examples

Sample requests


https://ecs.aliyuncs.com/?Action=AllocateDedicatedHosts
&RegionId=cn-hangzhou
&DedicatedHostType=ddh.sn1ne
&Quantity=2
&<Common request parameters>

Sample success responses

XML format

<AllocateDedicatedHostsResponse>
    <RequestId> E2A664A6-2933-4C64-88AE-5033D003EADF </RequestId>
    <DedicatedHostIdSets>
        <DedicatedHostId>dh-dedicatedhost1</DedicatedHostId>
        <DedicatedHostId>dh-dedicatedhost2</DedicatedHostId>
    </DedicatedHostIdSets>
</AllocateDedicatedHostsResponse>

JSON format

{
	"RequestId":"E2A664A6-2933-4C64-88AE-5033D003EADF",
	"DedicatedHostIdSets":{
		"DedicatedHostId":[
			"dh-dedicatedhost1",
			"dh-dedicatedhost2"
		]
	}
}

Error codes

HTTP status code Error code Error message Description
400 InvalidInstanceType.ValueUnauthorized The specified InstanceType is not authorized. The error message returned because you are not authorized to use the specified instance type.
400 InvalidDescription.Malformed The specified parameter "Description" is not valid. The error message returned because the specified description is invalid. The description must be 2 to 256 characters in length and cannot start with http:// or https://.
403 OperationDenied The creation of Host to the specified Zone is not allowed. The error message returned because you are not authorized to create a dedicated host in the specified zone.
403 OperationDenied.NoStock The requested resource is sold out in the specified zone; try other types of resources or other regions and zones. The error message returned because of insufficient inventory for the requested resource. Try again with other resource types, regions, or zones.
500 InternalError The request processing has failed due to some unknown error. The error message returned because an internal error has occurred. Try again later. If the problem persists, submit a ticket.
403 OperationDenied Sales of this resource are temporarily suspended in the specified region; please try again later. The error message returned because the sales of the specified resources in the specified region are disabled.
400 InvalidParameter.Conflict The specified region and cluster do not match. The error message returned because the specified region does not match the specified cluster.
403 NodeControllerUnavailable The Node Controller is temporarily unavailable. The error message returned because the node controller is currently unavailable.
404 OperationDenied Another Host has been creating The error message returned because the dedicated host is being created.
403 OperationDenied The resource is out of usage. The error message returned because the instance is not in the running state. Enable the instance or check whether the operation is performed correctly.
404 PaymentMethodNotFound No payment method has been registered on the account. The error message returned because you have not registered the payment method for your account.
404 InvalidDedicatedHostName.Malformed The specified parameter DedicatedHostName is not valid. The error message returned because the specified DedicatedHostId is invalid.
403 InvalidParameter.ResourceOwnerAccount ResourceOwnerAccount is Invalid. The error message returned because the specified ResourceOwnerAccount parameter is invalid.
403 InvalidUserData.Forbidden User not authorized to input the parameter "UserData", please apply for permission "UserData" The error message returned because you are not authorized to configure the UserData.
403 Zone.NotOpen The specified zone is not granted to you to buy resources yet. The error message returned because you are not authorized to purchase resources in the specified zone.
403 Zone.NotOnSale The specified zone is not available for purchase. The error message returned because the requested instance resources are unavailable in the specified zone. Change the instance type or select a different zone.
403 InvalidResourceType.NotSupported This resource type is not supported; please try other resource types. The error message returned because the specified resource type is out of stock.
403 InvalidDedicatedHostType.ValueNotSupported The specified DedicatedHostType does not exist or beyond the permitted range. The error message returned when the specified dedicated host type does not exist.
403 InvalidDedicatedHostType.ZoneNotSupported The specified zone does not support this dedicatedHostType. The error message returned when the specified dedicated host type is not supported in the specified zone.
400 InvalidAutoRenewPeriod.ValueNotSupported The specified autoRenewPeriod is not valid. The error message returned because the specified AutoRenewPeriod is invalid.
403 InvalidUserData.Base64FormatInvalid The specified Usage is not valid The error message returned because the specified UserData is invalid.
400 InvalidTagKey.Malformed The specified Tag.n.Key is not valid. The error message returned because the specified Tag.N.Value is invalid.
400 InvalidDedicatedHostType.ValueNotSupported %s The error message returned because the specified instance type does not support this operation.
400 RegionUnauthorized %s The error message returned because the specified region is not supported.
500 InternalError %s The error message returned because an internal error has occurred. Try again later.
400 Zone.NotOnSale %s The error message returned because the specified zone is disabled.
400 OperationDenied The specified DedicatedHostType or Zone is not available or not authorized. The error message returned when the specified dedicated host type or the zone is unavailable.
400 InvalidPeriodUnit.ValueNotSupported The specified parameter PeriodUnit is not valid. The error message returned because the specified PeriodUnit is invalid.
400 InvalidTagValue.Malformed The specified Tag.n.Value is not valid. The error message returned because the specified Tag.N.Value is invalid.
403 InvalidParameter.NotMatch %s The error message returned because the parameter conflicts with another parameter.
403 Account.Arrearage Your account has been in arrears. The error message returned because your account balance is insufficient. You must add funds to your account before you proceed.
400 QuotaExceed.AfterpayDedicatedHost The maximum number of Pay-As-You-Go DedicatedHosts is exceeded: %s The error message returned because the number of pay-as-you-go dedicated hosts exceeds the upper limit
400 InvalidChargeType.ValueNotSupported ChargeType is not valid. The error message returned because the billing method is invalid.
400 InvalidParameter.SlbUdpTimeout The specified value is invalid. The error message returned because the SlbUdpTimeout parameter is invalid.
400 InvalidParameter.UdpTimeout The specified value is invalid. The error message returned because the UdpTimeout parameter is invalid.
400 Duplicate.TagKey The Tag.N.Key contain duplicate key. The error message returned because the specified tag key is repeated.

For more information about error codes, see API Error Center.