API Reference€¦ · 3.5.2 Querying BMSs (Native OpenStack API).....68 3.5.3 Querying Details About BMSs (Native OpenStack API ... 101 3.11.4 Deleting an SSH Key Pair (Native OpenStack

Bare Metal Server

API Reference

Issue 01

Date 2018-07-15

Before You Start

IntroductionThis document provides the descriptions, syntax, parameters, and examples of the Bare MetalServer (BMS) APIs.

Table 1 Content

Phase Related Links

BMS API types and API list API Overview

REST message bodies and calling methods API Invoking Method

API use methods BMS APIs

Public parameters Return Codes

Required KnowledgeBMS APIs include self-developed and native OpenStack APIs. To use native OpenStackAPIs, you need to have basic knowledge of OpenStack, which you can find at https://www.openstack.org/.

Bare Metal ServerAPI Reference Before You Start

Issue 01 (2018-07-15) ii

https://www.openstack.org/

https://www.openstack.org/

Contents

Before You Start............................................................................................................................... ii

1 API Overview................................................................................................................................. 1

2 API Invoking Method...................................................................................................................32.1 REST APIs..................................................................................................................................................................... 32.2 Service Usage................................................................................................................................................................. 72.3 Request Methods............................................................................................................................................................ 82.4 Request Authentication Methods....................................................................................................................................82.5 Token Authentication......................................................................................................................................................82.6 AK/SK Authentication................................................................................................................................................... 92.6.1 AK and SK Generation..............................................................................................................................................102.6.2 Request Signing Procedure........................................................................................................................................102.6.3 Sample Code.............................................................................................................................................................. 112.7 Obtaining the Project ID or Tenant ID......................................................................................................................... 18

3 BMS APIs...................................................................................................................................... 193.1 BMS Lifecycle Management........................................................................................................................................193.1.1 Creating a BMS......................................................................................................................................................... 193.1.2 Querying BMS Details.............................................................................................................................................. 353.2 BMS Status Management............................................................................................................................................. 443.2.1 Changing the BMS Name..........................................................................................................................................443.3 BMS Disk Management............................................................................................................................................... 533.3.1 Attaching an EVS Disk to a BMS............................................................................................................................. 533.3.2 Detaching an EVS Disk from a BMS........................................................................................................................553.4 Querying Task Statuses.................................................................................................................................................563.4.1 Querying Task Statuses..............................................................................................................................................563.5 BMS Lifecycle Management (Native OpenStack APIs)..............................................................................................593.5.1 Querying Details About a BMS (Native OpenStack API)........................................................................................ 593.5.2 Querying BMSs (Native OpenStack API).................................................................................................................683.5.3 Querying Details About BMSs (Native OpenStack API)......................................................................................... 713.6 BMS Status Management (Native OpenStack APIs)................................................................................................... 743.6.1 Starting a BMS (Native OpenStack API).................................................................................................................. 743.6.2 Restarting a BMS (Native OpenStack API).............................................................................................................. 753.6.3 Stopping a BMS (Native OpenStack API)................................................................................................................ 76

Bare Metal ServerAPI Reference Contents

Issue 01 (2018-07-15) iii

3.6.4 Querying BMS Metadata (Native OpenStack API).................................................................................................. 773.6.5 Updating BMS Metadata (Native OpenStack API)...................................................................................................793.6.6 Modifying Specified BMS Metadata (Native OpenStack API)................................................................................ 813.6.7 Deleting Specified BMS Metadata (Native OpenStack API)....................................................................................823.7 BMS IP Address Query (Native OpenStack APIs)...................................................................................................... 833.7.1 Querying IP Addresses of BMSs (Native OpenStack API)...................................................................................... 833.7.2 Querying the IP Address of a BMS (Native OpenStack API)...................................................................................843.8 BMS Flavor Query (Native OpenStack APIs)............................................................................................................. 863.8.1 Querying BMS Flavors (Native OpenStack API)..................................................................................................... 863.8.2 Querying Details About a BMS Flavor (Native OpenStack API).............................................................................893.8.3 Querying Details About BMS Flavor extra_specs (Native OpenStack API)............................................................913.9 BMS NIC Management (Native OpenStack APIs)...................................................................................................... 923.9.1 Querying Information About BMS NICs (Native OpenStack API)..........................................................................923.9.2 Querying NIC Information About a Specified BMS (Native OpenStack API).........................................................943.10 BMS Disk Management (Native OpenStack APIs)................................................................................................... 953.10.1 Querying Information About the Disks Attached to a BMS (Native OpenStack API)...........................................953.10.2 Querying Information About a Disk Attached to a BMS (Native OpenStack API)................................................973.11 BMS SSH Key Pair Management (Native OpenStack APIs).....................................................................................983.11.1 Querying SSH Key Pairs (Native OpenStack API)................................................................................................. 983.11.2 Querying an SSH Key Pair (Native OpenStack API)............................................................................................1003.11.3 Creating and Importing an SSH Key Pair (Native OpenStack API)..................................................................... 1013.11.4 Deleting an SSH Key Pair (Native OpenStack API)............................................................................................. 1043.12 BMS 1D Tag Management (Native OpenStack APIs)............................................................................................. 1043.12.1 Querying BMS Tags (Native OpenStack API)......................................................................................................1043.12.2 Adding Tags to a BMS (Native OpenStack API).................................................................................................. 1053.12.3 Deleting Tags of a BMS (Native OpenStack API)................................................................................................ 1073.12.4 Adding a Tag to a BMS (Native OpenStack API).................................................................................................1073.12.5 Checking for Tags of a BMS (Native OpenStack API).........................................................................................1093.12.6 Deleting a Tag of a BMS (Native OpenStack API)...............................................................................................109

4 Return Codes.............................................................................................................................. 1114.1 Common Returned Values.......................................................................................................................................... 1114.2 Error Codes................................................................................................................................................................. 112

A Appendix....................................................................................................................................121A.1 Network API Description.......................................................................................................................................... 121A.2 DSS API Description.................................................................................................................................................121

B Change History..........................................................................................................................122

Bare Metal ServerAPI Reference Contents

Issue 01 (2018-07-15) iv

1 API Overview

BMS APIs include self-developed and native OpenStack APIs.

A combination of the two types of APIs allows you to use all functions provided by the BMSservice. For example, you can create a BMS by using a self-developed or a native OpenStackAPI.

Table 1-1 API description

Type Function Description

Self-developedAPIs

Lifecyclemanagement(creatingBMSs)

Creating BMSs

Statusmanagement

l Changing the BMS namel Obtaining the remote login address

EVS diskmanagement

Attaching and detaching an EVS disk (batch operation isnot supported)

Tagmanagement

Adding 2D tags to a specified BMS in batches

NativeOpenStackAPIs (V2.1)

Lifecyclemanagement

Creating, deleting, and querying details of BMSs

Statusmanagement

Starting, restarting, and stopping BMSs

IP addressquery

Querying IP addresses of BMSs

BMS flavorquery

l Querying BMS flavorsl Querying details of BMS flavors

BMS NICquery

l Querying NICs of BMSsl Querying NICs of BMSs by NIC ID

Bare Metal ServerAPI Reference 1 API Overview

Issue 01 (2018-07-15) 1

Type Function Description

EVS diskmanagement

Attaching, detaching, and querying EVS disks

SSH keymanagement

Querying SSH keys, querying details of SSH keys, andcreating and deleting SSH keys

1D tagmanagement

Adding, deleting, modifying, and querying 1D tags ofBMSs

NOTE

In the current version, long HTTP connections cannot be used to call native OpenStack APIs.

Bare Metal ServerAPI Reference 1 API Overview

Issue 01 (2018-07-15) 2

2 API Invoking Method

Application programming interface (API) requests sent by third-party applications to publiccloud services must be authenticated using signatures.

This chapter describes the signature usage procedure, provides sample code to illustrate howto use the default signer to sign requests and how to use the HTTP client to send requests.

2.1 REST APIsThe BMS service provides Representational State Transfer (REST) APIs. In REST, specificinformation or data on a network is represented by resources. REST allows users to accessservice resources by creating, querying, updating, and deleting resources.

A REST API request or response consists of the following five parts:

l Request URIl Request headerl Request bodyl Response headerl Response body

Request URI

A request URI consists of the following:

{URI-scheme}://{Endpoint}/{resource-path}?{query-string}

Although the request URI is included in the request header, most languages or frameworksrequire that it be transmitted separately from the request message. Therefore, the request URIis listed independently.

Table 2-1 URI parameter description

Parameter Description

URI-scheme Specifies the protocol used for transmitting requests. HTTPS mustbe used in BMS APIs.

Bare Metal ServerAPI Reference 2 API Invoking Method

Issue 01 (2018-07-15) 3


Endpoint Specifies the domain name or IP address of the server bearing theREST service endpoint. Obtain the value from Regions andEndpoints.

resource-path Specifies the API access path for performing a specified operation.Obtain the value from the URI of the API, for example, v3/auth/tokens.

query-string This parameter is optional. For example, you can set it to APIversion or resource selection criteria.

Request HeaderA request header consists of an HTTP method and additional field in the request header.

l HTTP methods, which are also called operations or actions, specify the type ofoperations that you are requesting. The following table lists the methods supported byBMS REST APIs.

Table 2-2 HTTP methods

Method Description

GET The GET method requests a representation of the specifiedresource.

PUT The PUT method requests that the enclosed entity be storedunder the supplied URI.

POST The POST method requests that the server accept the entityenclosed in the request as a new subordinate of the webresource identified by the URI.

DELETE The DELETE method deletes the specified resource, forexample, an object.

HEAD The HEAD method requests a server resource header.

PATCH The PATCH method applies partial modifications to aresource.If the resource does not exist, the PATCH method creates aresource.

l You can also add additional fields to the request header, for example, the fields required

by a specified URI and an HTTP method. For details about the fields of common requestmessage headers, see section Table 2-3.


Issue 01 (2018-07-15) 4

https://developer.huaweicloud.com/en-us/endpoint


Table 2-3 Common request headers

Parameter Description Mandatory Example Value

X-Sdk-Date Specifies the timewhen the request issent. The time is inYYYYMMDD'T'HHMMSS'Z' format.The value is thecurrent GMT time ofthe system.

NoThis field ismandatory forAK/SKauthentication.

20150907T101459Z

Authorization Specifies theauthenticationinformation.The value can beobtained from therequest signingresult.See section RequestSigning Procedure.


SDK-HMAC-SHA256Credential=ZIRRKMTWPTQFQI1WKNKB/20150907//ec2/sdk_request,SignedHeaders=content-type;host;x-sdk-date,Signature=55741b610f3c9fa3ae40b5a8021ebf7ebc2a28a603fc62d25cb3bfe6608e1994

Host Specifies the serverdomain name andport number of theresources beingrequested. The valuecan be obtainedfrom the URL of theservice API. Thevalue ishostname[:port]. Ifthe port number isnot specified, thedefault port is used.The default portnumber for https is443.


code.test.comorcode.test.com:443

Content-Type Specifies the MIMEtype of the body inthe request. You areadvised to use thedefault valueapplication/json.For interfaces usedto upload objects orimages, the valuecan vary dependingon the flow type.

Yes application/json


Issue 01 (2018-07-15) 5

Parameter Description Mandatory Example Value

Content-Length

Specifies the lengthof the request body.The unit is byte.

No 3495

X-Project-Id Specifies the projectID. Obtain theproject ID byfollowing theinstructions insection Obtainingthe Project ID orTenant ID.This parameter ismandatory for arequest from a DeCor multi-project user.

NoThis field ismandatory forrequests thatuse AK/SKauthenticationin theDedicatedCloud (DeC)scenario ormulti-projectscenario.

e9993fc787d94b6c886cbaa340f9c0f4

X-Auth-Token Specifies the usertoken.For details abouthow to obtain thetoken, see section"Obtaining the UserToken" in theIdentity and AccessManagement APIReference. After therequest is processed,the value of X-Subject-Token inthe message headeris the token value.

NoThis field ismandatory fortokenauthentication.

The following is part of anexample token:MIIPAgYJKoZIhvcNAQc-CoIIO8zCCDu8CAQExDTALBglghkgBZQMEA-gEwgg1QBgkqhkiG9w0BBwGggg1BBIINPXsidG9rZ.

Request BodyThis part is optional. A request body is generally sent in a structured format (for example,JSON or XML), corresponding to Content-Type in the request header, and is used to transfercontent other than the request header.

Response HeaderA response header consists of an HTTP status code and additional field:

l An HTTP status code, such as 2xx success code and 4xx or 5xx error code, or a statuscode defined by the BMS service

l An additional response header field, for example the Content-Type response header field.For details about the fields of common response message headers, see section Table 2-4.


Issue 01 (2018-07-15) 6

Table 2-4 Common response headers

Parameter Description Example Value

Content-Length

Specifies the length of the response body.The unit is byte.

--

Date Specifies the GMT time when a responseis returned.

Wed, 27 Dec 201606:49:46 GMT

Content-Type Specifies the response body MIME type. application/json

Response BodyThis part is optional. A response body is generally returned in a structured format (forexample, JSON or XML), corresponding to Content-Type in the response header, and is usedto transfer content other than the response header.

Send a RequestYou can initiate a request based on constructed request messages using any of the followingmethods:

l cURLcURL is a command-line tool used to perform URL operations and transfer information.cURL acts as an HTTP client that can send HTTP requests to the server and receiveresponse messages. cURL is suitable for use in API tuning scenarios. For moreinformation about cURL, visit https://curl.haxx.se/.

l CodeYou can call APIs through code to assemble, send, and process request messages.

l REST clientBoth Mozilla and Google Chrome provide a graphical browser plug-in REST client tosend and process requests. For Firefox, see Firefox REST Client. For Google Chrome,see Chrome REST Client.

2.2 Service UsagePublic cloud services provide RESTful APIs.

Representational State Transfer (REST) allocates Uniform Resource Identifiers (URIs) todispersed resources so that resources can be located. Applications on clients use UniformResource Locators (URLs) to obtain resources.

The URL is in the following format: https://Endpoint/uri

Table 2-5 describes the parameters in a URL.


Issue 01 (2018-07-15) 7

https://curl.haxx.se/

https://addons.mozilla.org/en-US/firefox/addon/restclient/

https://code.google.com/archive/p/rest-client

Table 2-5 Parameter description


Endpoint Specifies the URL that is the entry point for a web service. Obtainthe value from Regions and Endpoints.

URI Specifies the API access path for performing a specified operation.Obtain the value from the URI of the API, for example, v3/auth/tokens.

2.3 Request MethodsThe HTTP protocol defines request methods, such as GET, PUT, POST, DELETE, andPATCH, to indicate the desired action to be performed on the identified resource. Thefollowing table describes the HTTP methods supported by the RESTful APIs.

Table 2-6 HTTPS methods

Method Description

GET The GET method requests a representation of the specified resource.

PUT The PUT method requests that the enclosed entity be stored under thesupplied URI.

POST The POST method requests that the server accept the entity enclosed in therequest as a new subordinate of the web resource identified by the URI.

DELETE The DELETE method deletes the specified resource, for example, anobject.

PATCH The PATCH method applies partial modifications to a resource.If the resource does not exist, the PATCH method creates a resource.

2.4 Request Authentication MethodsYou can use either of the following two authentication methods to call APIs:

l Token authentication: Requests are authenticated using Tokens.l AK/SK authentication: Requests are encrypted using the access key (AK) and secret key

(SK) to provide higher security.

2.5 Token Authentication

ScenariosIf you use a token for authentication, you must obtain the user's token and add X-Auth-Tokento the request message header of the service API when making an API call.


Issue 01 (2018-07-15) 8

http://developer.huaweicloud.com/en-us/endpoint

This section describes how to make an API call for token authentication.

Make an API Call1. Send POST https://Endpoint of IAM/v3/auth/tokens to obtain the endpoint of IAM and

the region name in the message body.

See Regions and Endpoints.

If the service region name is ALL, replace Endpoint of IAM with the endpoint of CNNorth-Beijing1.

An example request message is as follows:

NOTE

Replace the items in italic in the following example with actual ones. For details, see the Identityand Access Management API Reference.

{ "auth": { "identity": { "methods": [ "password" ], "password": { "user": { "name": "username", "password": "password", "domain": { "name": "domainname" } } } }, "scope": { "project": { "id": "0215ef11e49d4743be23dd97a1561e91" //This ID is used as an example. } } }}

2. Obtain the token. For details, see section "Obtaining the User Token" in the Identity andAccess Management API Reference.

3. Make a call to a service API, add X-Auth-Token to the message header, and set thevalue of X-Auth-Token to the token obtained in step 2.

2.6 AK/SK AuthenticationWhen you use API Gateway to send requests to underlying services, the requests are signedusing the AK and SK.

NOTE

AK: indicates the ID of the access key. AK is used together with SK to obtain an encrypted signature fora request.

SK: indicates the secret access key together used with the access key ID to sign requests. AK and SKcan be used together to identify a request sender to prevent the request from being modified.

When the AK/SK of a user under a domain is used, add X-Domain-Id to the header and set itto the user's domain ID.


Issue 01 (2018-07-15) 9


2.6.1 AK and SK Generation1. Log in to the management console.2. Hover the mouse over the username and select Basic Information from the drop-down

list.3. On the Account Info page, click Manage after Security Credentials.4. On the My Credential page, click Access Keys.5. Click Add Access Key.6. Enter the current login password.7. Enter the authentication code received in the email or mobile phone.

NOTE

For users created in Identity and Access Management (IAM), if no email address or mobile phoneis filled during the user creation, you only need to authenticate the login password.

8. Click OK to download the access key.

NOTE

To prevent the access key from being leaked, keep it secure.

2.6.2 Request Signing Procedure

Preparations1. Download the API Gateway signature tool from the following link:

http://esdk.huawei.com/ilink/esdk/download/HW_4567062. Extract the package.3. Create a Java project, and reference the extracted JAR to the dependency path.

Sign a Request1. Create a request com.cloud.sdk.DefaultRequest (JAVA) used for signing.2. Set the target API URL, HTTPS method, and content of request

com.cloud.sdk.DefaultRequest (JAVA).3. Sign request com.cloud.sdk.DefaultRequest (JAVA).

a. Call SignerFactory.getSigner(String serviceName, String regionName) to obtaina signing tool.

b. Call Signer.sign(Request<?> request, Credentials credentials) to sign the requestcreated in step 1.The following code shows the details://Select an algorithm for request signing.Signer signer = SignerFactory.getSigner(serviceName, region);//Sign the request. The request will change after the signing.signer.sign(request, new BasicCredentials(this.ak, this.sk));

4. Convert the request signed in the previous step to a new request that can be used to makean API call and copy the header of the signed request to the new request.For example, if Apache HttpClient is used, convert DefaultRequest to HttpRequestBaseand copy the header of the signed DefaultRequest to HttpRequestBase.For details, see descriptions of AccessServiceImpl.java in section Sample Code.


Issue 01 (2018-07-15) 10

http://esdk.huawei.com/ilink/esdk/download/HW_456706

2.6.3 Sample CodeThe following three types of code show how to sign a request and use an HTTP client to sendan HTTPS request:

AccessService: indicates the abstract class that converts the GET, POST, PUT, and DELETEmethods in to the access method.

Demo: indicates the execution entry used to simulate GET, POST, PUT, and DELETE requestsending.

AccessServiceImpl: indicates the implementation of the access method. Code required forAPI gateway communication is in the access method.

For details about region and serviceName in the following code, see Regions andEndpoints.

AccessService.java:package com.cloud.apigateway.sdk.demo;

import java.io.InputStream;import java.net.URL;import java.util.Map;

import org.apache.http.HttpResponse;

import com.cloud.sdk.http.HttpMethodName;

public abstract class AccessService { protected String serviceName = null; protected String region = null; protected String ak = null; protected String sk = null; public AccessService(String serviceName, String region, String ak, String sk) { this.region = region; this.serviceName = serviceName; this.ak = ak; this.sk = sk; } public abstract HttpResponse access(URL url, Map<String, String> header, InputStream content, Long contentLength, HttpMethodName httpMethod) throws Exception; public HttpResponse access(URL url, Map<String, String> header, HttpMethodName httpMethod) throws Exception { return this.access(url, header, null, 0l, httpMethod); } public HttpResponse access(URL url, InputStream content, Long contentLength, HttpMethodName httpMethod) throws Exception { return this.access(url, null, content, contentLength, httpMethod); } public HttpResponse access(URL url, HttpMethodName httpMethod) throws Exception { return this.access(url, null, null, 0l, httpMethod); } public abstract void close();


Issue 01 (2018-07-15) 11



public String getServiceName() { return serviceName; } public void setServiceName(String serviceName) { this.serviceName = serviceName; } public String getRegion() { return region; } public void setRegion(String region) { this.region = region; } public String getAk() { return ak; } public void setAk(String ak) { this.ak = ak; } public String getSk() { return sk; } public void setSk(String sk) { this.sk = sk; } }

AccessServiceImpl.java:

package com.cloud.apigateway.sdk.demo;

import java.io.IOException;import java.io.InputStream;import java.net.URISyntaxException;import java.net.URL;import java.util.HashMap;import java.util.Map;

import javax.net.ssl.SSLContext;

import org.apache.http.Header;import org.apache.http.HttpHeaders;import org.apache.http.HttpResponse;import org.apache.http.client.methods.HttpDelete;import org.apache.http.client.methods.HttpGet;import org.apache.http.client.methods.HttpHead;import org.apache.http.client.methods.HttpPatch;import org.apache.http.client.methods.HttpPost;import org.apache.http.client.methods.HttpPut;import org.apache.http.client.methods.HttpRequestBase;import org.apache.http.conn.ssl.AllowAllHostnameVerifier;import org.apache.http.conn.ssl.SSLConnectionSocketFactory;import org.apache.http.conn.ssl.SSLContexts;import org.apache.http.conn.ssl.TrustSelfSignedStrategy;import org.apache.http.entity.InputStreamEntity;import org.apache.http.impl.client.CloseableHttpClient;import org.apache.http.impl.client.HttpClients;

import com.cloud.sdk.DefaultRequest;import com.cloud.sdk.Request;import com.cloud.sdk.auth.credentials.BasicCredentials;


Issue 01 (2018-07-15) 12

import com.cloud.sdk.auth.signer.Signer;import com.cloud.sdk.auth.signer.SignerFactory;import com.cloud.sdk.http.HttpMethodName;

public class AccessServiceImpl extends AccessService {

private CloseableHttpClient client = null;

public AccessServiceImpl(String serviceName, String region, String ak, String sk) { super(serviceName, region, ak, sk); }

/** {@inheritDoc} */

public HttpResponse access(URL url, Map<String, String> headers, InputStream content, Long contentLength, HttpMethodName httpMethod) throws Exception {

// Make a request for signing. Request request = new DefaultRequest(this.serviceName); try { // Set the request address. request.setEndpoint(url.toURI());

String urlString = url.toString();

String parameters = null;

if (urlString.contains("?")) { parameters = urlString.substring(urlString.indexOf("?") + 1); Map parametersmap = new HashMap<String, String>(); if (null != parameters && !"".equals(parameters)) { String[] parameterarray = parameters.split("&"); for (String p : parameterarray) { String key = p.split("=")[0]; String value = p.split("=")[1]; parametersmap.put(key, value); } request.setParameters(parametersmap); } }

} catch (URISyntaxException e) { // It is recommended to add logs in this place. e.printStackTrace(); } // Set the request method. request.setHttpMethod(httpMethod); if (headers != null) { // Add request header information if required. request.setHeaders(headers); } // Configure the request content. request.setContent(content);

// Select an algorithm for request signing. Signer signer = SignerFactory.getSigner(serviceName, region); // Sign the request, and the request will change after the signing. signer.sign(request, new BasicCredentials(this.ak, this.sk));

// Make a request that can be sent by the HTTP client. HttpRequestBase httpRequestBase = createRequest(url, null, request.getContent(), contentLength, httpMethod); Map<String, String> requestHeaders = request.getHeaders(); // Put the header of the signed request to the new request.


Issue 01 (2018-07-15) 13

for (String key : requestHeaders.keySet()) { if (key.equalsIgnoreCase(HttpHeaders.CONTENT_LENGTH.toString())) { continue; } httpRequestBase.addHeader(key, requestHeaders.get(key)); }

HttpResponse response = null; SSLContext sslContext = SSLContexts.custom() .loadTrustMaterial(null, new TrustSelfSignedStrategy()) .useTLS().build(); SSLConnectionSocketFactory sslSocketFactory = new SSLConnectionSocketFactory( sslContext, new AllowAllHostnameVerifier());

client = HttpClients.custom().setSSLSocketFactory(sslSocketFactory) .build(); // Send the request, and a response will be returned. response = client.execute(httpRequestBase); return response; }

/** * Make a request that can be sent by the HTTP client. * * @param url * specifies the API access path. * @param header * specifies the header information to be added. * @param content * specifies the body content to be sent in the API call. * @param contentLength * specifies the length of the content. This parameter is optional. * @param httpMethod * specifies the HTTP method to be used. * @return specifies the request that can be sent by an HTTP client. */ private static HttpRequestBase createRequest(URL url, Header header, InputStream content, Long contentLength, HttpMethodName httpMethod) {

HttpRequestBase httpRequest; if (httpMethod == HttpMethodName.POST) { HttpPost postMethod = new HttpPost(url.toString());

if (content != null) { InputStreamEntity entity = new InputStreamEntity(content, contentLength); postMethod.setEntity(entity); } httpRequest = postMethod; } else if (httpMethod == HttpMethodName.PUT) { HttpPut putMethod = new HttpPut(url.toString()); httpRequest = putMethod;

if (content != null) { InputStreamEntity entity = new InputStreamEntity(content, contentLength); putMethod.setEntity(entity); } } else if (httpMethod == HttpMethodName.PATCH) { HttpPatch patchMethod = new HttpPatch(url.toString()); httpRequest = patchMethod;

if (content != null) { InputStreamEntity entity = new InputStreamEntity(content, contentLength); patchMethod.setEntity(entity); } } else if (httpMethod == HttpMethodName.GET) { httpRequest = new HttpGet(url.toString());


Issue 01 (2018-07-15) 14

} else if (httpMethod == HttpMethodName.DELETE) { httpRequest = new HttpDelete(url.toString()); } else if (httpMethod == HttpMethodName.HEAD) { httpRequest = new HttpHead(url.toString()); } else { throw new RuntimeException("Unknown HTTP method name: " + httpMethod); }

httpRequest.addHeader(header); return httpRequest; }

@Override public void close() { try { if (client != null) { client.close(); } } catch (IOException e) { // It is recommended to add logs in this place. e.printStackTrace(); } }

}

Demo.java:

package com.cloud.apigateway.sdk.demo;

import java.io.BufferedReader;import java.io.ByteArrayInputStream;import java.io.IOException;import java.io.InputStream;import java.io.InputStreamReader;import java.net.MalformedURLException;import java.net.URL;

import org.apache.http.HttpResponse;

import com.cloud.sdk.http.HttpMethodName;

public class Demo {

//replace real region private static final String region = "regionName";

//replace real service name private static final String serviceName = "serviceName";

public static void main(String[] args) {

//replace real AK String ak = "akString"; //replace real SK String sk = "skString";

// get method //replace real url String url = "urlString"; get(ak, sk, url);

// post method //replace real url String postUrl = "urlString"; //replace real body String postbody = "bodyString";


Issue 01 (2018-07-15) 15

post(ak, sk, postUrl, postbody);

// put method //replace real body String putbody = "bodyString"; //replace real url String putUrl = "urlString"; put(ak, sk, putUrl, putbody);

// delete method //replace real url String deleteUrl = "urlString"; delete(ak, sk, deleteUrl); }

public static void put(String ak, String sk, String requestUrl, String putBody) {

AccessService accessService = null; try { accessService = new AccessServiceImpl(serviceName, region, ak, sk); URL url = new URL(requestUrl); HttpMethodName httpMethod = HttpMethodName.PUT; InputStream content = new ByteArrayInputStream(putBody.getBytes()); HttpResponse response = accessService.access(url, content, (long) putBody.getBytes().length, httpMethod); System.out.println(response.getStatusLine().getStatusCode()); } catch (Exception e) { e.printStackTrace(); } finally { accessService.close(); }

} public static void patch(String ak, String sk, String requestUrl, String putBody) {

AccessService accessService = null; try { accessService = new AccessServiceImpl(serviceName, region, ak, sk); URL url = new URL(requestUrl); HttpMethodName httpMethod = HttpMethodName.PATCH; InputStream content = new ByteArrayInputStream(putBody.getBytes()); HttpResponse response = accessService.access(url, content, (long) putBody.getBytes().length, httpMethod); System.out.println(convertStreamToString(response.getEntity() .getContent())); } catch (Exception e) { e.printStackTrace(); } finally { accessService.close(); }

}

public static void delete(String ak, String sk, String requestUrl) {

AccessService accessService = null;

try { accessService = new AccessServiceImpl(serviceName, region, ak, sk); URL url = new URL(requestUrl); HttpMethodName httpMethod = HttpMethodName.DELETE;


Issue 01 (2018-07-15) 16

HttpResponse response = accessService.access(url, httpMethod); System.out.println(convertStreamToString(response.getEntity() .getContent())); } catch (Exception e) { e.printStackTrace(); } finally { accessService.close(); }

}

public static void get(String ak, String sk, String requestUrl) {

AccessService accessService = null;

try { accessService = new AccessServiceImpl(serviceName, region, ak, sk); URL url = new URL(requestUrl); HttpMethodName httpMethod = HttpMethodName.GET; HttpResponse response; response = accessService.access(url, httpMethod); System.out.println(convertStreamToString(response.getEntity() .getContent())); } catch (Exception e) { e.printStackTrace(); } finally { accessService.close(); }

}

public static void post(String ak, String sk, String requestUrl, String postbody) {

AccessService accessService = new AccessServiceImpl(serviceName, region, ak, sk); URL url = null; try { url = new URL(requestUrl); } catch (MalformedURLException e) { e.printStackTrace(); } InputStream content = new ByteArrayInputStream(postbody.getBytes()); HttpMethodName httpMethod = HttpMethodName.POST; HttpResponse response;

try { response = accessService.access(url, content, (long) postbody.getBytes().length, httpMethod); System.out.println(convertStreamToString(response.getEntity() .getContent())); } catch (Exception e) { e.printStackTrace(); } finally { accessService.close(); } }

private static String convertStreamToString(InputStream is) { BufferedReader reader = new BufferedReader(new InputStreamReader(is)); StringBuilder sb = new StringBuilder();

String line = null; try { while ((line = reader.readLine()) != null) { sb.append(line + "\n"); } } catch (IOException e) {


Issue 01 (2018-07-15) 17

e.printStackTrace(); } finally { try { is.close(); } catch (IOException e) { e.printStackTrace(); } }

return sb.toString(); }

}

NOTE

1. Parameters URI, AK, SK, and HTTP METHOD are mandatory.

2. You can use the request.addHeader() method to add header information.

2.7 Obtaining the Project ID or Tenant IDA project ID is required for some URLs when an API is called. It can be project_id ortenant_id because project_id has the same meaning as tenant_id in this document. Beforecalling an API, you need to obtain a project ID on the console. The steps are as follows:

1. Log in to the management console.2. Hover the mouse over the username and select Basic Information from the drop-down

list.3. On the Account Info page, click Manage after Security Credentials.

On the My Credential page, view the project ID in the project list.

Figure 2-1 Viewing the project ID


Issue 01 (2018-07-15) 18

3 BMS APIs

You must use the BMS endpoint when calling the V1 APIs in sections BMS LifecycleManagement to Querying Task Statuses and use endpoints registered with Nova whencalling the native OpenStack APIs in sections BMS Lifecycle Management (NativeOpenStack APIs) to BMS 1D Tag Management (Native OpenStack APIs).

Creation and unsubscription of BMSs in yearly/monthly mode involve interactions withoperations APIs.

NOTE

l APIs described in sections BMS Lifecycle Management (Native OpenStack APIs) to BMS 1DTag Management (Native OpenStack APIs) are the same as Elastic Cloud Server (ECS) APIs. Ifthe APIs change, see the parameter descriptions in the Elastic Cloud Server API Reference.

l The APIs include self-developed and native OpenStack APIs (with "Native OpenStack API" in thesection titles).

3.1 BMS Lifecycle Management

3.1.1 Creating a BMS

Function

This interface is used to create one or more BMSs.

Constraintsl File injection is not supported.

l This interface can only be used to create a BMS charged in yearly/monthly mode.

l A BMS can have a maximum of two VPCs, in which case the first VPC will be used bythe primary NIC.

Precautionsl This interface can be invoked by the partner's AK/SFK or token, or the AK/SK or token

of the partner's customer.

Bare Metal ServerAPI Reference 3 BMS APIs

Issue 01 (2018-07-15) 19

l If the AK/SK authentication mode is used, set the region in the example code based onthe Region column of the "Bare Metal Server (BMS)" section in Regions andEndpoints and set serviceName (service name abbreviation) to BMS.

l For details about endpoints, see the Endpoint column of the "Bare Metal Server (BMS)"section in Regions and Endpoints.

l Ensure that your account has sufficient balance because you cannot use coupons to payfor this interface. If the account balance is insufficient, error code BMS.0216 will bereported. If you want to use coupons to pay, set isAutoPay in the request to false.

URIl URI format

POST /v1/{tenant_id}/baremetalserversl Parameter description

Parameter Mandatory Description

tenant_id Yes Specifies the tenant ID.

Requestl Parameter description

Parameter

Description

Mandatory

Description

server Dict Yes Specifies the BMS information. For details, see[1] server field data structure description.

[1] server field data structure description

Parameter

Description

Mandatory

Description

imageRef

String Yes Specifies the ID of the image used by the BMS orthe image resource uniform resource locator(URL).

flavorRef

String Yes Specifies the ID of the flavor used by the BMS.NOTE

Only DeC tenants can apply for BMSs using thephysical.x.x.hba flavor, and only DESS disks can beattached to BMSs using this flavor.


Issue 01 (2018-07-15) 20




Parameter

Description

Mandatory

Description

name String Yes Specifies the BMS name.Value range:l The value can contain a maximum of 63

characters consisting of letters (case-insensitive), digits, underscores (_), hyphens(-), and periods (.).

l If more than one BMS is to be created, youneed to add tags similar to -0000 to the end ofthe BMS names during the creation. In thiscase, the BMS name contains a maximum of58 characters.

metadata Dictionary datastructure[2]

Yes Specifies the BMS metadata. The maximum sizefor each metadata key and value pair is 255 bytes.


Issue 01 (2018-07-15) 21

Parameter

Description

Mandatory

Description

user_data

String No Specifies the user data to be injected during theBMS creation. Text, text files, and .gzip files canbe injected.Constraints:l The content to be injected must be encoded

with base64. The maximum size of the contentto be injected (before encoding) is 32 KB.

l If key_name is not specified, the data injectedby user_data is the password of user root forlogging in to the BMS by default.

l This parameter is mandatory when you createa Linux BMS using the passwordauthentication mode. Its value is the initialuser root password.

Password complexity requirements:l Contains 8 to 26 characters.l Contains at least three of the following

character types: uppercase letters, lowercaseletters, digits, and special characters !@$%^-_=+[{}]:,./?.

An example is as follows:l Use a plaintext password (risky in security),

for example, cloud.1234.#!/bin/bash echo 'root:Cloud.1234' | chpasswd ;

l Use a password.#!/bin/bash echo 'root:$6$V6azyeLwcD3CHlpY$BN3VVq18fmCkj66B4zdHLWevqcxlig/GpOkLcOhab9smJoLKYm/Tf9Hcwa6DpiPDhdHfGEAPajFmLZa0YDd910' | chpasswd -e

where, $6$V6azyeLwcD3CHlpY$BN3VVq18fmCkj66B4zdHLWevqcxlig/GpOkLcOhab9smJoLKYm/Tf9Hcwa6DpiPDhdHfGEAPajFmL-Za0YDd910 is the ciphertext password, whichcan be generated as follows:1. Generate an encrypted salt value.

[root@ecs-test linux]# python -c "import crypt, getpass, pwd;print crypt.mksalt()" $6$V6azyeLwcD3CHlpY

2. Generate a ciphertext password based on thesalt value.[root@ecs-test linux]# python -c "import crypt, getpass, pwd;print crypt.crypt('Cloud.1234','\$6\$V6azyeLwcD3CHlpY')"


Issue 01 (2018-07-15) 22

Parameter

Description

Mandatory

Description

$6$V6azyeLwcD3CHlpY$BN3VVq18fmCkj66B4zdHLWevqcxlig/GpOkLcOhab9smJoLKYm/Tf9Hcwa6DpiPDhdHfGEAPajFmLZa0YDd910

NOTEData injection is not supported for BMSs that use aLinux image and the password login mode. For detailsabout how to inject data, see (Optional) Injecting UserData into BMSs.

key_name

String No Specifies the name of a key pair. This is anextended attribute. Specifies the name of the SSHkey used for logging in to the BMS.Constraints:l If both key_name and user_data are

specified, user_data only injects user data.l When a Windows image is used to create a

BMS, this parameter cannot be empty becausethe Windows image only supports login usinga key.

security_groups

List datastructure[3]

No Specifies the security group to which the BMSbelongs.

nics List datastructure[4]

Yes Specifies the BMS NICs.Constraints:A maximum of two networks can be specified.The first network in the parameter will be used bythe primary NIC. If multiple groups of networkparameters are specified, ensure that theparameters of each group belong to the sameVPC.

availability_zone

String Yes Specifies the name of the AZ where the BMS islocated.See Regions and Endpoints.

vpcid String Yes Specifies the ID of the VPC to which the BMSbelongs. The value is in the format of the UUID.You can obtain the VPC ID from the managementconsole or by referring to section "Querying aVPC" in the Virtual Private Cloud API Reference.

publicip List datastructure[5]

No Specifies the EIP information of the BMS.Possible values include:l Do Not Use (This parameter does not exist.)l Automatically Assign: Assign a new EIP.l Specify: Specify an EIP that has been created.


Issue 01 (2018-07-15) 23

https://support.huaweicloud.com/en-us/usermanual-bms/bms_01_0021.html

https://support.huaweicloud.com/en-us/usermanual-bms/bms_01_0021.html


Parameter

Description

Mandatory

Description

count Integer No Specifies the number of BMSs to be created.Constraints:l If this parameter is not specified, the default

value is 1.l If the quota is sufficient, the maximum value

is 24.

root_volume


No Specifies system disk configuration of the BMS.Constraints:This parameter is mandatory if the flavor supportsquick BMS provisioning. For details about howto check whether a flavor supports quick BMSprovisioning, see section Querying DetailsAbout BMS Flavor extra_specs (NativeOpenStack API).

data_volumes


No Specifies data disk configuration of the BMS.Each data structure represents a data disk to becreated.Constraints:A maximum of 60 EVS disks (including systemdisks and data disks) can be attached to a BMS.

extendparam


Yes Provides supplementary information about theBMS to be created.

schedulerHints


No Specifies scheduling information about the BMS.

[2] metadata field data structure description

Parameter

Type Mandatory

Description

op_svc_userid

String No Specifies the user ID. You can obtain the user IDfrom My Credential on the managementconsole.Constraints:When creating a BMS, set chargingMode in theextendparam structure to prePaid (creating aBMS charged in yearly/monthly mode). Thisfield is mandatory.


Issue 01 (2018-07-15) 24

Parameter

Type Mandatory

Description

admin_pass

String No Specifies the password of the administrator of theBMS created using a Windows image. Anexample value is cloud.1234.NOTE

This field is unavailable currently.

[3] security_groups field data structure description

Parameter

Description

Mandatory

Description

id String No Specifies the security group to which the BMSbelongs. The security group takes effect for theNICs on the BMS. You need to specify the ID ofan existing security group. The value is in UUIDformat.

[4] nics field data structure description

Parameter

Description

Mandatory

Description

subnet_id String Yes Specifies the BMS NICs.The value must be the ID of the network createdin the VPC specified by vpcid and in the formatof the UUID. You can obtain the network IDfrom the management console or by referring tosection "Querying Subnets" in the VirtualPrivate Cloud API Reference.

ip_address

String No Specifies the IP address of the NIC used by theBMS. The value is an IPv4 address.Constraints:l If this parameter is left blank or set to "", an

unused IP address in the subnet of thisnetwork is automatically assigned as the IPaddress of the NIC.

l If this parameter is specified, its value mustbe an unused IP address in the networksegment of the subnet in this network.

[5] publicip field data structure description


Issue 01 (2018-07-15) 25

Parameter

Type Mandatory

Description

id String No Specifies the ID of the EIP assigned to the BMSto be created. The value is in UUID format. Youcan obtain the EIP ID from the managementconsole or by referring to section "QueryingEIPs" in the Virtual Private Cloud APIReference.Constraints:Only EIPs in the DOWN state can be assigned.

eip List datastructure[10]

No Specifies the configuration parameter forcreating an EIP that will be automaticallyassigned to the BMS.

NOTE

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

[6] root_volume field data structure description

Parameter

Description

Mandatory

Description

volumetype

String Yes Specifies the BMS system disk type. The disktype must match the available disk type.l SATA: common I/O disk typel SAS: high I/O disk typel SSD: ultra-high I/O disk type

size Integer Yes Specifies the system disk size (GB). The valueranges from 40 to 1024.Constraints:The system disk size must be greater than orequal to the minimum system disk size of theimage (min_disk attribute).

cluster_id String No Specifies the ID of the storage pool used by theBMS system disk.NOTE

l This parameter is required when DedicatedDistributed Storage Service (DSS) is used.

l You can obtain the storage pool ID from themanagement console or by referring to section"Obtaining the Storage Pool Detail List" in theDedicated Storage Service API Reference.


Issue 01 (2018-07-15) 26

Parameter

Description

Mandatory

Description

cluster_type

String No Specifies the storage type of the BMS systemdisk. An example value is DSS, whichindicates the DSS service.NOTE

l This parameter is required when DSS is used.

l You can obtain the storage pool type from themanagement console or by referring to section"Obtaining the Storage Pool Detail List" in theDedicated Storage Service API Reference.

[7] data_volumes field data structure description

Parameter

Type Mandatory

Description

volume_type

String Yes Specifies the BMS system disk type. The disktype must match the available disk type.l SATA: common I/O disk typel SAS: high I/O disk typel SSD: ultra-high I/O disk typeConstraints:l When you apply for a BMS in a DeC,

DESS is required. In this case, the prefix ofthis field must be DESS_.Enumerated values are as follows:DESS_SAS_ISCSI: common I/O DESSstorageDESS_SAS_FC: common I/O DESSstorage (low latency)DESS_MIX_ISCSI: high I/O DESSstorageDESS_MIX_FC: high I/O DESS storage(low latency)DESS_SSD_ISCSI: ultra-high I/O DESSstorageDESS_SSD_FC: ultra-high I/O DESSstorage (low latency)

l DESS disks cannot be attached to BMSscharged in yearly/monthly mode.

NOTEFor details about the storage types supported byDESS, see section "Purchasing DESS" in the DESSUser Guide.


Issue 01 (2018-07-15) 27

Parameter

Type Mandatory

Description

size Integer Yes Specifies the data disk size (GB). The valueranges from 10 to 32768.

shareable boolean No Specifies whether the disk is shared. The valuecan be true (a shared disk) or false (a commondisk).

cluster_id String No Specifies the ID of the storage pool used bythe BMS data disk.NOTE

l This parameter is required when DedicatedDistributed Storage Service (DSS) is used.

l You can obtain the storage pool ID from themanagement console or by referring to section"Obtaining the Storage Pool Detail List" in theDedicated Storage Service API Reference.

cluster_type

String No Specifies the storage type of the BMS datadisk. An example value is DSS, whichindicates the DSS service.NOTE

l This parameter is required when DSS is used.

l You can obtain the storage pool type from themanagement console or by referring to section"Obtaining the Storage Pool Detail List" in theDedicated Storage Service API Reference.

[8] extendparam field description for creating a BMS

Parameter

Type Mandatory

Description

chargingmode

String No Specifies the charging mode.Value range:l prePaid: indicates the yearly/monthly

billing mode.l postPaid: indicates the pay-per-use billing

mode.NOTE

The default value is prePaid.

Common tenants can only choose prePaid. OnlyDeC tenants can choose postPaid.

regionID String No Specifies the ID of the region where the BMSis located.See Regions and Endpoints.


Issue 01 (2018-07-15) 28


Parameter

Type Mandatory

Description

periodType

String No Specifies the subscription period.Value range:l month: indicates that the subscription unit

is month.l year: indicates that the subscription unit is

year.NOTE

This parameter is valid and mandatory ifchargingMode is set to prePaid.

periodNum

Integer No Specifies the number of subscription periods.Value range:l If periodType is month, the value ranges

from 1 to 9.l If periodType is year, the value is 1.NOTE

This parameter is valid and mandatory ifchargingMode is set to prePaid.

isAutoRenew

String No Specifies whether the service is automaticallyrenewed.l true: indicates that auto renewal is

enabled.l false: indicates that auto renewal is

disabled.NOTE

This parameter is valid when chargingMode is setto prePaid. If this parameter is left blank, autorenewal is disabled by default.

isAutoPay String No Specifies whether the order is automaticallyor manually paid.l true: The order will be automatically paid.l false: You must manually pay the order.NOTE

This parameter is valid when chargingMode is setto prePaid. If this parameter is left blank, you mustmanually pay the order by default.

[9] schedulerHints field data structure description


Issue 01 (2018-07-15) 29

Parameter Type Mandatory

Description

dec_baremetal

String No Specifies whether to create a BMS in a DeC.The value can be share or dedicate.Constraints:l If this parameter is not specified, the

default value is share.l To create a BMS in a DeC, set the value

of this parameter to dedicate.

[10] eip field data structure description


Description

iptype String Yes Specifies the EIP type.Enumerated values:l 5_bgp: indicates the dynamic BGP.l 5_sbgp: indicates the static BGP.l 5_telcom: indicates China Telecom.l 5_union: indicates China Unicom.For details, see the publicip field in section"Assigning an EIP" in the Virtual PrivateCloud API Reference.

bandwidth List datastructure[11]

Yes Specifies the EIP bandwidth.

extendparam

Dictionarydatastructure[12]

Yes Provides additional information about theEIP.

[11] bandwidth field description


Description

name String No Specifies the bandwidth name.

sharetype String Yes Specifies the bandwidth sharing type.Value PER indicates dedicated bandwidthand WHOLE indicates shared bandwidth.


Issue 01 (2018-07-15) 30


Description

id String No Specifies the bandwidth ID. You canspecify an existing shared bandwidth whenapplying for an EIP with a WHOLEbandwidth.Value: ID of the bandwidth whose type isset to WHOLENOTE

This parameter is mandatory when sharetype isset to WHOLE.

size Integer Yes l The value ranges from 5 Mbit/s to 2000Mbit/s by default. (The specific rangemay vary depending on theconfiguration in each region. You canview the bandwidth range of eachregion on the management console.)

l Specifies the bandwidth (Mbit/s). Theshared bandwidth has a lower limit,which may vary depending on the site.The default minimum value is 5 Mbit/s.

NOTE

l If a decimal fraction (for example 10.2) or acharacter string (for example 10) isspecified, the specified value will beautomatically converted to an integer. If thebandwidth is less than 300 Mbit/s, the stepis 1 Mbit/s. If the bandwidth is from 300Mbit/s to 1000 Mbit/s, the step is 50 Mbit/s.If the bandwidth is from 1000 Mbit/s to2000 Mbit/s, the step is 1000 Mbit/s.

l This parameter is mandatory whensharetype is set to PER and is optionalwhen sharetype is set to WHOLE with anID specified.

chargemode

String No Specifies the bandwidth billing mode.The value can be traffic or bandwidth.Value traffic indicates that the billing modeis traffic and value bandwidth indicatesthat the billing mode is bandwidth.l If this field is not specified, the billing

mode is bandwidth.l If this field is not specified, the billing

mode is bandwidth.l If the field value is others, the BMS

creation will fail.NOTE

This parameter is optional when sharetype isset to WHOLE with an ID specified.


Issue 01 (2018-07-15) 31

[12] extendparam field data structure description for creating an EIP

Parameter Type Mandatory Description

chargingmode

String Yes Specifies the billing mode of an EIP. Ifthe bandwidth billing mode isbandwidth, both prePaid and postPaidare supported. If the bandwidth billingmode is traffic, only postPaid issupported.Value range:l prePaid: indicates the yearly/monthly

billing mode.l postPaid: indicates the pay-per-use

billing mode.NOTE

If sharetype in the bandwidth field is set toWHOLE with an ID specified, only pay-per-use EIPs are allowed and parameter prePaidis unavailable.

l Example request (creating a BMS charged in yearly/monthly mode and with thepassword login mode){ "server": { "availability_zone": "kvmxen.dc1", "name": "bms-75c7", "imageRef": "766a545a-02e1-433e-b1d1-733b5dc95e94", "flavorRef": "physical.a1.199", "data_volumes": [ { "volumetype": "SATA", "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": "southchina" }, "metadata": { "op_svc_userid": "59781460e9e54886a7d03df7d3f3fc81", "admin_pass": ""


Issue 01 (2018-07-15) 32

}, "publicip": { "id": "1b036bce-26b4-465c-acea-99fdbb0573a3" }, "user_data": "IyEvYmluL2Jhc2gKZWNobyAncm9vdDokNiR0Y0pZamUkNGhhUHlNZFR4VWVHc2dTMWFmL1NsMm4vbXZzdy5wSFdjbTVBc084OWFhUFhGNXUvVnJ5OXJiYmZZSW45SmZac2k3SlRmd2Z6djJPbTBHRFZUZTd6RDEnIHwgY2hwYXNzd2QgLWU7", "security_groups": [ { "id": "993f2916-5bad-4f24-bc3c-db539f1a6d19" } ] }}

l Example request (creating a Linux BMS charged in yearly/monthly mode and with thekey pair login mode){ "server": { "availability_zone": "kvmxen.dc1", "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": "southchina" }, "metadata": { "op_svc_userid": "59781460e9e54886a7d03df7d3f3fc81" }, "publicip": { "eip": { "iptype": "5_telcom", "bandwidth": { "chargemode": "", "name": "bms-3b91-bandwidth", "size": 1, "sharetype": "PER", "productid": "f7419632131240a5acf18cc2ae25ba72" } } }, "security_groups": [


Issue 01 (2018-07-15) 33

{ "id": "993f2916-5bad-4f24-bc3c-db539f1a6d19" } ], "key_name": "KeyPair-zbb29" }}The following is an example of user_data generated by the Java language:String userData_org = "#!/bin/bash \r\n echo 'root:P@ssWr0d123' | chpasswd ;";byte[] userData_byte = userData_org.getBytes();String userData = new BASE64Encoder().encode(userData_byte);

l Example request (creating a Windows BMS charged in yearly/monthly mode and withthe key pair login mode){ "server": { "availability_zone": "cn-south-1a", "name": "bms-6a1e", "imageRef": "fd04041a-5f35-45ae-a27c-bf30f921c6b5", "flavorRef": "physical.s3.large", "data_volumes": [], "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": "southchina" }, "metadata": { "op_svc_userid": "8a74baed155b47e8b59fbca853d6cb48" }, "publicip": { "id": "db9c4f39-fabd-4cc2-8685-82e7715d099f" }, "user_data": "cWF6PTEyMw==", "security_groups": [ { "id": "33cf5e40-0b65-4e03-867d-4c67947c49be" } ], "key_name": "KeyPair-South-Maoz" }}

Responsel Element description


job_id String No Specifies the task ID.


Issue 01 (2018-07-15) 34


order_id String No Specifies the order ID. This parameteris returned for the creation of a BMScharged in yearly/monthly mode.

code String No Specifies the error code returnedwhen an error occurs.

message String No Specifies the message returned whenan error occurs.

l Example response

{ "job_id": "70a599e0-31e7-49b7-b260-868f441e862b"}Or{ "order_id": "CS1711152257C60TL"}Or{ "error": { "message": "XXXX", "code": "XXX" }}

Returned ValuesSee section Common Returned Values.

3.1.2 Querying BMS Details

Functionl This API is used to query BMS details.l Querying BMS details with the micro version specified is supported. You can add a key

and value pair in the request header. The key is X-OpenStack-Nova-API-Version, andthe value is the micro version number, for example, 2.26. In this case, you query theBMS details with the micro version number 2.26 specified.

URIl URI format

GET /v1/{tenant_id}/baremetalservers/{server_id}l Parameter description



server_id Yes Specifies the BMS ID.


Issue 01 (2018-07-15) 35

Request

N/A

Responsel Parameter description


Description

server Dictionary datastructure [1]

Yes Specifies the BMS information.



Description

name String Yes Specifies the BMS name.

id String Yes Specifies the unique ID of the BMS.

status String Yes Specifies the BMS status.

created String:DateTime Yes Specifies the time when the BMSwas created.

updated String:DateTime Yes Specifies the time when the BMSwas last updated.

flavor Dictionary datastructure [2]

Yes Specifies the BMS flavorinformation.

image Dictionary datastructure [3]

Yes Specifies the BMS image.

tenant_id String Yes Specifies the ID of the tenant towhich the BMS belongs.

key_name String No Specifies the SSH key name.

user_id String Yes Specifies the ID of the user to whichthe BMS belongs.

metadata Dictionary datastructure [5]

Yes Specifies the BMS metadata.

hostId String Yes Specifies the host ID of the BMS.

addresses Dictionary datastructure [6]

Yes Specifies the BMS network address.

security_groups

List datastructure [8]

Yes Specifies the list of security groupsto which the BMS belongs.


Issue 01 (2018-07-15) 36


Description

links List datastructure [4]

Yes Specifies the shortcut links of theBMS.

OS-DCF:diskConfig

String Yes Specifies the disk configurationmode. This is an extended attribute.

OS-EXT-AZ:availability_zone

String Yes Specifies the AZ ID. This is anextended attribute.

OS-EXT-SERVICE:service_state

String No Specifies the BMS service status.This is an extended attribute.

OS-EXT-SRV-ATTR:host

String Yes Specifies the host name of the BMS.This is an extended attribute.

OS-EXT-SRV-ATTR:hypervisor_hostname

String Yes Specifies the name of a host on thehypervisor. This is an extendedattribute provided by the Nova virtdriver.

OS-EXT-SRV-ATTR:instance_name

String Yes Specifies the BMS ID. This is anextended attribute.

OS-EXT-STS:power_state

Integer Yes Specifies the power status of theBMS. This is an extended attribute.Examples:l 0: indicates NO STATE.l 1: indicates RUNNING.l 4: indicates SHUTDOWN.


Issue 01 (2018-07-15) 37


Description

OS-EXT-STS:task_state

String Yes Specifies the task status of the BMS.This is an extended attribute.Examples:l rebooting: indicates that the

BMS is restarting.l reboot_started: indicates that the

BMS is normally restarted.l reboot_started_hard: indicates

that the BMS is forcibly restarted.l powering-off: indicates that the

BMS is being powered off.l powering-on: indicates that the

BMS is being powered on.l rebuilding: indicates that the

BMS is being rebuilt.l scheduling: indicates that the

BMS is being scheduled.l deleting: indicates that the BMS

is being deleted.

OS-EXT-STS:vm_state

String Yes Specifies the BMS status. This is anextended attribute. Examples:l RUNNING: indicates that the

BMS is running.l SHUTOFF: indicates that the

BMS is powered off.l SUSPENDED: indicates that the

BMS is suspended.l REBOOT: indicates that the

BMS is restarted.

OS-SRV-USG:launched_at

String:DateTime Yes Specifies the time when the BMSwas started. This is an extendedattribute.

OS-SRV-USG:terminated_at

String:DateTime No Specifies the time when the BMSwas stopped. This is an extendedattribute.

os-extended-volumes:volumes_attached


No Specifies information about the EVSdisks attached to the BMS.

accessIPv4 String No This is a reserved attribute.

accessIPv6 String No This is a reserved attribute.


Issue 01 (2018-07-15) 38


Description

fault Dictionary datastructure [10]

No Specifies the fault cause. This is anoptional returned attribute.

config_drive String No This is a reserved attribute.

progress Integer Yes This is a reserved attribute.

description String No Specifies description of the BMS.This parameter is added in microversion 2.19.

host_status String No Specifies the nova-compute status.l UP: The nova-compute status is

normal.l UNKNOWN: The nova-compute

status is unknown.l DOWN: the nova-compute status

is abnormal.l MAINTENANCE: The nova-

compute is in the maintenancestate.

l Null: The BMS does not havehost information.

This parameter is added in microversion 2.16.

tags List <String> No Specifies the BMS tag.This parameter is added in microversion 2.26.

[2] flavor field data structure description


Description

id String Yes Specifies the ID of the BMS type.


Yes Specifies the shortcut links of theBMS type.

[3] image field data structure description


Issue 01 (2018-07-15) 39


Description

id String Yes Specifies the ID of the BMS image.


Yes Specifies the shortcut links of theBMS image.

[4] links field data structure description


Description

rel String Yes Specifies the shortcut link markername.

href String Yes Specifies the corresponding shortcutlink.



Description

chargingMode String No Specifies the BMS charging mode.l 0: pay per use (post-paid)l 1: yearly/monthly payment (pre-

paid)

User-definedfield key andvalue pair

String No Specifies the key and value pair ofthe metadata.The maximum size for each metadatakey and value pair is 255 bytes.

[6] addresses field data structure description

Parameter Type Description

VPC ID List data structure [7] Specifies the ID of the VPC used by theBMS (the VPC name is a variable).The value in the data structure isassigned private IP addresses in theVPC.

[7] VPC ID field data structure description


Issue 01 (2018-07-15) 40


Description

addr String Yes Specifies the IP address.

version Integer Yes Specifies the type of the IP address.The value can be 4 or 6.l 4: The type of the IP address is

IPv4.l 6: The type of the IP address is

IPv6.

OS-EXT-IPS-MAC:mac_addr

String Yes Specifies the MAC address. This isan extended attribute.

OS-EXT-IPS:type

String Yes Specifies the IP address assignmentmode. This is an extended attribute.



Description

name String Yes l If no security group is specifiedwhen you create the BMS, thedefault value is used.

l When creating a BMS, you need tospecify the ID of an existingsecurity group (in UUID format).

[9] os-extended-volumes:volumes_attached field data structure description


Description

id String Yes Specifies the EVS disk ID.

delete_on_termination

boolean Yes Specifies whether the EVS disk isdeleted together with the BMS.l true: Yesl false: NoThis parameter is added in microversion 2.3.

[10] fault field data structure description


Issue 01 (2018-07-15) 41


message String Yes Specifies the fault information.

code Int Yes Specifies the fault code.

details String Yes Specifies the fault details.

created String Yes Specifies the time when the faultoccurred. The time is in ISO 8601time format.

l Example response

{ "server": { "tenant_id": "bbf1946d374b44a0a2a95533562ba954", "addresses": { "5849fdf1-9d79-4589-80c2-fe557990c417": [ { "OS-EXT-IPS-MAC:mac_addr": "fa:16:3e:a3:15:6d", "OS-EXT-IPS:type": "fixed", "addr": "192.168.1.201", "version": 4 }, { "OS-EXT-IPS-MAC:mac_addr": "fa:16:3e:33:a4:78", "OS-EXT-IPS:type": "fixed", "addr": "192.168.2.169", "version": 4 }, { "OS-EXT-IPS-MAC:mac_addr": "fa:16:3e:a3:15:6d", "OS-EXT-IPS:type": "floating", "addr": "10.154.72.191", "version": 4 } ], "highway-9f80": [ { "OS-EXT-IPS-MAC:mac_addr": "fa:16:3e:a3:f6:a8", "OS-EXT-IPS:type": "fixed", "addr": "10.0.177.116", "version": 4 } ], "highway-bdcd": [ { "OS-EXT-IPS-MAC:mac_addr": "fa:16:3e:cb:6b:42", "OS-EXT-IPS:type": "fixed", "addr": "172.16.123.79", "version": 4 } ] }, "metadata": { "agency_name": "xxx", "chargingMode": "1" }, "OS-EXT-STS:task_state": null, "OS-DCF:diskConfig": "MANUAL", "OS-EXT-AZ:availability_zone": "kvmxen.dc1", "links": [ { "rel": "self", "href": "https://bms.dc1.domainname.com/v2.1/


Issue 01 (2018-07-15) 42

bbf1946d374b44a0a2a95533562ba954/servers/b5634437-861d-4438-8367-d6bb5c2d9b9f" }, { "rel": "bookmark", "href":"https://bms.dc1.domainname.com/bbf1946d374b44a0a2a95533562ba954/servers/b5634437-861d-4438-8367-d6bb5c2d9b9f" } ], "OS-EXT-STS:power_state": 1, "id": "b5634437-861d-4438-8367-d6bb5c2d9b9f", "os-extended-volumes:volumes_attached": [], "OS-EXT-SRV-ATTR:host": "bms.dc1", "image": { "links": [ { "rel": "bookmark", "href":"https://bms.dc1.domainname.com/bbf1946d374b44a0a2a95533562ba954/images/766a545a-02e1-433e-b1d1-733b5dc95e94" } ], "id": "766a545a-02e1-433e-b1d1-733b5dc95e94" }, "OS-SRV-USG:terminated_at": null, "accessIPv4": "", "accessIPv6": "", "created": "2018-05-22T06:10:02Z", "hostId": "cd243addb5d2c64e89218180b7a3ed95abe6882e81c337cc563137df", "OS-EXT-SRV-ATTR:hypervisor_hostname": "nova002@2", "key_name": "KeyPair-f390-lqq", "flavor": { "links": [ { "rel": "bookmark", "href":"https://bms.dc1.domainname.com/bbf1946d374b44a0a2a95533562ba954/flavors/physical.s1.medium" } ], "id": "physical.s1.medium" }, "security_groups": [ { "name": "default" }, { "name": "default" }, { "name": "default" }, { "name": "default" } ], "config_drive": "", "OS-EXT-STS:vm_state": "active", "OS-EXT-SRV-ATTR:instance_name": "instance-000ea0f1", "user_id": "3fc5ab2b0c544979abcaafd86edd80e6", "name": "csb-edit-name1", "progress": 0, "OS-SRV-USG:launched_at": "2018-05-22T06:27:08.322419", "updated": "2018-05-22T09:18:56Z", "status": "ACTIVE" }}


Issue 01 (2018-07-15) 43


3.2 BMS Status Management

3.2.1 Changing the BMS Name

FunctionThis interface is used to change the name of a BMS.

ConstraintsThe BMS name must meet the following requirements:

l The value can contain a maximum of 63 characters consisting of letters (case-insensitive), digits, underscores (_), hyphens (-), and periods (.).

NOTE

This API can only be used to modify the BMS name. The hostname will not be modified.

URIl URI format

PUT /v1/{ tenant_id }/baremetalservers/{server_id}l Parameter description






server Dictionary datastructure [1]

Yes Specifies the BMS datastructure.



name String No Specifies the new BMS name.


Issue 01 (2018-07-15) 44

l Example request{ "server": { "name": "new-server-test" }}



server Dictionarydata structure[1]

Yes Specifies the BMS information.




id String Yes Specifies the unique ID of theBMS.

status String Yes Specifies the current status of theBMS.

created String:DateTime

Yes Specifies the time when the BMSwas created.

updated String:DateTime

Yes Specifies the time when the BMSwas last updated.

flavor Dictionarydata structure[2]


image Dictionarydata structure[3]


tenant_id String Yes Specifies the ID of the tenant towhich the BMS belongs.

key_name String Yes Specifies the SSH key name.

user_id String Yes Specifies the ID of the user towhich the BMS belongs.

metadata Dictionarydata structure[5]


hostId String Yes Specifies the host ID of the BMS.


Issue 01 (2018-07-15) 45


addresses Dictionarydata structure[6]

Yes Specifies the BMS networkaddress.

security_groups


Yes Specifies the list of security groupsto which the BMS belongs.


Yes Specifies the shortcut links of theBMS.

OS-DCF:diskConfig

String Yes Specifies the disk configurationmode. This is an extended attribute.


String Yes Specifies the AZ ID. This is anextended attribute.


String No Specifies the BMS service status.This is an extended attribute.


String Yes Specifies the host name of theBMS. This is an extended attribute.


String Yes Specifies the name of a host on thehypervisor. This is an extendedattribute provided by the Nova virtdriver.


String Yes Specifies the BMS ID. This is anextended attribute.


Integer Yes Specifies the power status of theBMS. This is an extended attribute.Examples:l 0: indicates NO STATE.l 1: indicates RUNNING.l 4: indicates SHUTDOWN.


Issue 01 (2018-07-15) 46



String Yes Specifies the task status of theBMS. This is an extended attribute.Examples:l rebooting: indicates that the

BMS is restarting.l reboot_started: indicates that

the BMS is normally restarted.l reboot_started_hard: indicates

that the BMS is forciblyrestarted.

l powering-off: indicates that theBMS is being powered off.

l powering-on: indicates that theBMS is being powered on.

l rebuilding: indicates that theBMS is being rebuilt.

l scheduling: indicates that theBMS is being scheduled.

l deleting: indicates that the BMSis being deleted.

OS-EXT-STS:vm_state

String Yes Specifies the BMS status. This is anextended attribute. Examples:l RUNNING: indicates that the

BMS is running.l SHUTOFF: indicates that the

BMS is powered off.l SUSPENDED: indicates that

the BMS is suspended.l REBOOT: indicates that the

BMS is restarted.


String:DateTime

Yes Specifies the time when the BMSwas started. This is an extendedattribute.


String:DateTime

Yes Specifies the time when the BMSwas stopped. This is an extendedattribute.



Yes Specifies information about theEVS disks attached to the BMS.

accessIPv4 String Yes This is a reserved attribute.



Issue 01 (2018-07-15) 47


fault Dictionarydata structure[10]

No Specifies the fault cause. This is anoptional returned attribute.

config_drive String Yes This is a reserved attribute.


description String Yes Specifies description of the BMS.This parameter is added in microversion 2.19.

host_status String Yes Specifies the nova-compute status.l UP: The nova-compute status is

normal.l UNKNOWN: The nova-

compute status is unknown.l DOWN: the nova-compute

status is abnormal.l MAINTENANCE: The nova-

compute is in the maintenancestate.

l Null: The BMS does not havehost information.

This parameter is added in microversion 2.16.

OS-EXT-SRV-ATTR:hostname

String Yes Specifies the hostname of the BMS.This parameter is added in microversion 2.3.

OS-EXT-SRV-ATTR:reservation_id

String Yes Specifies the reserved BMS IDs inthe batch BMS creation scenario.This parameter is added in microversion 2.3.The public cloud system does notsupport this parameter.

OS-EXT-SRV-ATTR:launch_index

Int Yes Specifies the BMS startup sequencein the batch BMS creation scenario.This parameter is added in microversion 2.3.The public cloud system does notsupport this parameter.


Issue 01 (2018-07-15) 48


OS-EXT-SRV-ATTR:kernel_id

String Yes Specifies the UUID of the kernelimage when the AMI image is used.In other scenarios, leave thisparameter blank.This parameter is added in microversion 2.3.The public cloud system does notsupport this parameter.

OS-EXT-SRV-ATTR:ramdisk_id

String Yes Specifies the UUID of the Ramdiskimage when the AMI image is used.In other scenarios, leave thisparameter blank.This parameter is added in microversion 2.3.The public cloud system does notsupport this parameter.

OS-EXT-SRV-ATTR:root_device_name

String Yes Specifies the device name of theBMS system disk.This parameter is added in microversion 2.3.

OS-EXT-SRV-ATTR:user_data

String Yes Specifies the user data specifiedduring BMS creation.

locked boolean Yes Specifies whether a BMS is locked.l true: The BMS is locked.l false: The BMS is not locked.This parameter is added in microversion 2.9.

tags List <String> Yes Specifies the BMS tag.This parameter is added in microversion 2.26.



id String Yes Specifies the flavor ID.


Yes Specifies the shortcut link of theBMS flavor.


Issue 01 (2018-07-15) 49



id String Yes Specifies the ID of the BMS image.


Yes Specifies the shortcut links of theBMS image.




href String Yes Specifies the correspondingshortcut link.




String No Specifies the key and value pair ofthe metadata.The maximum size for eachmetadata key and value pair is 255bytes.



VPC ID List data structure[7]

Specifies the ID of the VPC used by theBMS (the VPC name is a variable).The value in the data structure is assignedprivate IP addresses in the VPC.





Issue 01 (2018-07-15) 50


version Integer Yes Specifies the type of the IPaddress. The value can be 4 or 6.l 4: The type of the IP address is

IPv4.l 6: The type of the IP address is

IPv6.


String Yes Specifies the MAC address. This isan extended attribute.

OS-EXT-IPS:type

String Yes Specifies the IP addressassignment mode. This is anextended attribute.



name String Yes l If no security group isspecified when you create theBMS, the default value isused.

l When creating a BMS, youneed to specify the ID of anexisting security group (inUUID format).





boolean Yes Specifies whether the EVS disk isdeleted together with the BMS.l true: Yesl false: NoThis parameter is added in microversion 2.3.



Issue 01 (2018-07-15) 51






l Example response

{ "server": { "tenant_id": "c685484a8cc2416b97260938705deb65", "addresses": { "08a7715f-7de6-4ff9-a343-95ba4209f24a": [ { "OS-EXT-IPS-MAC:mac_addr": "fa:16:3e:0e:c4:77", "OS-EXT-IPS:type": "fixed", "addr": "192.168.0.107", "version": 4 } ] }, "metadata": { "op_svc_userid": "1311c433dd9b408886f57d695c229cbe" }, "OS-EXT-STS:task_state": null, "OS-DCF:diskConfig": "MANUAL", "OS-EXT-AZ:availability_zone": "eu-de-01", "links": [ { "rel": "self", "href": "https://ecs-api.eu-de.otc-tsi.de/v2.1/c685484a8cc2416b97260938705deb65/servers/95bf2490-5428-432c-ad9b-5e3406f869dd" }, { "rel": "bookmark", "href": "https://ecs-api.eu-de.otc-tsi.de/c685484a8cc2416b97260938705deb65/servers/95bf2490-5428-432c-ad9b-5e3406f869dd" } ], "OS-EXT-STS:power_state": 1, "id": "95bf2490-5428-432c-ad9b-5e3406f869dd", "os-extended-volumes:volumes_attached": [ { "id": "dfa375b5-9856-44ad-a937-a4802b6434c3" }, { "id": "bb9f1b27-843b-4561-b62e-ca18eeaec417" }, { "id": "86e801c3-acc6-465d-890c-d43ba493f553" }, { "id": "0994d3ac-3c6a-495c-a439-c597a4f08fa6" } ], "OS-EXT-SRV-ATTR:host": "bms.eu-de-01", "image": { "links": [


Issue 01 (2018-07-15) 52

{ "rel": "bookmark", "href": "https://ecs-api.eu-de.otc-tsi.de/c685484a8cc2416b97260938705deb65/images/1a6635d8-afea-4f2b-abb6-27a202bad319" } ], "id": "1a6635d8-afea-4f2b-abb6-27a202bad319" }, "OS-SRV-USG:terminated_at": null, "accessIPv4": "", "accessIPv6": "", "created": "2017-05-24T06:14:05Z", "hostId": "e9c3ee0fcc58ab6085cf30df70b5544eab958858fb50d925f023e53e", "OS-EXT-SRV-ATTR:hypervisor_hostname": "nova004@2", "key_name": "KeyPair-JX", "flavor": { "links": [ { "rel": "bookmark", "href": "https://ecs-api.eu-de.otc-tsi.de/c685484a8cc2416b97260938705deb65/flavors/physical.83.medium" } ], "id": "physical.83.medium" }, "security_groups": [ { "name": "0011b620-4982-42e4-ad12-47c95ca495c4" } ], "config_drive": "", "OS-EXT-STS:vm_state": "active", "OS-EXT-SRV-ATTR:instance_name": "instance-0000ebd3", "user_id": "1311c433dd9b408886f57d695c229cbe", "name": "bms-83", "progress": 0, "OS-SRV-USG:launched_at": "2017-05-25T03:40:25.066078", "updated": "2017-05-25T03:40:25Z", "status": "ACTIVE" } }

Returned Values

See section Common Returned Values.

3.3 BMS Disk Management

3.3.1 Attaching an EVS Disk to a BMS

Function

This interface is used to attach an EVS disk to a BMS.

Constraintsl A bootable disk cannot be attached to a BMS.l A disk cannot be attached to a BMS when the BMS is in the SUSPENDED or PAUSED

state, which is specified using the OS-EXT-STS:vm_state parameter.


Issue 01 (2018-07-15) 53

l Only a shared disk or a disk in the available state can be attached to a BMS.l Only EVS disks whose device type is SCSI can be attached to a BMS.

URIl URI format

POST /v1/{tenant_id}/baremetalservers/{server_id}/attachvolumel Parameter description






Description

volumeAttachment

Dict Yes Specifies information about the disk tobe attached to the BMS. For details,see [1] volumeAttachment field datastructure description.

[1] volumeAttachment field data structure description


Description

volumeId UUID Yes Specifies the ID of the disk to beattached to a BMS.

device String No Specifies the mount point, suchas /dev/sda and /dev/sdb.The new disk mount point cannot bethe same as an existing one.The mount point must be specifiedbased on the sequence of existingdevice names. If this parameter is leftblank or set to "", the systemautomatically generates a mount point.

l Example request

{ "volumeAttachment": { "volumeId": "b53f23bd-ee8f-49ec-9420-d1acfeaf91d6", "device": "" }}


Issue 01 (2018-07-15) 54

Response

N/A

Returned Values


3.3.2 Detaching an EVS Disk from a BMS

Function

This interface is used to detach an EVS disk from a BMS.

Constraints

If a BMS is stopped, disks can be detached from it without any limitation on the OS. If aBMS is in running state, the constraints are as follows:

l Before detaching an EVS disk from a Linux BMS, log in to the BMS, run the unmountcommand to disassociate the disk to be detached from the file system, and ensure that noprogram is reading data from or writing data to the disk. Otherwise, the disk will fail tobe detached.

l Before detaching an EVS disk from a running Windows BMS, ensure that no program isreading data from or writing data to the disk. Otherwise, data will be lost.

URIl URI format

DELETE /v1/{tenant_id}/baremetalservers/{server_id}/detachvolume/{attachment_id}l Parameter description




attachment_id Yes Specifies the ID of the EVS disk of a BMS.

Request

N/A

Response

N/A

Returned Values



Issue 01 (2018-07-15) 55

3.4 Querying Task Statuses

3.4.1 Querying Task Statuses

FunctionThis interface is used to query the execution status of a task, such as ECS creation, ECSdeletion, ECS batch operation, and NIC operation.

After a task, such as creating a BMS or attaching disks, is issued, job_id is returned, based onwhich you can query the execution status of the task.

URIl URI format

GET /v1/{tenant_id}/jobs/{job_id}l Parameter description



job_id Yes Job ID

RequestN/A



Description

status String Yes Specifies the task status.l SUCCESS: The task is successful.l RUNNING: The task is running.l FAIL: The task failed.l INIT: The task is being initialized.


Issue 01 (2018-07-15) 56


Description

entities Dictionarydatastructure. Fordetails, seeTable 3-1.

Yes Specifies the task object.The displayed information variesdepending on the task type. Foroperations associated with BMSs,server_id is displayed. For operationsassociated with NICs, nic_id is displayed.If subtasks exist, details of the subtasksare displayed.

job_id String Yes Job ID

job_type String Yes Specifies the task type.

begin_time String Yes Specifies the start time.

end_time String Yes Specifies the end time.

error_code String Yes Specifies the error code returned upon atask execution failure.

fail_reason String Yes Specifies the cause of a task executionfailure.

message String No Specifies the message returned when anerror occurs.

code String No Specifies the error code returned when anerror occurs.For details about error codes, see sectionCommon Returned Values.

sub_jobs_total

Integer No Specifies the number of subtasks. If thetask has no subtasks, the value of thisparameter is 0.

sub_jobs List datastructure. Fordetails, seeTable 3-2.

No Specifies the execution information abouta subtask. If the task has no subtasks, thevalue of this parameter is left blank.

Table 3-1 entities field data structure description


sub_jobs_total Integer Specifies the number of subtasks. Ifthe task has no subtasks, the value ofthis parameter is 0.


Issue 01 (2018-07-15) 57


sub_jobs List data structure. Fordetails, see Table 3-2.

Specifies the execution informationabout a subtask. If the task has nosubtasks, the value of this parameteris left blank.

Table 3-2 sub_jobs field data structure description


status String Specifies the task status.l SUCCESS: The task is successful.l RUNNING: The task is running.l FAIL: The task failed.l INIT: The task is being initialized.

entities List data structure.For details, seeTable 3-3.

Specifies the task object. The displayedinformation varies depending on the tasktype. For operations associated with BMSs,server_id is displayed. For operationsassociated with NICs, nic_id is displayed.

job_id String Job ID

job_type String Specifies the task type.

begin_time String Specifies the start time.

end_time String Specifies the end time.

error_code String Specifies the error code returned upon atask execution failure.

fail_reason String Specifies the cause of a task executionfailure.

message String Specifies the message returned when anerror occurs.

code String Specifies the error code returned when anerror occurs.For details about error codes, see sectionCommon Returned Values.


Issue 01 (2018-07-15) 58

Table 3-3 entities field data structure description


server_id String If the task is a BMS-related operation, thevalue is server_id.

nic_id String If the task is a NIC-related operation, thevalue is nic_id.

l Example response

{ "status": "SUCCESS", "entities": { "sub_jobs_total": 1, "sub_jobs": [ { "status": "SUCCESS", "entities": { "server_id": "bae51750-0089-41a1-9b18-5c777978ff6d" }, "job_id": "2c9eb2c5544cbf6101544f0635672b60", "job_type": "createSingleServer", "begin_time": "2016-04-25T20:04:47.591Z", "end_time": "2016-04-25T20:08:21.328Z", "error_code": null, "fail_reason": null } ] }, "job_id": "2c9eb2c5544cbf6101544f0602af2b4f", "job_type": "createServer", "begin_time": "2016-04-25T20:04:34.604Z", "end_time": "2016-04-25T20:08:41.593Z", "error_code": null, "fail_reason": null}


Error CodesSee section Error Codes.

3.5 BMS Lifecycle Management (Native OpenStack APIs)

3.5.1 Querying Details About a BMS (Native OpenStack API)

FunctionThis interface is used to query details about a BMS by the BMS ID. The interface version isv2.1 Querying with the micro version number is supported. You can add a key and value pairin the request header. The key is X-OpenStack-Nova-API-Version, and the value is themicro version number, for example, 2.26. In this case, you query the BMS details with themicro version number 2.26 specified.


Issue 01 (2018-07-15) 59

URIl URI format

GET /v2.1/{tenant_id}/servers/{server_id}l Parameter description




Request

N/A



server Dictionarydata structure[1]

Yes Specifies the BMSinformation.




id String Yes Specifies the unique ID ofthe BMS.

status String Yes Specifies the BMS status.

created String:DateTime Yes Specifies the time when theBMS was created.

updated String:DateTime Yes Specifies the time when theBMS was last updated.

flavor Dictionary datastructure [2]


image Dictionary datastructure [3]


tenant_id String Yes Specifies the ID of the tenantto which the BMS belongs.

key_name String Yes Specifies the SSH key name.


Issue 01 (2018-07-15) 60


user_id String Yes Specifies the ID of the userto which the BMS belongs.

metadata Dictionary datastructure [5]


hostId String Yes Specifies the host ID of theBMS.

addresses Dictionary datastructure [6]

Yes Specifies the BMS networkaddress.

security_groups


Yes Specifies the list of securitygroups to which the BMSbelongs.


Yes Specifies the shortcut linksof the BMS.

OS-DCF:diskConfig

String Yes Specifies the diskconfiguration mode. This isan extended attribute.


String Yes Specifies the AZ ID. This isan extended attribute.


String No Specifies the BMS servicestatus. This is an extendedattribute.


String Yes Specifies the host name ofthe BMS. This is anextended attribute.


String Yes Specifies the name of a hoston the hypervisor. It is anextended attribute providedby the Nova virt driver.


String Yes Specifies the BMS ID. Thisis an extended attribute.


Integer Yes Specifies the power status ofthe BMS. This is anextended attribute.


String Yes Specifies the job status ofthe BMS. This is anextended attribute.


Issue 01 (2018-07-15) 61


OS-EXT-STS:vm_state

String Yes Specifies the BMS status.This is an extended attribute.


String:DateTime Yes Specifies the time when theBMS was started. This is anextended attribute.


String:DateTime Yes Specifies the time when theBMS was stopped. This is anextended attribute.



Yes Specifies information aboutthe EVS disks attached tothe BMS.



fault Dictionary datastructure [10]

Yes Specifies the fault cause.This is an optional returnedattribute.

config_drive String Yes This is a reserved attribute.


description String Yes Provides supplementaryinformation about the pool.Added in micro version2.19.

host_status String Yes Specifies the nova-computestatus.l UP: The nova-compute is

normal.l UNKNOWN: The nova-

compute status isunknown.

l DOWN: the nova-compute status isabnormal.

l MAINTENANCE: Thenova-compute is in themaintenance state.

l Null: The BMS does nothave host information.

Added in micro version2.16.


Issue 01 (2018-07-15) 62


OS-EXT-SRV-ATTR:hostname

String Yes Specifies the hostname ofthe BMS.Added in micro version 2.3.

OS-EXT-SRV-ATTR:reservation_id

String Yes Specifies the reserved BMSIDs in the batch BMScreation scenario.Added in micro version 2.3.The public cloud systemdoes not support thisparameter.

OS-EXT-SRV-ATTR:launch_index

Int Yes Specifies the BMS startupsequence in the batch BMScreation scenario.Added in micro version 2.3.The public cloud systemdoes not support thisparameter.

OS-EXT-SRV-ATTR:kernel_id

String Yes Specifies the UUID of thekernel image when the AMIimage is used. In otherscenarios, leave thisparameter blank.Added in micro version 2.3.The public cloud systemdoes not support thisparameter.

OS-EXT-SRV-ATTR:ramdisk_id

String Yes Specifies the UUID of theRamdisk image when theAMI image is used. In otherscenarios, leave thisparameter blank.Added in micro version 2.3.The public cloud systemdoes not support thisparameter.

OS-EXT-SRV-ATTR:root_device_name

String Yes Specifies the device name ofthe BMS system disk.Added in micro version 2.3.

OS-EXT-SRV-ATTR:user_data

String Yes Specifies the user dataspecified during BMScreation.


Issue 01 (2018-07-15) 63


locked boolean Yes Specifies whether a BMS islocked.l true: The BMS is locked.l false: The BMS is not

locked.Added in micro version 2.9.

tags List <String> Yes Specifies the BMS tag.Added in micro version2.26.



id String Yes Specifies the ID of the BMStype.


Yes Specifies the shortcut links ofthe BMS type.



id String Yes Specifies the ID of the BMSimage.


Yes Specifies the shortcut links ofthe BMS image.



rel String Yes Specifies the shortcut linkmarker name.




Issue 01 (2018-07-15) 64



String No Specifies the key and value pair of themetadata.The maximum size for each metadatakey and value pair is 255 bytes.



VPC ID List data structure [7] Specifies the ID of the VPC used by theBMS (the VPC name is a variable).The value in the data structure isassigned private IP addresses in theVPC.




version Integer Yes Specifies the type of the IPaddress. The value can be 4 or6.l 4: The type of the IP

address is IPv4.l 6: The type of the IP

address is IPv6.


String Yes Specifies the MAC address.This is an extended attribute.

OS-EXT-IPS:type String Yes Specifies the IP addressassignment mode. This is anextended attribute.



Issue 01 (2018-07-15) 65


name String Yes l If no security group is specifiedwhen you create the BMS, thedefault value is used.

l If a security group is specifiedwhen you create the BMS, thevalue is the ID of the VPC towhich the BMS belongs.





boolean Yes Specifies whether the EVSdisk is deleted together withthe BMS.l true: Yesl false: NoAdded in micro version 2.3.







l Example response

{ "server": { "tenant_id": "c685484a8cc2416b97260938705deb65", "addresses": { "08a7715f-7de6-4ff9-a343-95ba4209f24a": [ { "OS-EXT-IPS-MAC:mac_addr": "fa:16:3e:0e:c3:77", "OS-EXT-IPS:type": "fixed", "addr": "192.168.0.107", "version": 4 } ] }, "metadata": { "op_svc_userid": "1311c433dd9b408886f57d695c229cbe"


Issue 01 (2018-07-15) 66

}, "OS-EXT-STS:task_state": null, "OS-DCF:diskConfig": "MANUAL", "OS-EXT-AZ:availability_zone": "eu-de-01", "links": [ { "rel": "self", "href": "https://ecs-api.eu-de.otc-tsi.de/v2.1/c685484a8cc2416b97260938705deb65/servers/95bf2490-5428-432c-ad9b-5e3406f869dd" }, { "rel": "bookmark", "href": "https://ecs-api.eu-de.otc-tsi.de/c685484a8cc2416b97260938705deb65/servers/95bf2490-5428-432c-ad9b-5e3406f869dd" } ], "OS-EXT-STS:power_state": 1, "id": "95bf2490-5428-432c-ad9b-5e3406f869dd", "os-extended-volumes:volumes_attached": [ { "id": "dfa375b5-9856-44ad-a937-a4802b6434c3" }, { "id": "bb9f1b27-843b-4561-b62e-ca18eeaec417" }, { "id": "86e801c3-acc6-465d-890c-d43ba493f553" }, { "id": "0994d3ac-3c6a-495c-a439-c597a4f08fa6" } ], "OS-EXT-SRV-ATTR:host": "bms.eu-de-01", "image": { "links": [ { "rel": "bookmark", "href": "https://ecs-api.eu-de.otc-tsi.de/c685484a8cc2416b97260938705deb65/images/1a6635d8-afea-4f2b-abb6-27a202bad319" } ], "id": "1a6635d8-afea-4f2b-abb6-27a202bad319" }, "OS-SRV-USG:terminated_at": null, "accessIPv4": "", "accessIPv6": "", "created": "2017-05-24T06:14:05Z", "hostId": "e9c3ee0fcc58ab6085cf30df70b5544eab958858fb50d925f023e53e", "OS-EXT-SRV-ATTR:hypervisor_hostname": "nova004@2", "key_name": "KeyPair-JX", "flavor": { "links": [ { "rel": "bookmark", "href": "https://ecs-api.eu-de.otc-tsi.de/c685484a8cc2416b97260938705deb65/flavors/physical.83.medium" } ], "id": "physical.83.medium" }, "security_groups": [ { "name": "0011b620-4982-42e4-ad12-47c95ca495c4" } ], "config_drive": "", "OS-EXT-STS:vm_state": "active", "OS-EXT-SRV-ATTR:instance_name": "instance-0000ebd3", "user_id": "1311c433dd9b408886f57d695c229cbe",


Issue 01 (2018-07-15) 67

"name": "bms-83", "progress": 0, "OS-SRV-USG:launched_at": "2017-05-25T03:40:25.066078", "updated": "2017-05-25T03:40:25Z", "status": "ACTIVE" }}

Returned Values


3.5.2 Querying BMSs (Native OpenStack API)

Function

This interface is used query BMSs using search criteria and to display the BMSs in a list. Theinterface version is v2.1. Querying with the micro version number is supported. You can add akey and value pair in the request header. The key is X-OpenStack-Nova-API-Version, andthe value is the micro version number, for example, 2.26. In this case, you query the BMSswith the micro version number 2.26 specified.

Constraintsl The query result returned by this interface includes both ECSs and BMSs. You need to

filter out the BMSs using the flavor used to create the BMSs or the tags added to theBMSs during BMS creation.

l If the image is used as the search criteria, other search criteria and pagination criteria arenot supported. If both the image and other search criteria are used, the BMSs are filteredout by image. If the image is not used as the search criteria, this interface has norestrictions.

URIl URI format

GET /v2.1/{tenant_id}/servers

l Parameter description



The following table lists the optional parameters that can be used to query BMSs.

[1] Optional parameters that can be used to query BMSs


image String No Specifies the image ID.

flavor String No Specifies the flavor ID.


Issue 01 (2018-07-15) 68


name String No Specifies the BMS name. Thisparameter supports fuzzymatching.For example, regular expression ?name=bob will return both boband bobb. To obtain only bob,you can use a regular expressionmatching the basic databasesyntax, such as MySQL orPostgreSQL (official website:https://www.postgresql.org/docs/9.2/static/functions-matching.html).

status String No Specifies the BMS status. Onlythe administrators can use thedeleted state to filter out deletedBMSs.

changes-since

String No Filters out the BMSs that havebeen updated since the changes-since time. The parameter is inISO 8601 time format, forexample, 2013-06-09T06:42:18Z.

all_tenants Int No Specifies whether to query theBMSs of all tenants. Thisparameter is available only toadministrators. The value can be0 (do not query the BMSs of alltenants) or 1 (query the BMSs ofall tenants).

ip String No Specifies the IP address. Thisparameter supports fuzzymatching.

deleted boolean No Filters out all deleted BMSs. Thisparameter is available only toadministrators.

tags String No Specifies the tag list. ReturnsBMSs that match all tags. Usecommas (,) to separate multipletags.Added in micro version 2.26.

tags-any String No Specifies the tag list. ReturnsBMSs that match any tag. Usecommas (,) to separate multipletags.Added in micro version 2.26.


Issue 01 (2018-07-15) 69

https://www.postgresql.org/docs/9.2/static/functions-matching.html




not-tags String No Specifies the tag list. ReturnsBMSs that do not match all tags.Use commas (,) to separatemultiple tags.Added in micro version 2.26.

not-tags-any String No Specifies the tag list. ReturnsBMSs that do not match any ofthe tags. Use commas (,) toseparate multiple tags.Added in micro version 2.26.

sort_key String No Specifies the BMS sortingattribute, which can be the BMSUUID (uuid), BMS status(vm_state), BMS name(display_name), BMS task status(task_state), power status(power_state), creation time(created_at), last time when theBMS is updated (updated_at),and availability zone(availability_zone). You canspecify multiple sort_key andsort_dir pairs.

sort_dir String No Specifies the sorting direction.l asc: The query results are

displayed in ascending order.l desc (default value): The

query results are displayed indescending order.

Request

N/A



servers List datastructure [2]

Yes Specifies the BMS list.

[2] servers field data structure description


Issue 01 (2018-07-15) 70



id String Yes Specifies the unique ID ofthe BMS.


Yes Specifies the shortcut linksof the BMS.



rel String Yes Specifies the shortcut linkmarker name.


l Example response{ "servers": [ { "name": "bms", "links": [ { "rel": "self", "href": "https://ecs-api.eu-de.otc-tsi.de/v2.1/c685484a8cc2416b97260938705deb65/servers/820abbd0-2d8b-4bc5-ae46-69cacfd4fbaa" }, { "rel": "bookmark", "href": "https://ecs-api.eu-de.otc-tsi.de/c685484a8cc2416b97260938705deb65/servers/820abbd0-2d8e-4bc5-ae46-69cacfd4fbaa" } ], "id": "820abbd0-2d8e-4bc5-ae46-69cacfd4fbaa" } ]}

Returned Values


3.5.3 Querying Details About BMSs (Native OpenStack API)

Function

This interface is used query details about BMSs using search criteria and to display the BMSdetails in a list. The interface version is v2.1. Querying with the micro version number issupported. You can add a key and value pair in the request header. The key is X-OpenStack-Nova-API-Version, and the value is the micro version number, for example, 2.26. In thiscase, you query the BMS details with the micro version number 2.26 specified.


Issue 01 (2018-07-15) 71

Constraintsl The query result returned by this interface includes both ECS and BMS details. You need

to filter out the BMS details using the flavor used to create the BMSs or the tags addedto the BMSs during BMS creation.

l If the image is used as the search criteria, other search criteria and pagination criteria arenot supported. If both the image and other search criteria are used, the BMS details arefiltered out by image. If the image is not used as the search criteria, this interface has norestrictions.

URIl URI format

GET /v2.1/{tenant_id}/servers/detaill Parameter description



The [1] table in section Querying BMSs (Native OpenStack API) lists the optionalparameters that can be used to query BMSs.

RequestN/A



servers List datastructureFor details, see[1] serverfield datastructuredescription insectionQueryingDetails Abouta BMS(NativeOpenStackAPI).

Yes Specifies the BMS details list.

l Example response

{ "servers": [ {


Issue 01 (2018-07-15) 72

"tenant_id": "c685484a8cc2416b97260938705deb64", "addresses": { "08a7715f-7de6-4ff9-a343-95ba4209f24a": [ { "OS-EXT-IPS-MAC:mac_addr": "fa:16:3e:0e:c4:77", "OS-EXT-IPS:type": "fixed", "addr": "192.168.0.107", "version": 4 } ] }, "metadata": { "op_svc_userid": "1311c433dd9b408886f57d695c229cbe" }, "OS-EXT-STS:task_state": null, "OS-DCF:diskConfig": "MANUAL", "OS-EXT-AZ:availability_zone": "eu-de-01", "links": [ { "rel": "self", "href": "https://ecs-api.eu-de.otc-tsi.de/v2.1/c685484a8cc2416b97260938705deb65/servers/95bf2490-5428-432c-ad9b-5e3406f869dd" }, { "rel": "bookmark", "href": "https://ecs-api.eu-de.otc-tsi.de/c685484a8cc2416b97260938705deb65/servers/95bf2490-5428-432c-ad9b-5e3406f869dd" } ], "OS-EXT-STS:power_state": 1, "id": "95bf2490-5428-432c-ad9b-5e3406f869dd", "os-extended-volumes:volumes_attached": [ { "id": "dfa375b5-9856-44ad-a937-a4802b6434c3" }, { "id": "bb9f1b27-843b-4561-b62e-ca18eeaec417" }, { "id": "86e801c3-acc6-465d-890c-d43ba493f553" }, { "id": "0994d3ac-3c6a-495c-a439-c597a4f08fa6" } ], "OS-EXT-SRV-ATTR:host": "bms.eu-de-01", "image": { "links": [ { "rel": "bookmark", "href": "https://ecs-api.eu-de.otc-tsi.de/c685484a8cc2416b97260938705deb65/images/1a6635d8-afea-4f2b-abb6-27a202bad319" } ], "id": "1a6635d8-afea-4f2b-abb6-27a202bad319" }, "OS-SRV-USG:terminated_at": null, "accessIPv4": "", "accessIPv6": "", "created": "2017-05-24T06:14:05Z", "hostId": "e9c3ee0fcc58ab6085cf30df70b5544eab958858fb50d925f023e53e", "OS-EXT-SRV-ATTR:hypervisor_hostname": "nova004@2", "key_name": "KeyPair-JX", "flavor": { "links": [ { "rel": "bookmark", "href": "https://ecs-api.eu-de.otc-tsi.de/


Issue 01 (2018-07-15) 73

c685484a8cc2416b97260938705deb65/flavors/physical.83.medium" } ], "id": "physical.83.medium" }, "security_groups": [ { "name": "0011b620-4982-42e4-ad12-47c95ca495c4" } ], "config_drive": "", "OS-EXT-STS:vm_state": "active", "OS-EXT-SRV-ATTR:instance_name": "instance-0000ebd3", "user_id": "1311c433dd9b408886f57d695c229cbe", "name": "bms", "progress": 0, "OS-SRV-USG:launched_at": "2017-05-25T03:40:25.066078", "updated": "2017-05-25T03:40:25Z", "status": "ACTIVE" } ]}


3.6 BMS Status Management (Native OpenStack APIs)

3.6.1 Starting a BMS (Native OpenStack API)

FunctionThis interface is used to start a single BMS.

URIl URI format

POST /v2/{tenant_id}/servers/{server_id}/actionl Parameter description






Issue 01 (2018-07-15) 74

Parameter

Type Mandatory Description

os-start Emptystructure

Yes Specifies the operation to start the BMS.The data structure is empty.

l Example request

{ "os-start": {} }

ResponseN/A


3.6.2 Restarting a BMS (Native OpenStack API)

FunctionThis interface is used to restart a single BMS.

Constraintsl Currently, only forcible restart is supported.

URIl URI format

POST /v2/{tenant_id}/servers/{server_id}/actionl Parameter description






reboot Dictionarydatastructure [1]

Yes Specifies the operation of restartingthe BMS.


Issue 01 (2018-07-15) 75

[1] reboot field data structure description


type String Yes Specifies the type of the restartoperation.l SOFT: soft restartl HARD: forcible restart

NOTECurrently, value SOFT is invalid.All BMS restart operations areforcible restart.

l Example request{ "reboot": { "type": "HARD" } }

Response

N/A

Returned Values


3.6.3 Stopping a BMS (Native OpenStack API)

Function

This interface is used to stop a single BMS.

Constraintsl The BMS OS-EXT-STS:vm_state attribute (BMS status) must be active or error.

l Currently, only forcible stopping is supported.

URIl URI format

POST /v2/{tenant_id}/servers/{server_id}/action






Issue 01 (2018-07-15) 76



os-stop Null ordictionarydatastructure[1]

Yes Specifies the operation of stoppingthe BMS.

[1] os-stop field data structure description


type String No Specifies the type of the BMSstopping operation.l SOFT: normal BMS

stoppingl HARD: Forcible BMS

stoppingNOTE

Currently, this parameter isinvalid. All BMS stoppingoperations are forciblestopping.

l Example request{ "os-stop": {}}

Response

N/A

Returned Values


3.6.4 Querying BMS Metadata (Native OpenStack API)

Function

This interface is used to query BMS metadata.

Constraintsl Pagination query is not supported.


Issue 01 (2018-07-15) 77

URIl URI format

GET /v2/{tenant_id}/servers/{server_id}/metadatal Parameter description




RequestN/A



metadata Dictionary datastructure[1]

Yes Specifies the user-defined metadatakey and value pair.




String No Specifies the key and value pair ofthe metadata.The maximum size for eachmetadata key and value pair is 255bytes.

l Example response

{ "metadata": { "key": "value" }}



Issue 01 (2018-07-15) 78

3.6.5 Updating BMS Metadata (Native OpenStack API)

FunctionThis interface is used to update BMS metadata.

l If the metadata does not contain the target field, the field is automatically added to thefield.

l If the metadata contains the target field, the field value is automatically updated.

Constraintsl The BMS OS-EXT-STS:vm_state attribute (BMS status) must be active, stopped,

paused, or suspended.

URIl URI format

POST /v2/{tenant_id}/servers/{server_id}/metadatal Parameter description






metadata Dictionarydatastructure [1]

Yes Specifies the user-definedmetadata key and value pair.



Issue 01 (2018-07-15) 79



String Yes Specifies the user-definedmetadata key and value pair.l The maximum size for each

metadata key and value pair is255 bytes.

l The key does not support thefollowing special characters::`~!@#$%^&*()=+<,>?/'";{[]}|\

l The value does not support thefollowing special characters:\"

l Example request

{ "metadata": { "key": "value" } }



metadata Dictionarydatastructure[2]

Yes Specifies the user-defined metadatakey and value pair.




String Yes Specifies the key and value pair ofthe metadata.l The maximum size for each

metadata key and value pair is255 bytes.

l The value does not support thefollowing special characters:\"

l Example response

{ "metadata": { "key": "value" } }


Issue 01 (2018-07-15) 80

Returned Values


3.6.6 Modifying Specified BMS Metadata (Native OpenStackAPI)

Function

This interface is used to modify specified BMS metadata.

Constraintsl The BMS OS-EXT-STS:vm_state attribute (BMS status) must be active, stopped,

paused, or suspended.

URIl URI format

PUT /v2/{tenant_id}/servers/{server_id}/metadata/{key}l Parameter description




key Yes Specifies the BMS metadata key value to bemodified.



meta Dictionarydata structure[1]


[1] meta field data structure description



String Yes Specifies the user-definedmetadata key and value pair.

l Example request


Issue 01 (2018-07-15) 81

{ "meta": { "key": "value" }}



meta Dictionarydatastructure [2]


[2] meta field data structure description



String Yes Specifies the user-definedmetadata key and value pair.The maximum size for eachmetadata key and value pair is255 bytes.

l Example response

{ "meta": { "key": "value" }}

Returned Values


3.6.7 Deleting Specified BMS Metadata (Native OpenStack API)

Function

This interface is used to delete specified BMS metadata.

Constraints

The BMS OS-EXT-STS:vm_state attribute (BMS status) must be active, stopped, paused,or suspended.

URIl URI format

DELETE /v2/{tenant_id}/servers/{server_id}/metadata/{key}


Issue 01 (2018-07-15) 82





key Yes Specifies the BMS metadata key value to bedeleted.

RequestN/A

ResponseN/A


3.7 BMS IP Address Query (Native OpenStack APIs)

3.7.1 Querying IP Addresses of BMSs (Native OpenStack API)

FunctionThis interface is used to query the IP address of a BMS.

ConstraintsPagination query is not supported.

URIl URI format

GET /v2/{tenant_id}/servers/{server_id}/ipsl Parameter description




RequestN/A


Issue 01 (2018-07-15) 83



addresses Dict Yes Specifies the BMS networkinformation. For details, see[1] addresses parameterstructure description.

[1] addresses parameter structure description


BMS networkname

List<Dict>

Yes Specifies the network used bythe BMS. For details about thenetwork information, see [2]Network parameter structuredescription.

[2] Network parameter structure description


version Int Yes Specifies the IP address version.The value can be IPv4 or IPv6.


l Example response{ "addresses": { "08a7715f-7de6-4ff9-a343-95ba4209f24a": [ { "version": 4, "addr": "192.168.2.90" } ] }}

Returned Values


3.7.2 Querying the IP Address of a BMS (Native OpenStack API)

Function

This interface is used to query the IP address of a BMS.


Issue 01 (2018-07-15) 84

URIl URI format

GET /v2/{tenant_id}/servers/{server_id}/ips/{networkName}l Parameter description




networkName Yes Specifies the name of the network used by theBMS.

Request

N/A



BMS networkname

List<Dict>

Yes Specifies the network used bythe BMS. For details about thenetwork information, see [1]Network parameter structuredescription.

[1] Network parameter structure description


version Int Yes Specifies the IP address version.The value can be IPv4 or IPv6.


l Example response

{ "5849fdf1-9d79-4589-80c2-fe557990c417": [ { "version": 4, "addr": "192.168.1.159" } ]}

Returned Values



Issue 01 (2018-07-15) 85

3.8 BMS Flavor Query (Native OpenStack APIs)

3.8.1 Querying BMS Flavors (Native OpenStack API)

Function

This interface is used to query flavors of BMSs and display the query results in a list.

Constraints

The flavors you obtained using this interface are all the flavors in the system. The flavorswhose names starting with physical are BMS flavors and can be used to create BMSs.

URIl URI format

GET /v2/{tenant_id}/flavors/detail{?minDisk,minRam,is_public,sort_key,sort_dir}l Parameter description



The following table lists the optional parameters that can be used to query BMS flavordetails.[1] Optional parameters that can be used to query BMS flavor details


minDisk String No Specifies the minimum disk size inGB. Only the BMSs with a disksize greater than or equal to theminimum size can be queried.

minRam String No Specifies the minimum memorysize in MB. Only the BMSs withthe memory size greater than orequal to the minimum size can bequeried.

is_public Boolean No Specifies whether public flavorsare displayed. The private flavorsare available only to user admin.The value can be true, false, ornone. If this parameter isconfigured by a non-admin user,the system returns all publicimages.


Issue 01 (2018-07-15) 86


sort_key String No Specifies the sorting field. Thedefault value is flavorid. Thevalue of this parameter can also bename, memory_mb, vcpus,root_gb, or flavorid.

sort_dir String No Specifies the sorting order, whichcan be ascending (asc) ordescending (desc). The defaultvalue is asc. You can set thesorting order to ascending ordescending for specificparameters.

RequestN/A



Description

flavors List datastructure [2]

Yes Specifies the list of BMS flavors.

[2] flavors field data structure description


id String Yes Specifies the ID of the BMS flavor.

name String Yes Specifies the name of the BMSflavor.

vcpus Integer Yes Specifies the number of CPU coresin the BMS flavor.

ram Integer Yes Specifies the memory size (MB) inthe BMS flavor.

disk Integer Yes Specifies the disk size (GB) in theBMS flavor.

swap String Yes This is a reserved attribute.


Issue 01 (2018-07-15) 87


OS-FLV-EXT-DATA:ephemeral

Integer Yes This is a reserved attribute.

OS-FLV-DISABLED:disabled

Boolean Yes This is a reserved attribute.

rxtx_factor Float Yes This is a reserved attribute.

os-flavor-access:is_public



Yes Specifies the shortcut link of theBMS flavor.




href String Yes Specifies the corresponding shortcutlink.

l Example response

{ "flavors": [ "name": "physical.84.medium", "links": [{ "href": "https://compute.region.eu-de.otc-tsi.de/v2/c685484a8cc2416b97260938705deb65/flavors/physical.84.medium", "rel": "self" },{ "href": "https://compute.region.eu-de.otc-tsi.de/c685484a8cc2416b97260938705deb65/flavors/physical.84.medium", "rel": "bookmark" } ], "ram": 321725, "OS-FLV-DISABLED:disabled": false, "vcpus": 56, "swap": "", "os-flavor-access:is_public": true, "rxtx_factor": 1, "OS-FLV-EXT-DATA:ephemeral": 0, "disk": 3725, "id": "physical.84.medium" ] }


Issue 01 (2018-07-15) 88

Returned Values


3.8.2 Querying Details About a BMS Flavor (Native OpenStackAPI)

Function

This interface is used to query details about a BMS flavor based on the flavor ID.

URIl URI format

GET /v2/{tenant_id}/flavors/{flavors_id}l Parameter description



flavors_id Yes Specifies the flavor ID.

Request

N/A



flavor Dictionarydata structure[1]

Yes Specifies the BMS flavor.



id String Yes Specifies the ID of the BMSflavor.

name String Yes Specifies the name of theBMS flavor.

vcpus Integer Yes Specifies the number ofCPU cores in the BMSflavor.


Issue 01 (2018-07-15) 89


ram Integer Yes Specifies the memory size(MB) in the BMS flavor.

disk Integer Yes Specifies the disk size (GB)in the BMS flavor.

swap String Yes This is a reserved attribute.

OS-FLV-EXT-DATA:ephemeral

Integer Yes This is a reserved attribute.

OS-FLV-DISABLED:disabled


rxtx_factor Float Yes This is a reserved attribute.

os-flavor-access:is_public


links List datastructure[2]

Yes Specifies the shortcut link ofthe BMS flavor.



rel String Yes Specifies the shortcut link marker name.

href String Yes Specifies the corresponding shortcut link.

l Example response

{ "flavor": { "name": "physical.83.medium", "links": [ { "href": "https://compute.region.eu-de.otc-tsi.de/v2/c685484a8cc2416b97260938705deb65/flavors/physical.83.medium", "rel": "self" }, { "href": "https://compute.region.eu-de.otc-tsi.de/c685484a8cc2416b97260938705deb65/flavors/physical.83.medium", "rel": "bookmark" } ], "ram": 192705, "OS-FLV-DISABLED:disabled": false, "vcpus": 24, "swap": "", "os-flavor-access:is_public": true, "rxtx_factor": 1, "OS-FLV-EXT-DATA:ephemeral": 0, "disk": 1862, "id": "physical.83.medium" } }


Issue 01 (2018-07-15) 90

Returned Values


3.8.3 Querying Details About BMS Flavor extra_specs (NativeOpenStack API)

Function

This interface is used to query details about BMS flavor extra_specs.

URIl URI format

GET /v2/{tenant_id}/flavors/{flavors_id}/os-extra_specsl Parameter description



flavors_id Yes Specifies the flavor ID.

Request

N/A



extra_specs Dict No Specifies the key-value pair of a BMSflavor.NOTE

Local disk: The value ofbaremetal:extBootType is LocalDisk.

System disk (quick BMS provisioning):The value of baremetal:extBootType isVolume.

l Example response

{ "extra_specs": { "capabilities:cpu_arch": "x86_64", "baremetal:disk_detail": "SAS 8T", "capabilities:hypervisor_type": "ironic", "baremetal:__support_evs": "true", "baremetal:extBootType": "LocalDisk", "capabilities:board_type": "s2m", "baremetal:net_num": "2", "baremetal:netcard_detail": "2*10GE", "baremetal:cpu_detail": "2*8coreIntel Xeon E5-2667 V43.2GHz",


Issue 01 (2018-07-15) 91

"resource_type": "ironic", "baremetal:memory_detail": "256GB DDR4 RAM(GB)" }}

Returned Values


Error CodesError Code Description Handling Measure

404 The resource could not befound.

Check whether the flavor exists.

3.9 BMS NIC Management (Native OpenStack APIs)

3.9.1 Querying Information About BMS NICs (Native OpenStackAPI)

Function

This interface is used to query NIC information about BMSs.

URIl URI format

GET /v2/{tenant_id}/servers/{server_id}/os-interfacel Parameter description




Request

N/A



interfaceAttach-ments


Yes Specifies information aboutBMS NICs.


Issue 01 (2018-07-15) 92

[1] interfaceAttachments field data structure description


port_state String Yes Specifies the NIC portstatus.

fixed_ips List datastructure [2]

Yes Specifies the NIC privateIP address.

net_id String Yes Specifies the ID of thenetwork to which the NICport belongs.

port_id String Yes Specifies the ID of the NICport.

mac_addr String Yes Specifies the MAC addressof the NIC.

[2] fixed_ips field data structure description


subnet_id String Yes Specifies the subnet of theNIC private IP address.

ip_address String Yes Specifies the NIC private IPaddress.

l Example response

{ "interfaceAttachments": [ { "port_state": "ACTIVE", "fixed_ips": [ { "subnet_id": "f8a6e8f8-c2ec-497c-9f23-da9616de54ef", "ip_address": "192.168.1.3" } ], "net_id": "3cb9bc59-5699-4588-a4b1-b87f96708bc6", "port_id": "ce531f90-199f-48c0-816c-13e38010b442", "mac_addr": "fa:16:3e:4c:2c:30" } ]}



Issue 01 (2018-07-15) 93

3.9.2 Querying NIC Information About a Specified BMS (NativeOpenStack API)

Function

This interface is used to query information about a BMS NIC based on the NIC ID.

URIl URI format

GET /v2/{tenant_id}/servers/{server_id}/os-interface/{id}l Parameter description




id Yes Specifies the ID of the NIC.

Request

N/A



interfaceAttachment Dictionarydatastructure [1]

Yes Specifies information aboutBMS NICs.

[1] interfaceAttachment field data structure description


port_state String Yes Specifies the NIC portstatus.

fixed_ips List datastructure [2]

Yes Specifies the NIC IPaddress.

net_id String Yes Specifies the ID of thenetwork to which the NICport belongs.

port_id String Yes Specifies the ID of theNIC port.


Issue 01 (2018-07-15) 94


mac_addr String Yes Specifies the MAC addressof the NIC.

[2] fixed_ips field data structure description


subnet_id String Yes Specifies the ID of thesubnet used by the NIC.

ip_address String Yes Specifies the NIC IPaddress.

l Example response

{ "interfaceAttachment": { "port_state": "ACTIVE", "fixed_ips": [{ "subnet_id": "f8a6e8f8-c2ec-497c-9f23-da9616de54ef", "ip_address": "192.168.1.3" } ], "net_id": "3cb9bc59-5699-4588-a4b1-b87f96708bc6", "port_id": "ce531f90-199f-48c0-816c-13e38010b442", "mac_addr": "fa:16:3e:4c:2c:30" } }

Returned Values


3.10 BMS Disk Management (Native OpenStack APIs)

3.10.1 Querying Information About the Disks Attached to a BMS(Native OpenStack API)

Function

This interface is used to query information about the Elastic Volume Service (EVS) disksattached to a BMS.

URIl URI format

GET /v2/{tenant_id}/servers/{server_id}/os-volume_attachmentsl Parameter description


Issue 01 (2018-07-15) 95




RequestN/A



volumeAttachments


Yes Specifies information aboutEVS disks attached to a BMS.

[1] volumeAttachments field data structure description


device String Yes Specifies the directory towhich the disks are mounted.

id String Yes Specifies the ID of theattached resource.

serverId String Yes Specifies the ID of the BMS towhich the disks are attached.

volumeId String Yes Specifies the IDs of the EVSdisks attached to the BMS.

l Example response

{ "volumeAttachment": { "device": "/dev/vdb", "serverId": "820abbd0-2d8e-4bc5-ae46-69cacfd4fbaa", "id": "b53f23bd-ee8f-49ec-9420-d1acfeaf91d6", "volumeId": "b53f23bd-ee8f-49ec-9420-d1acfeaf91d6" }}



Issue 01 (2018-07-15) 96

3.10.2 Querying Information About a Disk Attached to a BMS(Native OpenStack API)

FunctionThis interface is used to query information about a single disk attached to a BMS based on thedisk ID.

URIl URI format

GET /v2/{tenant_id}/servers/{server_id}/os-volume_attachments/{volume_id}l Parameter description



volume_id Yes Specifies the disk ID.

RequestN/A



volumeAttachment Dictionarydatastructure[1]

Yes Specifies information aboutthe EVS disk attached to aBMS.

[1] volumeAttachment field data structure description


device String Yes Specifies the directory towhich the disk is mounted.

id String Yes Specifies the ID of theattached resource.

serverId String Yes Specifies the ID of the BMSto which the disk is attached.

volumeId String Yes Specifies the ID of the diskattached to the BMS.


Issue 01 (2018-07-15) 97

l Example response{ "volumeAttachment": { "device": "/dev/vdb", "serverId": "820abbd0-2d8e-4bc5-ae46-69cacfd4fbaa", "id": "b53f23bd-ee8f-49ec-9420-d1acfeaf91d6", "volumeId": "b53f23bd-ee8f-49ec-9420-d1acfeaf91d6" } }


3.11 BMS SSH Key Pair Management (Native OpenStackAPIs)

3.11.1 Querying SSH Key Pairs (Native OpenStack API)

FunctionThis interface is used to query SSH key pairs and to display the query results in a list.

ConstraintsPagination query is not supported.

URIl URI format

GET /v2/{tenant_id}/os-keypairsl Parameter description



RequestN/A



Issue 01 (2018-07-15) 98


keypairs List datastructure. Fordetails, see[1] keypairsfield datastructuredescription.

Yes Specifies the key pairs.

[1] keypairs field data structure description


keypair Dictionarydata structure.For details,see [2]keypair fielddata structuredescription.

Yes Specifies the key pair details.

[2] keypair field data structure description


fingerprint String Yes Specifies fingerprintinformation about the keypair.

name String Yes Specifies the key pair name.

public_key String Yes Specifies information aboutthe public key in the key pair.

l Example response

{ "keypairs": [ { "keypair": { "fingerprint": "15:b0:f8:b3:f9:48:63:71:cf:7b:5b:38:6d:44:2d:4a", "name": "keypair-601a2305-4f25-41ed-89c6-2a966fc8027a", "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQC+Eo/RZRngaGTkFs7I62ZjsIlO79KklKbMXi8F+KITD4bVQHHn+kV+4gRgkgCRbdoDqoGfpaDFs877DYX9n4z6FrAIZ4PES8TNKhatifpn9NdQYWA+IkU8CuvlEKGuFpKRi/k7JLos/gHi2hy7QUwgtRvcefvD/vgQZOVw/mGR9Q== Generated-by-Nova" } } ]}


Issue 01 (2018-07-15) 99

Returned Values


3.11.2 Querying an SSH Key Pair (Native OpenStack API)

Function

This interface is used to query a specified SSH key pair based on the key pair name.

URIl URI format

GET /v2/{tenant_id}/os-keypairs/{keypair_name}l Parameter description



keypair_name Yes Specifies the key pairname.

Request

N/A



keypair Dictionarydatastructure.For details,see [1]keypairfield datastructuredescription.

Yes Specifies information about theSSH key pair.



public_key String Yes Specifies information about thepublic key in the key pair.


Issue 01 (2018-07-15) 100



fingerprint String Yes Specifies fingerprint informationabout the key pair.

created_at String:DateTime

Yes Specifies the time when the keypair was created.

deleted Boolean Yes Specifies the deleted key pair.

deleted_at String:DateTime

Yes Specifies the time when the keypair was deleted.

id String Yes Specifies the key pair ID.

updated_at String:DateTime

Yes Specifies the time when the keypair was updated.

user_id String Yes Specifies information about theuser to which the key pairbelongs.

l Example response{ "keypair": { "created_at": "2014-05-07T12:06:13.681238", "deleted": false, "deleted_at": null, "fingerprint": "9d:00:f4:d7:26:6e:52:06:4c:c1:d3:1d:fd:06:66:01", "id": 1, "name": "keypair-3582d8b7-e588-4aad-b7f7-f4e76f0e4314", "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDYJrTVpcMwFqQy/oMvtUSRofZdSRHEwrsX8AYkRvn2ZnCXM+b6+GZ2NQuuWj+ocznlnwiGFQDsL/yeE+/kurqcPJFKKp60mToXIMyzioFxW88fJtwEWawHKAclbHWpR1t4fQ4DS+/sIbX/Yd9btlVQ2tpQjodGDbM9Tr9/+/3i6rcR+EoLqmbgCgAiGiVV6VbM2Zx79yUwd+GnQejHX8BlYZoOjCnt3NREsITcmWE9FVFy6TnLmahs3FkEO/QGgWGkaohAJlsgaVvSWGgDn2AujKYwyDokK3dXyeX3m2Vmc3ejiqPa/C4nRrCOlko5nSgV/9IXRx1ERImsqZnE9usB Generated-by-Nova", "updated_at": null, "user_id": "fake" }}


3.11.3 Creating and Importing an SSH Key Pair (NativeOpenStack API)

FunctionThis interface is used to create an SSH key pair or import a public key to generate a key pair.

After an SSH key is created, download the private key to a local directory. Then, you can usethis private key to log in to the BMS. To ensure BMS security, the private key can bedownloaded only once. Keep it secure.


Issue 01 (2018-07-15) 101

URIl URI format

POST /v2/{tenant_id}/os-keypairsl Parameter description




NOTE

When creating an SSH key pair, you only need to configure name. When importing a public SSHkey, you must also configure public_key.


keypair Dictionarydatastructure.For details,see [1]keypairfield datastructuredescription.

Yes Specifies information about thecreated SSH key pair orimported public SSH key.



public_key String No Specifies the imported publickey. The maximum size of theimported public key is 1024bytes.Note: If the length of the publickey to be imported exceeds 1024bytes, the public key importingoperation will fail.

name String Yes Specifies the key pair name.The new key pair name cannotbe the same as an existing one.

l Example request

{ "keypair": { "name": "keypair-7d7c3650-dabe-4eb0-b904-5c464453c043",


Issue 01 (2018-07-15) 102

"public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQC9mC3WZN9UGLxgPBpP7H5jZMc6pKwOoSgre8yun6REFktn/Kz7DUt9jaR1UJyRzHxITfCfAIgSxPdGqB/oF1suMyWgu5i0625vavLB5z5kC8Hq3qZJ9zJO1poE1kyD+htiTtPWJ88e12xuH2XB/CZN9OpEiF98hAagiOE0EnOS5Q== Generated by Nova\n" }}



keypair Dictionarydatastructure [1]

Yes Specifies information about theSSH key pair.



fingerprint String Yes Specifies fingerprintinformation about the key pair.


public_key String Yes Specifies information about thepublic key in the key pair.

private_key String No Specifies information about theprivate key.

user_id String Yes Specifies the ID of the user towhich the key pair belongs.

l Example response

{ "keypair": { "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQC9mC3WZN9UGLxgPBpP7H5jZMc6pKwOoSgre8yun6REFktn/Kz7DUt9jaR1UJyRzHxITfCfAIgSxPdGqB/oF1suMyWgu5i0625vavLB5z5kC8Hq3qZJ9zJO1poE1kyD+htiTtPWJ88e12xuH2XB/CZN9OpEiF98hAagiOE0EnOS5Q== Generated by Nova\n", "user_id": "f882feb345064e7d9392440a0f397c25", "name": "keypair-7d7c3650-dabe-4eb0-b904-5c464453c043", "fingerprint": "35:9d:d0:c3:4a:80:d3:d8:86:f1:ca:f7:df:c4:f9:d8" }}



Issue 01 (2018-07-15) 103

3.11.4 Deleting an SSH Key Pair (Native OpenStack API)

Function

This interface is used to delete a specified SSH key pair based on the key pair name.

URIl URI format

DELETE /v2/{tenant_id}/os-keypairs/{keypair_name}




keypair_name Yes Specifies the key pair name.

Request

N/A

Response

N/A

Returned Values


3.12 BMS 1D Tag Management (Native OpenStack APIs)

3.12.1 Querying BMS Tags (Native OpenStack API)

Function

This interface is used to query all tags of a BMS.

You are required to use the HTTP header X-OpenStack-Nova-API-Version: 2.26 to specifythe micro version on the client.

URIl URI format

GET /v2.1/{tenant_id}/servers/{server_id}/tags



Issue 01 (2018-07-15) 104




Request

N/A



tags list<String>

Yes Specifies user-defined tags of aBMS.

l Example response{ "tags": [ "baz", "foo", "qux" ]}

Returned Values


3.12.2 Adding Tags to a BMS (Native OpenStack API)

Function

This interface is used to add tags to a BMS.


Constraints

A BMS can have a maximum of 50 tags.

NOTE

l It is recommended that you add the __type_baremetal tag to BMSs to distinguish BMSs fromECSs. Otherwise, BMSs will be available only on the ECS console.

l A new tag will overwrite the existing one. If you want to retain the original tag, add it to the list ofnew tags. You are advised to add __type_baremetal to the added tags list each time you add a tag.


Issue 01 (2018-07-15) 105

URIl URI format

PUT /v2.1/{tenant_id}/servers/{server_id}/tagsl Parameter description


project_id Yes Specifies the tenant ID.




tags list<string>

Yes l Specifies the tags of a BMS.Each tag can contain amaximum of 80 characters.

l The tag cannot start with a dot(.).

l A BMS can have a maximumof 50 tags.

l An empty tag cannot becreated.

l Example request

{ "tags": [ "baz", "foo", "qux" ]}



tags list<String>

Yes Specifies user-defined tags of aBMS.

l Example response

{ "tags": [ "baz", "foo", "qux" ]}


Issue 01 (2018-07-15) 106


3.12.3 Deleting Tags of a BMS (Native OpenStack API)

FunctionThis interface is used to delete all tags of a BMS.


ConstraintsNOTE

l Tag __type_baremetal is used to identify a BMS. You are not advised to delete this tag. Otherwise,the BMS will be displayed only on the ECS console.

l If __type_baremetal is deleted, you can add it by following the instructions in section 3.12.4Adding a Tag to a BMS. After the tag is added, the BMS is displayed on the BMS console.

URIl URI format

DELETE /v2.1/{tenant_id}/servers/{server_id}/tagsl Parameter description




RequestN/A

ResponseN/A


3.12.4 Adding a Tag to a BMS (Native OpenStack API)

FunctionThis interface is used to add a tag to a BMS.



Issue 01 (2018-07-15) 107

Constraintsl A BMS can have a maximum of 50 tags.

l The tag contains a maximum of 80 characters.

l The tag cannot start with a period (.).

l An empty tag cannot be created.

NOTE

It is recommended that you add the __type_baremetal tag to BMSs to distinguish BMSs from ECSs.

URIl URI format

PUT /v2.1/{tenant_id}/servers/{server_id}/tags/{tag}





tag Yes Specifies the taginformation.Constraints:l The tag contains a

maximum of 80characters.

l The tag cannot startwith a period (.).

l An empty tag cannotbe created.

l URL encoding isrequired for specialcharacters.

Request

N/A

Response

N/A

Returned Values



Issue 01 (2018-07-15) 108

3.12.5 Checking for Tags of a BMS (Native OpenStack API)

Function

This interface is used to check whether a BMS has a specified tag.


URIl URI format

GET /v2.1/{tenant_id}/servers/{server_id}/tags/{tag}l Parameter description




tag Yes Specifies the key of the tagto be queried.Constraints:l URL encoding is

required for specialcharacters.

l If no tag key isspecified, all tags of theBMS are displayed.

Request

N/A

Response

N/A

Returned Values


3.12.6 Deleting a Tag of a BMS (Native OpenStack API)

Function

This interface is used to delete a tag of a BMS.



Issue 01 (2018-07-15) 109

Constraintsl The tag contains a maximum of 80 characters.l If a tag contains non-URL-safe characters, perform URL encoding.

NOTE

l Tag __type_baremetal is used to identify a BMS. You are not advised to delete this tag. Otherwise,the BMS will be displayed only on the ECS console.

l If __type_baremetal is deleted, you can add it by following the instructions in section 3.12.4Adding a Tag to a BMS. After the tag is added, the BMS is displayed on the BMS console.

URIl URI format

DELETE /v2.1/{tenant_id}/servers/{server_id}/tags/{tag}l Parameter description




tag Yes Specifies the taginformation.Constraints:l A tag can contain a

maximum of 80characters. If a tagcontains non-URL-safecharacters, performURL encoding.

l If no tag key isspecified, all tags of theBMS are deleted.

RequestN/A

ResponseN/A



Issue 01 (2018-07-15) 110

4 Return Codes

4.1 Common Returned Valuesl Normal

Returned Value Description

200 OK Specifies the normal response code for the GET and PUToperations.

201 Created Specifies the normal response code for the POSToperation.

202 Accepted The request has been accepted for processing.

204 No Content Specifies the normal response code for the DELETEoperation.

l Abnormal


400 Bad Request The server failed to process the request.

401 Unauthorized You must enter a username and password toaccess the requested page.

403 Forbidden You are forbidden to access the requested page.

404 Not Found The server could not find the requested page.

405 Method Not Allowed You are not allowed to use the methodspecified in the request.

406 Not Acceptable The response generated by the server could notbe accepted by the client.

Bare Metal ServerAPI Reference 4 Return Codes

Issue 01 (2018-07-15) 111


407 Proxy Authentication Required You must use the proxy server forauthentication so that the request can beprocessed.

408 Request Timeout The request timed out.

409 Conflict The request could not be processed due to aconflict.

500 Internal Server Error Failed to complete the request because of aninternal service error.

501 Not Implemented Failed to complete the request because theserver does not support the requested function.

502 Bad Gateway Failed to complete the request because theserver has received an invalid response.

503 Service Unavailable Failed to complete the request because theservice is unavailable.

504 Gateway Timeout A gateway timeout error occurred.

4.2 Error Codes

Contextl An error code returned by an API does not correspond to one error message. The

following table lists only common error messages.l Most BMS APIs are asynchronous. Some error codes are displayed in the returned

messages for task viewing requests. HTTP status codes may not be accurate.l The BMS service is strongly dependent on other services, such as network and storage.

When error messages are provided for the BMS-depended services, contact technicalsupport for troubleshooting.

Error Code DescriptionHTTPStatusCode

ReturnedValue

Description Error Message Troubleshooting

400 BMS.0001

Request error. Fail to parse request,reason: %s

Check the request bodyaccording to the returnederror message.


Issue 01 (2018-07-15) 112

HTTPStatusCode

ReturnedValue


400 BMS.0002

The BMSservice isunavailable.

The BMS service isunavailable.

Select a region where theBMS service is available.

400 BMS.0003

Request error. Create BareMetalServer error, request isnull.

Check the request bodyaccording to the returnederror message.

400 BMS.0004

Insufficientpermission.

role check fail,reason :%s

For details, see thereturned error message orcontact technical support.

400 BMS.0005


role check fail,reason :You do not havepermission or yourbalance is insufficient.


400 BMS.0008

Failed to query aflavor.

Fail to query flavor[%s], reason:%s


400 BMS.0006

Failed to createa task.

Fail to operatebaremetal server!


400 BMS.0009

Failed to queryflavor attributes.

Fail to query flavorextra specs[%s], reason:%s


400 BMS.0010

Failed to queryan image.

Fail to query image[%s], reason: %s


400 BMS.0011

The imageattribute doesnot supportBMSs.

The selected imagescannot be used to applyfor BMSs, %s


400 BMS.0012

Insufficient IPaddresses in theselected subnet.

The number of IPaddresses in the selectedsubnet[%s] isinsufficient.

Check whether the IPaddresses of the subnet areused up.

400 BMS.0013

Failed to queryports.

Fail to query ports bysubnet [%s], reason: %s



Issue 01 (2018-07-15) 113

HTTPStatusCode

ReturnedValue


400 BMS.0014

IP addressconflict.

The specified IP addressconflicts with anexisting IP address insubnet[%s].

Modify the NIC IPaddress.

400 BMS.0015

Failed to querythe NIC.

Fail to query subnet,reason:%s


400 BMS.0017

The EIP quota isinsufficient.

The number[%d] ofEIPs has reached themaximum[%d] allowed.Apply for a higherquota and try again.

Apply for a higher EIPquota.

400 BMS.0218

Failed to createthe order.

Fail to create order,reason :%s


400 BMS.0019

Invalid NICparameters.

publicIp parameter isillegal,reason : %s


400 BMS.0020

Failed to checkthe billing mode.

Fail to checkchargingMode, reason:%s


400 BMS.0021

The selectedflavor cannot beused to createBMSs. Pleaseselect a correctone.

Flavor parameter isillegal,reason : %s

Select a correct flavor.

400 BMS.0023

Failed to querythe quota.

Fail to query limits,reason: %s


400 BMS.0025

The number ofBMSs exceedsthe quota.

The number of cloudservers has reached themaximum allowed.

Apply for a higher quota.

400 BMS.0026

The number ofCPUs of theBMS exceedsthe quota.

The number of CPUcores used by all cloudservers has reached themaximum allowed.



Issue 01 (2018-07-15) 114

HTTPStatusCode

ReturnedValue


400 BMS.0027

The memory ofthe BMSexceeds thequota.

The memory space usedby all cloud servers hasreached the maximumallowed.


400 BMS.0028

The number ofBMSs and CPUsexceeds thequota.

The number of CPUcores used by all cloudservers and that ofcloud servers havereached the maximumallowed.


400 BMS.0029

The number ofBMSs and thememory exceedthe quota.

The memory space usedby all cloud servers andthe number of cloudservers have reached themaximum allowed.


400 BMS.0030

The memory andnumber of CPUsof the BMSexceed thequota.

The memory space andnumber of CPU coresused by all cloudservers have reached themaximum allowed.


400 BMS.0031

The number ofBMSs and CPUsexceeds thequota.

The number of cloudservers, the memoryspace used by all cloudservers, and the numberof CPU cores used byall cloud servers havereached the maximumallowed.


400 BMS.0032

Contact thecustomer servicemanager toapply for aBMS.

token check fail. For details, see thereturned error message orcontact technical support.

400 BMS.0033

You do not haveoperation rights.Contact theadministrator.

fail to checkroles,reason : %s


400 BMS.0034

BMSs cannot beprovisionedautomatically.

-- This operation is notsupported.


Issue 01 (2018-07-15) 115

HTTPStatusCode

ReturnedValue


400 BMS.0047

The system diskis too small.

root volume isillegal,reason : %s

Specify a system disk witha larger capacity.

400 BMS.0049

Failed to querykey_name.

query keypairfail,reason is : %s


400 BMS.0102

This image doesnot supportvolumeattaching.

The image not supportattach volume

Contact technical support.

400 BMS.0103

The volumedoes not exist.

attach volume %s fail,volume info is null

Check whether the volumeinformation is correct.

400 BMS.0104

The data volumecannot beattached to themount point ofthe systemvolume.

attach volume %s fail,data volume can notattach in root volumedevice

Select another mountpoint.

400 BMS.0105

The mount pointis invalid.

attach volume %s fail,device is illegal

Check whether the mountpoint is valid.

400 BMS.0106

The AZ towhich the datavolume belongsis inconsistentwith that towhich the BMSbelongs.

attach volume %s fail,volume's az is not equalwith server's az

Ensure that the AZ towhich the data volumebelongs is consistent withthat to which the BMSbelongs.

400 BMS.0108

The system diskdoes not matchthe BMS.

attach volume %s fail,root volume is notmatch with vm, do notchange image

Check the system disk andthen attach it to the BMSagain.

400 BMS.1001

This operationcan beperformed onlywhen the BMSis in running orstopped state.

volume can only beattached when sever %sstopped or active

Try again later or contactcustomer service.


Issue 01 (2018-07-15) 116

HTTPStatusCode

ReturnedValue


400 BMS.1002

The number ofdata volumesthat can beattached to theBMS exceedsthe quota.

attach volume fail,server %s attchmentnum over limit


400 BMS.1003

The volumestatus is invalid.

attach shareable volume%s fail, volume status is%s, not available orinuse

Check whether the volumeis in attached or otherunavailable status.

400 BMS.1004

The number ofshared datavolumes that canbe attached tothe BMSexceeds thequota.



400 BMS.1006

The runningstatus of theBMS cannot beobtained.

server %s info is null orits status or its metadatais null


400 BMS.1007

Failed to obtaininformationabout the datavolume.

post query volume %sfail, the error is:%s


400 BMS.1008

The volume typedoes not matchthe BMS.

the server[%s] is nothana server,volume[%s] is notmatch with server

Check whether the volumetype matches the BMS orcontact the technicalsupport.

400 BMS.1009

The data volumehas beenattached to theBMS.

attach shareable volume%s fail, volume status is%s, the volume hasbeen attached to theserver

Select another datavolume.

400 BMS.1011

The data volumeis beingattached.


Do not repeatedly attachthe data volume.


Issue 01 (2018-07-15) 117

HTTPStatusCode

ReturnedValue


400 BMS.3001

Failed to querythe securitygroup or subnet.

query security groupfailed: %s.orquery vpcId for subnetfailed: %s.

See the returned errormessage or contacttechnical support.

400 BMS.3011

- - See the returned errormessage or contacttechnical support.

400 BMS.3025

The EVS disktype is incorrect.

Not support createshareable data volumes.


400 BMS.3035

No volumematches theBMS.

attach volume fail: thebmsid [%s] in volumemetadata is not thesame with bmsid [%s]in url

Ensure that the volumematches the BMS orcontact technical support.

400 BMS.3039

Failed to verifypasswordcomplexity.

The Password isillegal ,reason : %s

See the password rules.

400 BMS.3040

Failed to querythe VPC.

The vpcId[%s] isinvalid or not-existing


400 BMS.0201

Parameters forcreating a BMSare incorrect.

Fail to check thebaremetal serverparams, reason:%s


400 BMS.0202

The data disktype is invalid.

All volumes must be insame type.


400 BMS.0203

Invalid diskparameters.

volume is illegal, %s See the returned errormessage or contacttechnical support.

400 BMS.0204

The number ofdata disksexceeds theupper limit.

the num of datavolumeis illegal,the num is %d,max num allow is %d


400 BMS.0205

Invalid BMSquantity.

The number ofbaremetal server is outof range for one quest

Change the number ofBMSs.


Issue 01 (2018-07-15) 118

HTTPStatusCode

ReturnedValue


400 BMS.0206

Invalid name. The length of baremetalserver name[%s] is %s

Change the name asrequired.

400 BMS.0207

IP addressescannot bespecified duringbatch BMScreation.

vpc is illegal , reason:%s


400 BMS.0208

Failed to querythe AZ.

Fail to get RegionInfoby tenant [%s], reason:%s


400 BMS.0210

The length ofthe injected dataexceeds theupper limit.

the size of userdata[%d] is over quotalimits [%d]

Modify the injected data.

400 BMS.0211

Invalid key. The image platfrom is[%s], supportpublicKey, resion: thepublicKey is illegal,null is Not allowed

Select a valid key.

400 BMS.0114

The disk to bedetached is notin the BMS disklist.

volume %s is not inserver %s attach volumelist

Check whether the diskexists.

400 BMS.0212

The system isoverloaded.

System is overloaded,please try again later.

Please try later.

400 BMS.0213


OBTAZ role verify fail:not allowed role.


400 BMS.0214

Failed to querythe NIC.

query subnet[%s]failed: response is null.


400 BMS.0215

Failed to createthe order.

- See the returned errormessage or contacttechnical support.

400 BMS.0216

Failed to submitthe order.

Submit order[%s]failed: %s



Issue 01 (2018-07-15) 119

HTTPStatusCode

ReturnedValue


400 BMS.0217

Failed to verifymetadata.

Create serverfail,reason :metaData isillegal.


400 BMS.0223

Currently, onlySCSI disks aresupported.

Only SCSI disks aresupported.

Select the SCSI disk type.


Issue 01 (2018-07-15) 120

A Appendix

A.1 Network API DescriptionFor details about network service APIs, see Virtual Private Cloud API Reference.

A.2 DSS API DescriptionFor details about DSS APIs, see Dedicated Storage Service API Reference.

Bare Metal ServerAPI Reference A Appendix

Issue 01 (2018-07-15) 121

B Change History

What's New Release Date

This issue is the first official release. 2018-07-15

Bare Metal ServerAPI Reference B Change History

Issue 01 (2018-07-15) 122

Documents

API Reference€¦ · 3.5.2 Querying BMSs (Native OpenStack API).....68 3.5.3 Querying Details About BMSs (Native OpenStack API ... 101 3.11.4 Deleting an SSH Key Pair (Native OpenStack