api development guide · 2019. 7. 18. · elastic volume service api development guide issue 01...

Elastic Volume Service

API Development Guide

Issue 01

Date 2018-06-30

HUAWEI TECHNOLOGIES CO., LTD.

Copyright © Huawei Technologies Co., Ltd. 2018. All rights reserved.No part of this document may be reproduced or transmitted in any form or by any means without prior writtenconsent of Huawei Technologies Co., Ltd. Trademarks and Permissions

and other Huawei trademarks are trademarks of Huawei Technologies Co., Ltd.All other trademarks and trade names mentioned in this document are the property of their respectiveholders. NoticeThe purchased products, services and features are stipulated by the contract made between Huawei and thecustomer. All or part of the products, services and features described in this document may not be within thepurchase scope or the usage scope. Unless otherwise specified in the contract, all statements, information,and recommendations in this document are provided "AS IS" without warranties, guarantees orrepresentations of any kind, either express or implied.

The information in this document is subject to change without notice. Every effort has been made in thepreparation of this document to ensure accuracy of the contents, but all statements, information, andrecommendations in this document do not constitute a warranty of any kind, express or implied.

Huawei Technologies Co., Ltd.Address: Huawei Industrial Base

Bantian, LonggangShenzhen 518129People's Republic of China

Website: http://www.huawei.com

Email: [email protected]

Issue 01 (2018-06-30) Huawei Proprietary and ConfidentialCopyright © Huawei Technologies Co., Ltd.

i

http://www.huawei.commailto:[email protected]

Contents

1 Overview......................................................................................................................................... 1

2 Request Creation........................................................................................................................... 32.1 API Calling Process........................................................................................................................................................32.2 Obtaining Request Authentication Information............................................................................................................. 42.3 Constructing a Request...................................................................................................................................................42.4 Initiating a Request.........................................................................................................................................................72.5 Parsing a Response......................................................................................................................................................... 7

3 Disk Encryption............................................................................................................................. 93.1 Principle..........................................................................................................................................................................93.2 Creating Encrypted EVS Disks...................................................................................................................................... 9

4 Disk Sharing.................................................................................................................................114.1 Principle........................................................................................................................................................................ 114.2 Using Shared EVS Disks.............................................................................................................................................. 11

5 Snapshot........................................................................................................................................ 135.1 Principle........................................................................................................................................................................135.2 Using EVS Snapshots...................................................................................................................................................14

6 FAQ................................................................................................................................................ 156.1 How Can I Use the EVS Disk Metadata?.....................................................................................................................15

A Change History........................................................................................................................... 16

Elastic Volume ServiceAPI Development Guide Contents


ii

1 OverviewWhat Is Elastic Volume Service?

The Elastic Volume Service (EVS) offers scalable block storage for servers. With highreliability, high performance, and rich specifications, EVS disks can be used for distributedfile systems, development and test environments, data warehouse applications, and high-performance computing (HPC) scenarios to meet diverse service requirements. These serverscan be Elastic Cloud Servers (ECSs) or Bare Metal Servers (BMSs).

EVS disks are also referred to as disks in this document.

EVS Development MethodRESTful APIs provided by EVS can be classified into open-source APIs and extension APIs.l Open-source APIs: These APIs are inherited from the OpenStack Mitaka release. To

resolve public cloud authentication issues and differentiate clusters, these open-sourceAPIs are added with specific header fields, such as X-Auth-Token, X-Sdk-Date,Authorization, and X-Project-Id in the EVS request header. For details, see the ElasticVolume Service API Reference.

l Extension APIs: These APIs are implemented based on open-source APIs and also havethe public cloud authentication and cluster differentiation capabilities.

This document describes the RESTful API development method.

EVS Basic Featuresl Disk encryption

EVS disk encryption allows you to encrypt the disk data using keys provided by the KeyManagement Service (KMS) of Data Encryption Workshop (DEW), which is secure andconvenient. Therefore, you do not need to build and maintain the key managementinfrastructure.

l Disk sharingShared EVS disks are block storage devices that support concurrent read/writeoperations and can be attached to multiple servers. Shared EVS disks feature multiplemount points, high concurrency, high performance, and high reliability. A shared EVSdisk can be attached to a maximum of 16 servers.Currently, shared EVS disks can be used as data disks only and cannot be used as systemdisks.

Elastic Volume ServiceAPI Development Guide 1 Overview


1

l SnapshotAn EVS snapshot is a complete copy or image of the disk data at a specific time point.As a major disaster recovery (DR) approach, you can use a snapshot to completelyrestore the data to the time point when the snapshot was created.

Elastic Volume ServiceAPI Development Guide 1 Overview


2

2 Request Creation2.1 API Calling Process2.2 Obtaining Request Authentication Information2.3 Constructing a Request2.4 Initiating a Request2.5 Parsing a Response

2.1 API Calling ProcessFigure 2-1 API calling process

Elastic Volume ServiceAPI Development Guide 2 Request Creation


3

The process for calling an EVS API is as follows:

1. Before you make an API call, obtain request authentication information, and fill it in therequest header. For details, see 2.2 Obtaining Request Authentication Information.

2. Configure request parameters to construct a request. For details, see 2.3 Constructing aRequest.

3. Initiate a request based on the constructed request. For details, see 2.4 Initiating aRequest.

4. The parsing server returns an HTTP response after receiving the request. For details, see2.5 Parsing a Response.

2.2 Obtaining Request Authentication InformationYou can use either of the following authentication methods to call the API:

l Token authentication: Requests are authenticated using tokens. Token authentication isrecommended for open-source APIs.For details about token authentication, see section "Token Authentication" in the ElasticVolume Service API Reference.

l AK/SK authentication: Requests are encrypted using the access key ID (AK) and secretaccess key (SK). AK/SK authentication is recommended for extension APIs, which ismore secure than token authentication.For details about AK/SK authentication, see section "AK/SK Authentication" in theElastic Volume Service API Reference.

2.3 Constructing a RequestA request usually contains the request line, request header, and request body.

NOTE

The request body is optional.

Request Line

A request line begins with a method token, followed by a request URI and protocol version.The three parts are separated by spaces. The format of the request line is as follows:

Method Request-URI HTTP-Version CRLFl Method: indicates the request method. All methods are capitalized and are explained as

follows:– GET: requests the resource identified by Request-URI.– POST: adds new data to the resource identified by Request-URI.– PUT: requests the server to store the URI of an existing resource to Request-URI.– DELETE: requests the server to delete the resource identified by Request-URI.– PATCH: requests the server to update part of the resource. If no resource is

available, PATCH may create a resource.– HEAD: requests only the head of the page.– OPTION: allows the client to view the server performance.



4

l Request-URI: indicates a uniform resource identifier. Request-URI is in the [path]?[query] format. If there are multiple paths and queries, you can:– Use slashes (/) to separate multiple paths.– Use question marks (?) to separate query and path.– Use ampersands (&) to separate multiple queries.

l HTTP-Version: indicates the HTTP protocol version.l CRLF: a carriage return and line feed (CRLF), indicating to start a new line. Value

CRLF appears at the end, and no CR or LF is allowed.

Request HeaderA request header consists of several header fields. Each header field consists of a field name,a colon (:), and a field value.

Table 2-1 describes common request header fields of EVS. Except for Content-Type andContent-Length, other fields are unique to EVS.

Table 2-1 Common request header fields

Name Description Mandatory Example Value

x-sdk-date Time when the requestis sent. The time is intheYYYYMMDD'T'HHMMSS'Z' format.The value is the currentCoordinated UniversalTime (UTC) time of thesystem.

NoThis field ismandatory forAK/SKauthentication.

20150907T101459Z

Authorization Signature authenticationinformation.For details, see section"Request SigningProcedure" in the ElasticVolume Service APIReference.


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



5

Name Description Mandatory Example Value

Host Requested serverinformation, which canbe obtained from theURL of the service API.The value is in thehostname[:port] format.If the port number is notspecified, the defaultport is used. The defaultport for HTTPS is port443.


code.test.comorcode.test.com:443

Content-Type MIME type of the sentrequest body. You areadvised to use thedefault valueapplication/json. For anobject or image uploadAPI, the value variesdepending on the flowtype.

Yes application/json

Content-Length Length of the requestbody. The unit is byte.

No 3495

X-Project-Id Project ID.For details about how toobtain the project ID,see section "Obtaining aProject ID" in theIdentity and AccessManagement APIReference.This field is mandatoryfor a request from aDedicated Cloud (DeC)or multi-project user.

NoThis field ismandatory forrequests that useAK/SKauthentication in theDeC or multi-project scenario.

e9993fc787d94b6c886cbaa340f9c0f4

X-Auth-Token User token.For details about how toobtain the token, seesection "Obtaining aUser Token" in theIdentity and AccessManagement APIReference. After therequest is processed, thevalue of X-Subject-Token in the responseheader is the tokenvalue.

NoThis field ismandatory for tokenauthentication.

MIIPAgYJKoZIhvc-NAQcCoIIO8zCCDu8CAQExDTALBglghkgBZQMEAgEwgg1QBgkqhkiG9w0BBwGggg1BBIINPXsidG9rZNOTE

This value is only partof a sample token.



6

Request Body

The request body is encapsulated in the JSON format and presented in nested key:valueformat. Mandatory fields and optional fields in an HTTP request vary with URI objects. Fordetails, see the Elastic Volume Service API Reference.

2.4 Initiating a RequestYou can initiate a request based on the constructed request message in one of the followingways:

l cURLcURL is a command-line tool used to perform URL operations and transmit information.It serves as an HTTP client that can send HTTP requests to the server and receiveresponse messages. cURL is applicable to API debugging. For more information aboutcURL, visit https://curl.haxx.se/.

l CodingYou can call the APIs through code to assemble, send, and process requests.

l REST clientBoth Mozilla Firefox and Google Chrome provide a graphical browser plug-in, that is,REST client, to send and process requests.– For Mozilla Firefox, see Firefox REST Client.– For Google Chrome, see Postman Interceptor.

2.5 Parsing a ResponseAfter receiving a request, the server returns an HTTP response.

A response consists of a status line, a response header, and a response body.

Status Line

The status line format is as follows:

HTTP-Version Status-Code Reason-Phrase CRLFl HTTP-Version: indicates the version of the HTTP protocol used by the server.l Status-Code: indicates the status code in the response.

The status code consists of three digits. The first digit defines the response category andcan be any of the following five values:– 1xx: Informational - Request received, continuing process– 2xx: Success - The action was successfully received, understood, and accepted– 3xx: Redirection - Further action must be taken in order to complete the request– 4xx: Client Error - The request contains bad syntax or cannot be fulfilled– 5xx: Server Error - The server failed to fulfill an apparently valid request

l Reason-Phrase: indicates the textual description of the status code.



7

https://curl.haxx.se/https://addons.mozilla.org/en-US/firefox/addon/restclient/https://chrome.google.com/webstore/detail/postman-interceptor/aicmkgpgakddgnaphhhpliifpcfhicfo/

Response HeaderA response header usually contains the header fields described in Table 2-2.

Table 2-2 Response header fields

Name Description Example Value

Date Standard HTTP header field, whichrepresents the date and time at which themessage was originated. The format isdefined by RFC 822.

Mon, 12 Nov 200715:55:01 GMT

Server Standard HTTP header field, whichincludes information about the softwarethat the server uses to process the request.

Apache

Content-Length Standard HTTP header field, whichspecifies the size of the entity body, indecimal number of bytes, sent to therecipient.

xxx

Content-Type Standard HTTP header field, whichspecifies the media type of the entity bodysent to the recipient.

application/json

Response BodyThe response body is in JSON format and presented in UTF-8 code format.



8

3 Disk EncryptionIntroduction

Data security has always been the top priority of enterprise information security. In the past,enterprises store the encrypted data on their own servers. With the popularity of cloudcomputing across industries, more enterprises choose to host their services on the cloud.Therefore, the encryption of their disk data on the cloud is becoming particularly important.

To address this need, EVS adds support for disk encryption. EVS uses a universal secureencryption algorithm to encrypt data on user disks, without any application awareness. Thekeys used to encrypt disks are managed by users, which ensures data security and privacy.

Application Scenarios

Many enterprises have an urgent need for EVS disk encryption, such as:

l Financial institutions, who manage a large number of accounts, and the account securityis of great importance.

l Internet enterprises, who manage a massive amount of user data, and the data security isvital for them.

3.1 Principle

3.2 Creating Encrypted EVS Disks

3.1 PrincipleEVS uses the AES-256 encryption algorithm and uses the keys provided by the KMS of DEWto encrypt the disk data.

3.2 Creating Encrypted EVS Disks

Precautionsl The security administrator (user having the Security Administrator rights) can grant the

KMS access rights to EVS for using disk encryption.

Elastic Volume ServiceAPI Development Guide 3 Disk Encryption


9

l When a common user who does not have the Security Administrator rights needs to usethe disk encryption feature, the condition varies depending on whether the user is thefirst one ever in the current region or project to use this feature.– If the common user is the first one ever in the current region or project to use the

feature, the user must contact a user having the Security Administrator rights togrant the KMS access rights to EVS. Then, the common user can use the diskencryption feature.

– If the common user is not the first one ever in the current region or project to usethe feature, the common user can use the disk encryption function directly.

l From the perspective of a tenant, as long as the KMS access rights have been granted toEVS in a region, all users in the same region can directly use the disk encryption feature.If there are multiple projects in the current region, the KMS access rights need to begranted to each project in this region.

Usage Instructions

Step 1 Obtain a key ID.l For API users: Obtain a key ID by calling the API used to query the key list. For details,

see CMK Management > Querying the List of CMKs in the Data EncryptionWorkshop API Reference.

l For console users: Log in to the management console and switch to the EVS console. Onthe Buy Disk page, select Enable for Disk Encryption and select a key for KMS KeyName. The KMS key ID is also displayed on the console. For details, see section"Purchasing an EVS Disk" in the Elastic Volume Service User Guide.

Step 2 Create an encrypted disk.l For API users: Create an encrypted disk by calling the API used to create disks. For

details, see section "Creating an EVS Disk" in the Elastic Volume Service API Reference.l For console users: On the Buy Disk page, set the parameters and click Next. For details,

see section "Purchasing an EVS Disk" in the Elastic Volume Service User Guide.

----End

Elastic Volume ServiceAPI Development Guide 3 Disk Encryption


10

4 Disk SharingIntroduction

Disk sharing allows you to attach an EVS disk to multiple servers for use. EVS disks with thisfeature enabled are referred to as shared EVS disks. Shared EVS disks feature multiple mountpoints, high performance, high reliability, and wide application scenarios.

Application ScenariosShared EVS disks are mainly used for enterprise key applications that require clusterdeployment and high availability (HA). These applications demand concurrent access to anEVS disk from multiple servers. Example applications include Oracle RAC, Windows WSFC,Linux RHCS, Veritas VCS, and Veritas CFS.

4.1 Principle

4.2 Using Shared EVS Disks

4.1 PrincipleA shared EVS disk is essentially the disk that can be attached to multiple servers for use,which is similar to a physical disk in that the disk can be attached to multiple physical servers,and each server can read data from and write data into any space on the disk.

4.2 Using Shared EVS Disks

Precautionsl Currently, shared EVS disks can be used as data disks only and cannot be used as system

disks.l Each server to which the shared EVS disk has been attached can read data from and

write data into any space on this disk. If data read/write rules, such as the read/writesequence and meaning, between these servers are not defined, data read/writeinterference between servers or other unpredictable errors may occur.

l Though shared EVS disks are block storage devices that provide shared access forservers, shared EVS disks do not have the cluster management capability. Therefore, youneed to deploy a cluster system to manage shared EVS disks. Common cluster

Elastic Volume ServiceAPI Development Guide 4 Disk Sharing


11

management systems include Oracle RAC, Windows WSFC, Linux RHCS, Veritas VCS,and Veritas CFS.

Usage Instructions

Step 1 Create a shared EVS disk.l For API users: Create a shared EVS disk by calling the API used to create disks. For

details, see section "Creating an EVS Disk" in the Elastic Volume Service API Reference.l For console users: On the Buy Disk page, select Enable for Disk Sharing and click

Next. For details, see section "Purchasing an EVS Disk" in the Elastic Volume ServiceUser Guide.

Step 2 Attach the shared EVS disk.l For API users: Attach the shared EVS disk by calling the ECS API used to attach disks.

For details, see Disk Management > Attaching a Disk in the Elastic Cloud Server APIReference.

l For console users: Log in to the management console and choose Storage > ElasticVolume Service > Disk. In the disk list, locate the shared disk and click Attach in theOperation column to attach the disk to servers. For details, see section "Attaching aShared EVS Disk" in the Elastic Volume Service User Guide.

----End

Elastic Volume ServiceAPI Development Guide 4 Disk Sharing


12

5 SnapshotIntroduction

An EVS snapshot is a complete copy or image of the disk data at a specific time point. As amajor disaster recovery approach, you can use a snapshot to completely restore the data to thetime point when the snapshot was created.

Application ScenariosThe snapshot feature helps address your following needs:

l Routine data backup

You can create snapshots for disks on a timely basis and use snapshots as backups to recoveryour data in case that data loss or data inconsistency occurred due to misoperations, viruses,or attacks.

l Rapid data restoration

You can create a snapshot or multiple snapshots before an OS change, application softwareupgrade, or a service data migration. If an exception occurs during the upgrade or migration,service data can be rapidly restored to the time point when the snapshot was created.

l Multi-service quick deployment

You can use a snapshot to create multiple disks containing the same initial data, and thesedisks can be used as data resources for various services, for example data mining, reportquery, and development and testing. This method protects the initial data and creates disksrapidly, meeting the diversified service data requirements.

5.1 Principle

5.2 Using EVS Snapshots

5.1 PrincipleHUAWEI CLOUD uses the Redirect-On-Write (ROW) mechanism to store snapshot data,which does not deteriorate performance of the source disk and achieves second-level recoveryof the disk data.

The snapshot metadata is stored in a distributed manner, allowing horizontal expansion andeliminating bottlenecks that may occur in a centrally-deployed system.

Elastic Volume ServiceAPI Development Guide 5 Snapshot


13

5.2 Using EVS Snapshots

Usage Instructions

Step 1 Create an EVS snapshot.l For API users: Create an EVS snapshot by calling the API used to create snapshots. For

details, see section "Creating an EVS Snapshot" in the Elastic Volume Service APIReference.

l For console users: Log in to the management console and choose Storage > ElasticVolume Service > Disk. In the disk list, locate the target disk, click More in theOperation column, and choose Create Snapshot. For details, see section "Creating aSnapshot" in the Elastic Volume Service User Guide.

Step 2 Create an EVS disk from the snapshot.l For API users: Create an EVS disk from the snapshot by calling the API used to create

disks. For details, see section "Creating an EVS Disk" in the Elastic Volume Service APIReference.

l For console users: Log in to the EVS console and click Buy Disk. On the displayedpage, select Create from snapshot for Source and click Next. For details, see section"Purchasing an EVS Disk" in the Elastic Volume Service User Guide.

Step 3 Roll back the snapshot to a disk.l For API users: Roll back the snapshot to a disk by calling the API used to roll back

snapshots. For details, see section "Rolling Back a Snapshot to an EVS Disk" in theElastic Volume Service API Reference.

l For console users: Log in to the management console and choose Storage > ElasticVolume Service > Snapshot. In the snapshot list, locate the target snapshot and clickRoll Back Disk in the Operation column. For details, see section "Rolling Back Datafrom a Snapshot" in Elastic Volume Server User Guide.

----End

Elastic Volume ServiceAPI Development Guide 5 Snapshot


14

6 FAQ6.1 How Can I Use the EVS Disk Metadata?

6.1 How Can I Use the EVS Disk Metadata?

OverviewEVS disk metadata consists of key-value pairs. You can customize keys and values based onyour service requirements.

Involved APIsl Adding metadata of an EVS diskl Querying metadata of an EVS diskl Updating metadata of an EVS diskl Querying one piece of metadata for an EVS diskl Updating one piece of metadata for an EVS diskl Deleting one piece of metadata for an EVS disk

NOTE

For more information about APIs, see the Elastic Volume Service API Reference.

Elastic Volume ServiceAPI Development Guide 6 FAQ


15

A Change HistoryIssue Release Date What's New

01 2018-06-30 This issue is the first official release.

Elastic Volume ServiceAPI Development Guide A Change History


16

Contents1 Overview2 Request Creation2.1 API Calling Process2.2 Obtaining Request Authentication Information2.3 Constructing a Request2.4 Initiating a Request2.5 Parsing a Response

3 Disk Encryption3.1 Principle3.2 Creating Encrypted EVS Disks

4 Disk Sharing4.1 Principle4.2 Using Shared EVS Disks

5 Snapshot5.1 Principle5.2 Using EVS Snapshots

6 FAQ6.1 How Can I Use the EVS Disk Metadata?

A Change History

api development guide · 2019. 7. 18. · elastic volume service api development guide issue 01...

Documents