Updated on 2024-05-17 GMT+08:00

Creating BMSs

Function

This API is used to create one or more BMSs.

Background for Setting the Login Authentication Mode

Logging in to a BMS can be authenticated using either a key pair or password. For security purposes, you are advised to use key pair authentication.

  • Key pair

    A key pair is used for BMS login authentication.

    Method of calling APIs: Use the key_name field to specify the key file used for logging in to the BMS. For details about how to use the key_name field, see Table 2.

  • Password

    If you choose the initial password for authentication in a BMS, you can log in to a BMS using the username and its initial password. The initial password of user root is used for authentication in Linux.

    Methods of calling APIs:

    • Method 1 (recommended): Use the adminPass field to specify the initial login password of the specified administrator account. For details about how to use the adminPass field, see Table 2.

      For Linux BMSs with Cloud-Init, if field user_data is specified, field adminPass is invalid.

    • Method 2:
      • For Linux BMSs with Cloud-Init, use the user_data field to inject data. For details, see Table 2.

    Public images contain Cloud-Init or Cloudbase-Init by default. For private images, you need to check whether Cloud-Init or Cloudbase-Init is installed.

Constraints

  • File injection is not supported.
  • Currently, only yearly/monthly BMSs can be created.

URI

POST /v1/{project_id}/baremetalservers

Table 1 lists the parameters.

Table 1 Parameter description

Parameter

Mandatory

Description

project_id

Yes

Specifies the project ID.

For details about how to obtain the project ID, see Obtaining a Project ID.

Request Parameters

Parameter

Mandatory

Type

Description

server

Yes

Object

Specifies BMS information. For details, see Table 2.

Table 2 server field data structure description

Parameter

Mandatory

Type

Description

imageRef

Yes

String

Specifies the image ID or image resource URL used for creating the BMS. The ID is in the format of a Universally Unique Identifier (UUID).

You can obtain the image ID from the IMS console or by following the instructions in Querying Images in Image Management Service API Reference.

When using an API to query images, you can add the field ?virtual_env_type=Ironic to filter BMS images.

flavorRef

Yes

String

Specifies the flavor ID of the BMS. The format is physical.x.x.

You can obtain the flavor ID from the BMS console or using the Querying Flavor Details and Extended Flavor Information API.

NOTE:

For details about the images supported by different BMS flavors, see OSs Supported by Different Types of BMSs.

Only DeC tenants can apply for BMSs using the physical.x.x.hba flavor, and only DESS disks can be attached to BMSs using this flavor.

name

Yes

String

Specifies the BMS name.

Value range:

  • The value can contain a maximum of 63 characters consisting of letters (case-insensitive), digits, underscores (_), hyphens (-), and periods (.).
  • If more than one BMS is to be created, tags similar to -0000 will be automatically added to the end of the BMS names during the creation. In this case, the BMS name contains 1 to 58 characters.

metadata

Yes

Object

Specifies the BMS metadata. The maximum size for both the metadata key and value is 255 characters. For details, see Table 3.

user_data

No

String

Specifies the user data to be injected during the BMS creation. Text can be injected.

Constraints:

  • The content to be injected must be encoded with base64. The maximum size of the content to be injected (before encoding) is 32 KB.
  • If key_name is not specified, the password of user root for logging in to the BMS will be injected by default.
  • This parameter is mandatory when you create a Linux BMS using password authentication. Its value is the initial user root password.

Password complexity requirements:

  • Contains 8 to 26 characters.
  • Contains at least three of the following character types: uppercase letters, lowercase letters, digits, and special characters !@$%^-_=+[{}]:,./?
An example is as follows:
1
2
#!/bin/bash 
echo 'root:$6$V6azyeLwcD3CHlpY$BN3VVq18fmCkj66B4zdHLWevqcxlig' | chpasswd -e

where, $6$V6azyeLwcD3CHlpY$BN3VVq18fmCkj66B4zdHLWevqcxlig is the ciphertext password, which can be generated as follows:

  1. Generate an encrypted salt value.
    1
    2
    [root@test linux]# python -c "import crypt, getpass, pwd;print crypt.mksalt()" 
    $6$V6azyeLwcD3CHlpY
    
  2. Generate a ciphertext password based on the salt value.
    1
    2
    [root@test linux]# python -c "import crypt, getpass, pwd;print crypt.crypt('Cloud.1234','\$6\$V6azyeLwcD3CHlpY')" 
     $6$V6azyeLwcD3CHlpY$BN3VVq18fmCkj66B4zdHLWevqcxlig
    
NOTE:

Data injection is not supported for BMSs that use a Linux image and the password login mode. For details about how to inject user data, see Injecting User Data into BMSs.

adminPass

No

String

Specifies the initial login password of the administrator account for logging in to a BMS using password authentication. The Linux administrator is root.

Password complexity requirements:
  • Contains 8 to 26 characters.
  • Contains at least three of the following character types: uppercase letters, lowercase letters, digits, and special characters !@$%^-_=+[{}]:,./?
  • (Linux OSs) Cannot contain the username or the username in reverse.

key_name

No

String

Specifies the name of a key pair. This is an extended attribute. To log in to a BMS using an SSH key pair, set the value to the name of an existing private key.

You can create a key pair using the Creating or Importing an SSH Key Pair (Native OpenStack API) API, or query existing key pairs using the Querying SSH Key Pairs (Native OpenStack API) API.

Constraints:

  • If both key_name and user_data are specified, user_data only injects user data.
  • When a Windows image is used to create a BMS, this parameter cannot be left blank because the Windows image supports only login using a key.
  • To log in to a Windows BMS, decrypt the key pair to obtain a password and use it to remotely log in to the BMS. For details, see Login Using an MSTSC Password.

security_groups

No

Array of objects

Specifies security groups of the BMS. For details, see Table 4.

nics

Yes

Array of objects

Specifies NICs of the BMS. For details, see Table 5.

Constraints:

A maximum of two NICs can be attached to a BMS. The first will be used as the primary NIC. If multiple NICs are specified, ensure that all NICs belong to the same VPC.

availability_zone

Yes

String

Specifies the name of the AZ where the BMS is located.

vpcid

Yes

String

Specifies the ID of the VPC to which the BMS belongs. The value is in UUID format. You can obtain the VPC ID from the network console or by following the instructions in Querying VPC Details of Virtual Private Cloud API Reference.

publicip

No

Object

Specifies the EIP information of the BMS. Possible values include:

  • Do not use (This parameter is unavailable.)
  • Automatically assign: Assign a new EIP.
  • Specify: Specify an EIP that has been created.

For details, see Table 6.

count

No

Integer

Specifies the number of BMSs to be created.

Constraints:

  • If this parameter is not specified, the default value is 1.
  • If the quota is sufficient, the maximum value is 100.

root_volume

No

Object

Specifies system disk configurations of the BMS. For details, see Table 7.

Constraints:

If the flavor supports quick provisioning, this parameter is mandatory. Otherwise, this parameter is not required. For how to check whether a flavor supports quick provisioning, see Querying Details About extra_specs Parameters of a BMS Flavor (Native OpenStack API).

data_volumes

No

Array of objects

Specifies data disk configurations of the BMS. Each data structure represents a data disk to be created. For details, see Table 8.

Constraints:

A maximum of 60 EVS disks (including the system disk and data disks) can be attached to a BMS.

extendparam

Yes

Object

Specifies the supplementary for creating the BMS. For details, see Table 9.

schedulerHints

No

Object

Specifies scheduling information of the BMS. This parameter is mandatory for creating a BMS in a DeC.

For details, see Table 10.

server_tags

No

List <resource_tag>

Specifies tags of the BMS. For details, see Table 11.

NOTE:

A maximum of 10 tags can be added to a BMS. __type_baremetal is an internal tag of the system. Therefore, you can add a maximum of nine tags.

Table 3 metadata field data structure description

Parameter

Mandatory

Type

Description

op_svc_userid

Yes

String

Specifies the user ID. You can obtain the user ID from My Credential on the management console.

BYOL

No

String

Specifies whether a license is provided. The value can be true or false.

admin_pass

No

String

Specifies the initial password of the administrator account for logging in to a BMS. For Linux, the administrator account is root.

Password complexity requirements:
  • Contains 8 to 26 characters.
  • Contains at least three of the following character types: uppercase letters, lowercase letters, digits, and special characters !@$%^-_=+[{}]:,./?
  • Cannot contain the username, the username in reverse, or more than two consecutive characters in the username.

agency_name

No

String

Specifies the IAM agency name.

An agency provides a temporary security credential for accessing a BMS. The agency is created by the tenant administrator on the IAM console.

NOTE:

To obtain and update an agency, perform the following steps:

  1. You can obtain a valid agency name by using the Listing Agencies API provided by IAM.
  2. Use the Updating the Metadata of a BMS API to change the value of field agency_name in the metadata to the new agency name.
Table 4 security_groups field data structure description

Parameter

Mandatory

Type

Description

id

No

String

Specifies the security group ID, which takes effect for all NICs configured for the BMS.

  • If this parameter is not specified, the default security group will be bound to the BMS.
  • If this parameter is required (in UUID format), use the ID of an existing security group. For details about how to obtain existing security groups, see Querying Security Groups in Virtual Private Cloud API Reference.
Table 5 nics field data structure description

Parameter

Mandatory

Type

Description

subnet_id

Yes

String

Specifies the subnet information of a BMS NIC.

The value must be the ID of the subnet (network_id) created in the VPC specified by vpcid and in the format of UUID. You can obtain the subnet ID (network_id) from the VPC console or by following the instructions in Querying Subnets in Virtual Private Cloud API Reference.

ip_address

No

String

Specifies the IPv4 address of a BMS NIC.

Constraints:

  • If this parameter is left blank or set to "", an unused IP address in the subnet of this network is automatically assigned as the IP address of the NIC.
  • If this parameter is specified, its value must be an unused IP address in the network segment of the subnet.
  • The IP address cannot be specified when you create BMSs in a batch.
Table 6 publicip field data structure description

Parameter

Mandatory

Type

Description

id

No

String

Specifies the ID of an existing EIP assigned to the BMS. The value is in UUID format. You can obtain the EIP ID from the network console or by following the instructions in Querying EIPs in Elastic IP API Reference.

Constraints:

  • Only EIPs in the DOWN state can be assigned.
  • Existing EIPs cannot be used for creating BMSs in a batch. That is, this parameter is invalid in such a case.

eip

No

Object

Specifies the configuration for creating an EIP that will be automatically assigned to the BMS. For details, see Table 12.

You can configure either but not both of id and eip in the publicip field.

Table 7 root_volume field data structure description

Parameter

Mandatory

Type

Description

volumetype

Yes

String

Specifies the BMS system disk type. The disk type must match the available disk type.

  • GPSSD: general-purpose SSD disk type
  • SAS: high I/O disk type
  • SSD: ultra-high I/O disk type

size

Yes

Integer

Specifies the system disk size (GB). The value ranges from 40 to 1024.

Constraints:

The system disk size must be greater than or equal to the minimum system disk size of the image (min_disk attribute).

cluster_id

No

String

Specifies the ID of the storage pool to which the BMS system disk belongs.

NOTE:
  • This parameter is required when Dedicated Distributed Storage Service (DSS) is used.

cluster_type

No

String

Specifies the storage type of the BMS system disk. An example value is DSS, which indicates the DSS service.

NOTE:
  • This parameter is required when DSS is used.
Table 8 data_volumes field data structure description

Parameter

Mandatory

Type

Description

volumetype

Yes

String

Specifies the BMS data disk type. The disk type must match the available disk type.

  • GPSSD: general-purpose SSD disk type
  • SAS: high I/O disk type
  • SSD: ultra-high I/O disk type

size

Yes

Integer

Specifies the data disk size (GB). The value ranges from 10 to 32768.

shareable

No

Boolean

Specifies whether the disk is shareable.

  • true: shared EVS disk
  • false: common EVS disk

The default value is false.

cluster_id

No

String

Specifies the ID of the storage pool to which BMS data disks belong.

NOTE:
  • This parameter is required when Dedicated Distributed Storage Service (DSS) is used.

cluster_type

No

String

Specifies the storage type of BMS data disks. An example value is DSS, which indicates the DSS service.

NOTE:
  • This parameter is required when DSS is used.
Table 9 extendparam field data structure description

Parameter

Mandatory

Type

Description

chargingMode

No

String

Specifies the billing mode. Value range:

prePaid (default): yearly/monthly billing

regionID

No

String

Specifies the ID of the region where the BMS resides.

periodType

No

String

Specifies the subscription period. Value range:

  • month: indicates that the subscription unit is month.
  • year: indicates that the subscription unit is year.
NOTE:

This parameter is valid and mandatory if chargingMode is set to prePaid.

periodNum

No

Integer

Specifies the number of subscription periods. Value range:

  • If periodType is month, the value ranges from 1 to 9.
  • If periodType is year, the value is 1.
NOTE:

This parameter is valid and mandatory if chargingMode is set to prePaid.

isAutoRenew

No

String

Specifies whether auto-renewal is enabled.

  • true: indicates that auto-renewal is enabled.
  • false: indicates that auto-renewal is disabled.
NOTE:

This parameter is valid when chargingMode is set to prePaid. If this parameter is not specified or is left blank, auto-renewal is disabled.

isAutoPay

No

String

Specifies whether the order is automatically or manually paid.

  • true: The order will be automatically paid.
  • false: You must manually pay the order.
NOTE:

This parameter is valid when chargingMode is set to prePaid. If this parameter is not specified or is left blank, manual payment is required.

Table 10 schedulerHints field data structure description

Parameter

Mandatory

Type

Description

dec_baremetal

No

String

Specifies whether to create the BMS in a DeC. The value can be share or dedicate.

Constraints:

  • If this parameter is not specified, the default value is share.
  • To create a BMS in a DeC, set this parameter to dedicate.
Table 11 server_tags field data structure description

Parameter

Mandatory

Type

Description

key

Yes

String

Specifies the tag key.

  • It contains a maximum of 36 Unicode characters and cannot be empty.
  • It cannot contain ASCII characters (0–31) or special characters =*<>\,|/
  • The tag key of a BMS must be unique.

value

No

String

Specifies the tag value.

  • Each value contains a maximum of 43 Unicode characters and can be an empty string.
  • It cannot contain ASCII characters (0–31) or special characters =*<>\,|/
Table 12 eip field data structure description

Parameter

Mandatory

Type

Description

iptype

Yes

String

Specifies the EIP type.

Enumerated values: 5_bgp and 5_sbgp

For details, see the publicip field in Assigning an EIP in Elastic IP API Reference.

bandwidth

Yes

Object

Specifies the EIP bandwidth. For details, see Table 13.

extendparam

Yes

Object

Provides additional information about the EIP. For details, see Table 14.

Table 13 bandwidth field data structure description

Parameter

Mandatory

Type

Description

name

No

String

Specifies the bandwidth name.

sharetype

Yes

String

Specifies the bandwidth sharing type.

Value PER indicates dedicated bandwidth and WHOLE indicates shared bandwidth.

id

No

String

Specifies the shared bandwidth ID. You can specify an existing shared bandwidth when applying for an EIP with a WHOLE bandwidth.

NOTE:

This parameter is mandatory when sharetype is set to WHOLE.

size

Yes

Integer

  • The value ranges from 5 Mbit/s to 2000 Mbit/s by default. (The specific range may vary depending on the configuration in each region. You can view the bandwidth range of each region on the management console.)
  • Specifies the bandwidth (Mbit/s). The minimum shared bandwidth is 5 Mbit/s by default.
NOTE:
  • If a decimal fraction (for example 10.2) or a character string (for example 10) is specified, the specified value will be automatically converted to an integer. If the bandwidth is less than 300 Mbit/s, the step is 1 Mbit/s. If the bandwidth is from 300 Mbit/s to 1000 Mbit/s, the step is 50 Mbit/s. If the bandwidth is from 1000 Mbit/s to 2000 Mbit/s, the step is 1000 Mbit/s.
  • This parameter is mandatory when sharetype is set to PER and is optional when sharetype is set to WHOLE with an ID specified.

chargemode

No

String

Specifies the bandwidth billing mode.

The value can be traffic or bandwidth.

  • If this field is not specified, the BMS is billed by bandwidth.
  • If the field value is empty, the BMS is billed by bandwidth.
Table 14 extendparam field data structure description for assigning an EIP

Parameter

Mandatory

Type

Description

chargingMode

Yes

String

Specifies the billing mode of an EIP. If bandwidth is charged by bandwidth, both prePaid and postPaid will be available for EIP. If bandwidth is charged by traffic, only postPaid will be available for EIP.

Value range:

  • prePaid: yearly/monthly billing mode.
  • postPaid: indicates the pay-per-use billing mode.

Example Request

  • Creating a BMS (image ID: 766a545a-02e1-433e-b1d1-733b5dc95e94; flavor: physical.s3.large; billing: yearly/monthly; remote login: password)
    1
    POST https://{BMS Endpoint}/v1/{project_id}/baremetalservers
    
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    {
        "server": {
            "availability_zone": "az1",
            "name": "bms-75c7",
            "imageRef": "766a545a-02e1-433e-b1d1-733b5dc95e94",
            "flavorRef": "physical.s3.large",
            "data_volumes": [
                {
                    "volumetype": "SAS",
                    "size": 10,
                    "shareable": false
                }
            ],
            "vpcid": "8df83bf2-fd2e-4ee0-9692-c0b7736513fb",
            "nics": [
                {
                    "subnet_id": "c6bb8788-4fd1-4a8f-adab-7eba3bed8616",
                    "ip_address": ""
                }
            ],
            "count": 1,
            "schedulerHints": {
                "dec_baremetal": "share"
            },
            "extendparam": {    
                "chargingMode": "prePaid",
                "periodType": "month",
                "periodNum": 1,
                "isAutoRenew": "true",
                "isAutoPay": "true",
                "regionID": "region01"
            },
            "metadata": {
                "op_svc_userid": "59781460e9e54886a7d03df7d3f3fc81",
                "BYOL": "false",
                "admin_pass": "$ADMIN_PASS"
            },
            "publicip": {
                "id": "1b036bce-26b4-465c-acea-99fdbb0573a3"
            },
            "user_data": "$USER_DATA",
            "security_groups": [
                {
                    "id": "993f2916-5bad-4f24-bc3c-db539f1a6d19"
                }
            ]
        }
    }
    
  • Creating a Linux BMS in AZ1 (name: bms-3b91; image ID: 766a545a-02e1-433e-b1d1-733b5dc95e94; flavor: physical.o2.large; billing: yearly/monthly; remote login: key pair)
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    {
        "server": {
            "availability_zone": "az1",
            "name": "bms-3b91",
            "imageRef": "766a545a-02e1-433e-b1d1-733b5dc95e94",
            "flavorRef": "physical.o2.large",
            "data_volumes": [
                {
                    "volumetype": "SAS",
                    "size": 10,
                    "shareable": true
                }
            ],
            "vpcid": "8df83bf2-fd2e-4ee0-9692-c0b7736513fb",
            "nics": [
                {
                    "subnet_id": "c6bb8788-4fd1-4a8f-adab-7eba3bed8616",
                    "ip_address": ""
                },
                {
                    "subnet_id": "2b8bcf33-33f2-4a63-aa9c-b1e17ff0ed7f",
                    "ip_address": ""
                }
            ],
            "count": 1,
            "schedulerHints": {
                "dec_baremetal": "share"
            },
            "extendparam": {
                "chargingMode": "prePaid",
                "periodType": "month",
                "periodNum": 1,
                "isAutoRenew": "true",
                "isAutoPay": "true",
                "regionID": "region01"
            },
            "metadata": {
                "op_svc_userid": "59781460e9e54886a7d03df7d3f3fc81",
                "BYOL": "false"
            },
            "publicip": {
                "eip": {
                    "iptype": "5_bpg",
                    "bandwidth": {
                        "chargemode": "",
                        "name": "bms-3b91-bandwidth",
                        "size": 1,
                        "sharetype": "PER"
                    },
                    "extendparam": {
                       "chargingMode": "prePaid"
                    }
                }
            },
            "security_groups": [
                {
                    "id": "993f2916-5bad-4f24-bc3c-db539f1a6d19"
                }
            ],
            "key_name": "$key_name"
        }
    }
    

    The following is an example of user_data generated by Java:

    1
    2
    3
    String userData_org = "#!/bin/bash \r\n echo    'root:xxxxx' | chpasswd ;";
    byte[] userData_byte = userData_org.getBytes();
    String userData = new BASE64Encoder().encode(userData_byte);
    
  • Creating a Windows BMS in AZ1 (name: bms-6a1e; image ID: fd04041a-5f35-45ae-a27c-bf30f921c6b5; billing: yearly/monthly; flavor: physical.s3.largecharged; remote login: key pair)
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    { 
         "server": { 
             "availability_zone": "az1", 
             "name": "bms-6a1e", 
             "imageRef": "fd04041a-5f35-45ae-a27c-bf30f921c6b5", 
             "flavorRef": "physical.s3.large", 
             "data_volumes": [ 
                 { 
                     "volumetype": "SAS", 
                     "size": 10, 
                     "shareable": false 
                 } 
             ], 
             "vpcid": "0adc2847-c160-4263-be1f-e03d36e93e32", 
             "nics": [ 
                 { 
                     "subnet_id": "4f1cf6cc-4cc3-41d3-8192-625293dccce0", 
                     "ip_address": "" 
                 } 
             ], 
             "count": 1, 
             "schedulerHints": { 
                 "dec_baremetal": "share" 
             }, 
            "extendparam": { 
                "chargingMode": "prePaid", 
                "periodType": "month", 
                "periodNum": 1, 
                "isAutoRenew": "true", 
                "isAutoPay": "true", 
                "regionID": "region1" 
             }, 
             "metadata": { 
                "op_svc_userid": "8a74baed155b47e8b59fbca853d6cb48", 
                "BYOL": "false" 
             }, 
             "publicip": { 
                 "id": "db9c4f39-fabd-4cc2-8685-82e7715d099f" 
             }, 
             "user_data": "$USER_DATA", 
             "security_groups": [ 
                 { 
                     "id": "33cf5e40-0b65-4e03-867d-4c67947c49be" 
                 } 
             ], 
             "key_name": "$key_name"
         } 
     }
    

Response Parameters

Table 15 Normal response

Parameter

Type

Description

order_id

String

Specifies the order ID returned after an order is submitted. You can query the order processing progress based on the ID. To query the order processing progress, log in to the management console and choose Billing > My Orders.

job_id

String

Specifies the task ID returned after a task command is issued. The task ID can be used to query the execution status of the task.

For details about how to query the task execution status based on job_id, see Querying Task Statuses.

Table 16 Abnormal response

Parameter

Type

Description

error

Dictionary data structure [1]

Specifies the error returned when a task submission encounters an exception. For details, see Table 17.

Table 17 error data structure

Parameter

Type

Description

message

String

Specifies the error message.

code

String

Specifies the error code.

Example Response

  • Normal response
    { 
        "order_id": "CS2009141523OQSEQ",
        "job_id": "ff808081748b760c01748b7f80370003"
    }

Returned Values

Normal values

Returned Values

Description

200

The request has been successfully processed.

For details about other returned values, see Status Codes.

Error Codes

See Error Codes.