Help Center/ Cloud Data Center / API Reference/ API/ iMetal Instance Management/ Creating an Instance
Updated on 2025-12-12 GMT+08:00
Online Debugging
CLI Examples
View PDF
Share

Creating an Instance

Function

This API is used to create an instance with more custom parameters, such as an IP address.

The following scheduling policies are supported:

  1. Scheduling to selected servers

  2. Random scheduling to idle servers

VPC and AI parameter plane networks can be configured.

This API is asynchronous. The instance creation and startup are not completed immediately. You can call the ShowInstanceStatus API to check whether the instance status is running. If it is, the instance has been created.

Constraint: The value of manage_state for the instances must be ready.

Calling Method

For details, see Calling APIs.

URI

POST /v1/{project_id}/instances

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Definition

Project ID.

Constraints

N/A

Range

Project ID of the account.

Default Value

N/A

Request Parameters

Table 2 Request header parameters

Parameter

Mandatory

Type

Description

X-Auth-Token

Yes

String

Definition

Requests for calling an API can be authenticated using a token. If token-based authentication is used, this parameter is mandatory and must be set to a user token.

Constraints

N/A

Range

N/A

Default Value

N/A
Table 3 Request body parameters

Parameter

Mandatory

Type

Description

name

Yes

String

Definition

The hostname of an instance.

Constraints

N/A

Range

Length: 1 to 63 characters. Only letters (case-sensitive), digits, underscores (_), hyphens (-), and periods (.) are allowed.

Default Value

N/A

image_id

Yes

String

Definition

Image ID, which is the ID of the private image created in IMS. You can view the ID on the CloudDC console or query the ID using the IMS API.

Constraints

N/A

Range

N/A

Default Value

N/A

vpc_id

Yes

String

Definition

ID of the VPC which the network interface to be created belongs to. You can query the ID using the VPC API: https://support.huaweicloud.com/intl/en-us/api-vpc/vpc_api01_0003.html.

Constraints

N/A

Range

VPC ID

Default Value

N/A

network_interfaces

Yes

Array of NetworkInterface objects

Definition

Network interface information about the specified iMetal server.

Constraints

A maximum of two network interfaces can be attached to an iMetal server, and the first one serves as the primary network interface. If multiple network interfaces are specified, ensure that all network interfaces belong to the same VPC.

password

Yes

String

Definition

Initial login password of the administrator account. For Linux, the administrator is root. For Windows, the administrator is Administrator.

Constraints

N/A

Range

8 to 26 characters

The password must contain at least three of the following character types: uppercase letters, lowercase letters, digits, and special characters !@$%^-_=+[{}]:,./?

The password cannot contain the username or the username spelled backwards.

Default Value

N/A

metadata

No

Map<String,String>

Definition

Metadata for creating an iMetal instance. You can use metadata to customize key-value pairs.

If the metadata contains sensitive data, take appropriate measures to protect the sensitive data, for example, controlling access permissions and encrypting the data.

Constraints

N/A

Range

A maximum of 10 key-value pairs can be injected.

A metadata key consists of 1 to 255 characters and can only contain uppercase letters, lowercase letters, spaces, digits, hyphens (-), underscores (_), colons (:), and periods (.).

A metadata value consists of a maximum of 255 characters.

Default Value

N/A

description

No

String

Definition

Description of an iMetal instance.

Constraints

N/A

Range

Maximum length: 255 characters

Default Value

Empty string

placement

No

placement object

Definition

Instance placement, which is a policy for specifying servers. If placement is not specified, idle servers are selected based on min_count and max_count.

Constraints

N/A
Table 4 NetworkInterface

Parameter

Mandatory

Type

Description

subnet_id

Yes

String

Definition

CloudDCN subnet ID, which is obtained from the CloudDCN cloud network.

Constraints

N/A

Range

N/A

Default Value

N/A

ipv4_address

No

String

Definition

Private IPv4 address of an elastic network interface.

Constraints

N/A

Range

N/A

Default Value

N/A
Table 5 placement

Parameter

Mandatory

Type

Description

server_id

No

String

Response Parameters

Status code: 202

Table 6 Response body parameters

Parameter

Type

Description

instance_id

String

Instance ID.

Status code: 400

Table 7 Response body parameters

Parameter

Type

Description

error_code

String

Definition

Error code.

error_msg

String

Definition

Error description.

Status code: 401

Table 8 Response body parameters

Parameter

Type

Description

error_code

String

Definition

Error code.

error_msg

String

Definition

Error description.

Status code: 429

Table 9 Response body parameters

Parameter

Type

Description

-

String

Status code: 500

Table 10 Response body parameters

Parameter

Type

Description

error_code

String

Definition

Error code.

error_msg

String

Definition

Error description.

Example Requests

Creating an instance

POST https://{endpoint}/v1/{project_id}/instances

Example Responses

Status code: 202

Instances created.

{
  "instance_id" : "0198170e-4ca7-7ee4-89a7-fa631843920b"
}

Status Codes

Status Code

Description

202

Instances created.

400

Invalid request parameter.

401

The request is not authenticated.

429

The request is overloaded.

500

Internal server error.

Error Codes

See Error Codes.