IBM Cloud Manager with OpenStack: REST API Reference, version 4.2

216 Pages·2014·0.57 MB·English

(cid:1)(cid:2)(cid:3)
IBM Cloud Manager with OpenStack
REST API Reference, version 4.2

(cid:1)(cid:2)(cid:3)
IBM Cloud Manager with OpenStack
REST API Reference, version 4.2
Note
Before using this information and the product it supports, read the information in “Notices” on
page 205.
SeventhEdition(December2014)
©CopyrightIBMCorporation2011,2014.
USGovernmentUsersRestrictedRights–Use,duplicationordisclosurerestrictedbyGSAADPScheduleContract
withIBMCorp.
Contents
Chapter 1. IBM Cloud Manager with PUT/configuration/ldap.xml . . . . . . . 35
OpenStack REST API reference . . . . 1 GET/configuration/ldapCert . . . . . . . 36
PUT/configuration/ldapCert . . . . . . . 37
OverviewofIBMCloudManagerwithOpenStack
Cloudmanagementservices. . . . . . . . . 37
RESTwebservices . . . . . . . . . . . . 1
GET/clouds/certificate . . . . . . . . . 37
WebservicesprovidedbyIBMCloudManager
POST/clouds . . . . . . . . . . . . 38
withOpenStack . . . . . . . . . . . . 1
DELETE/clouds/{id} . . . . . . . . . . 40
ConnectingtoanIBMCloudManagerwith
GET/clouds . . . . . . . . . . . . . 40
OpenStackserver. . . . . . . . . . . . 2
GET/clouds/{id} . . . . . . . . . . . 41
IBMCloudManagerwithOpenStackRESTAPI
GET/clouds?types. . . . . . . . . . . 42
responsecodes. . . . . . . . . . . . . 3
GET/clouds/{id}/certificate . . . . . . . 42
Appliancelibraryservices . . . . . . . . . . 3
PUT/clouds/{id} . . . . . . . . . . . 43
GET/appliances . . . . . . . . . . . . 3
Delinquencypoliciesservices . . . . . . . . 44
GET/appliances/{id} . . . . . . . . . . 5
GET/billing/delinquencyPolicies . . . . . . 44
PUT/appliances/{id} . . . . . . . . . . 6
GET/billing/delinquencyPolicies/{id} . . . . 44
DELETE/appliances/{id} . . . . . . . . . 6
Eventservices . . . . . . . . . . . . . 45
GET/appliances/{id}/copies. . . . . . . . 7
DELETE/events . . . . . . . . . . . 45
GET/appliances/{id}/targets. . . . . . . . 7
GET/events . . . . . . . . . . . . . 45
GET/appliances/{id}/customization . . . . . 8
GET/events/eventcsv. . . . . . . . . . 48
PUT/appliances/{id}/properties . . . . . . 13
GET/events/{id} . . . . . . . . . . . 48
DELETE/appliances/{id}/customization . . . 14
Expirationpolicyservices. . . . . . . . . . 49
GET/appliances/{id}/log . . . . . . . . 14
GET/expirationPolicies . . . . . . . . . 49
POST/appliances . . . . . . . . . . . 15
PUT/expirationPolicy. . . . . . . . . . 50
GET/targets . . . . . . . . . . . . . 15
GET/expirationPolicy/{id} . . . . . . . . 51
GET/targets/{TargetId}/virtualServers . . . . 17
PUT/expirationPolicy/{id} . . . . . . . . 51
Authenticationservices . . . . . . . . . . 17
GET/projects/{id}/expirationPolicy . . . . . 52
POST/auth . . . . . . . . . . . . . 17
Keypairservices . . . . . . . . . . . . 53
GET/auth/reminder . . . . . . . . . . 18
GET/keypairs . . . . . . . . . . . . 53
POST/auth/registration . . . . . . . . . 19
GET/keypairs/{id}. . . . . . . . . . . 54
GET/auth/reminder/isEnabled . . . . . . 19
POST/keypairs. . . . . . . . . . . . 54
Billingservices . . . . . . . . . . . . . 20
Licensekeyservices . . . . . . . . . . . 56
GET/accounts . . . . . . . . . . . . 20
GET/licensing . . . . . . . . . . . . 56
POST/accounts. . . . . . . . . . . . 21
PUT/licensing . . . . . . . . . . . . 57
GET/accounts/{id} . . . . . . . . . . 21
Meteringdataservices. . . . . . . . . . . 57
PUT/accounts/{id} . . . . . . . . . . 22
GET/udrfiles . . . . . . . . . . . . 57
DELETE/accounts/{id} . . . . . . . . . 22
GET/udrfiles/{directoryName} . . . . . . 57
GET/accounts/users . . . . . . . . . . 23
GET/udrfiles/{directoryName}/{fileName} . . 58
GET/accounts/{id}/users . . . . . . . . 24
GET/udrs . . . . . . . . . . . . . 58
GET/accounts/{id}/users/{id}. . . . . . . 24
GET/udrs/{id} . . . . . . . . . . . . 60
POST/accounts/{id}/users . . . . . . . . 25
Networkconfigurationservices. . . . . . . . 61
DELETE/accounts/{id}/users/{id} . . . . . 26
GET/networkConfigurations . . . . . . . 61
GET/accounts/{id}/bills. . . . . . . . . 27
POST/networkConfigurations . . . . . . . 65
GET/accounts/{id}/bills/{id} . . . . . . . 27
GET/networkConfigurations/{id}. . . . . . 68
GET/accounts/{id}/charges . . . . . . . 28
PUT/networkConfigurations/{id}. . . . . . 69
GET/accounts/{id}/credits . . . . . . . . 29
DELETE/networkConfigurations/{id} . . . . 70
POST/accounts/{id}/credits . . . . . . . 29
GET/networkConfigurations/{id}/ipAddresses 71
Billingcloudproductservices . . . . . . . . 30
POST/networkConfigurations/{id}/ipAddresses 72
GET/billing/cloudProducts. . . . . . . . 30
GET/networkConfigurations/{id}/ipAddresses/
GET/billing/cloudProducts/{prodId} . . . . 31
{ip} . . . . . . . . . . . . . . . . 74
Billingpaymentauthorizerservices . . . . . . 32
PUT/networkConfigurations/{id}/ipAddresses/
GET/billing/paymentAuthorizers . . . . . 32
{ip} . . . . . . . . . . . . . . . . 74
GET/billing/paymentAuthorizers/{id} . . . . 32
DELETE/networkConfigurations/{id}/
Configurationservices. . . . . . . . . . . 33
ipAddresses/{ip} . . . . . . . . . . . 75
GET/configuration/properties. . . . . . . 33
GET/networks/{cloudid}/floatingips . . . . 75
GET/configuration/ipAddressPools . . . . . 34
GET/networks/{cloudid}/floatingips/{serverid} 76
GET/configuration/ldap.xml . . . . . . . 34
©CopyrightIBMCorp.2011,2014 iii
PUT/networks/{cloudid}/floatingips/{floating GET/virtualServers/{id}/log . . . . . . . 119
ipid} . . . . . . . . . . . . . . . 77 GET/virtualServers/{id}/storages . . . . . 120
Productinformationservices . . . . . . . . 78 GET/virtualServers/{id}/storages/{id} . . . 120
GET/productInfo/version . . . . . . . . 78 POST/virtualServers/{id}/storages. . . . . 121
GET/productInfo/shortName . . . . . . . 78 DELETE/virtualServers/{id}/storages/{id} . . 122
GET/productInfo/name. . . . . . . . . 78 GET/virtualServers/{id}/networks . . . . . 123
GET/productInfo/fullName . . . . . . . 79 GET/virtualServers/{id}/networks/{id} . . . 125
GET/productInfo/vendorName . . . . . . 79 GET/virtualServers/{id}/backups . . . . . 127
GET/productInfo/vendorIcon. . . . . . . 80 GET/virtualServers/{id}/backups/{id} . . . 127
GET/productInfo/splash . . . . . . . . 80 POST/virtualServers/{id}/backups. . . . . 128
GET/productInfo/icon{type} . . . . . . . 80 PUT/virtualServers/{id}/backups/{id} . . . 128
Projectmanagementservices . . . . . . . . 81 DELETE/virtualServers/{id}/backups/{id} . . 129
GET/projects . . . . . . . . . . . . 81 GET/virtualServers/{id}/repositories . . . . 129
POST/projects . . . . . . . . . . . . 82 GET/virtualServers/{id}/repositories/{id}/
DELETE/projects/{id} . . . . . . . . . 83 customization . . . . . . . . . . . . 130
PUT/projects/{id} . . . . . . . . . . . 83 Workloadservices. . . . . . . . . . . . 130
GET/projects/{id} . . . . . . . . . . . 84 GET/multiWorkloads/{id}. . . . . . . . 130
GET/projects/{id}/workloads . . . . . . . 84 GET/workloads . . . . . . . . . . . 132
GET/projects/{id}/appliances . . . . . . . 86 POST/workloads. . . . . . . . . . . 133
GET/projects/{id}/users. . . . . . . . . 87 GET/workloads/{id} . . . . . . . . . 138
GET/projects/{id}/expirationPolicy . . . . . 87 GET/workloads/{id}/customization . . . . 139
POST/projects/{id}/users . . . . . . . . 88 GET/workloads/{id}/target . . . . . . . 152
PUT/projects/{id}/users/{username} . . . . 89 GET/workloads/{id}/log . . . . . . . . 153
DELETE/projects/{id}/users/{username} . . . 89 GET/workloads/{id}/virtualServers . . . . 153
Requestlifecycleservices. . . . . . . . . . 90 GET/workloads/{id}/virtualServers/{id}. . . 155
GET/requests . . . . . . . . . . . . 90 GET/workloads/{id}/virtualServers/{id}/
PUT/requests . . . . . . . . . . . . 91 credentials . . . . . . . . . . . . . 157
GET/requests/{id}. . . . . . . . . . . 92 PUT/workloads/{id}/virtualServers/{id}/
PUT/requests/{id}. . . . . . . . . . . 92 credentials . . . . . . . . . . . . . 157
GET/requests/{id}/parameters . . . . . . 93 GET/workloads/{id}/timestamps . . . . . 158
PUT/requests/{id}/parameters . . . . . . 94 PUT/workloads/{id} . . . . . . . . . 159
GET/requests/{id}/comments. . . . . . . 94 DELETE/workloads/{id} . . . . . . . . 163
POST/requests/{id}/comments . . . . . . 95 GET/workloads/stats . . . . . . . . . 164
GET/requests/handlers . . . . . . . . . 95 GET/workloads/owners . . . . . . . . 164
PUT/requests/handlers . . . . . . . . . 98
GET/requests/requestcsv . . . . . . . . 98 Chapter 2. IBM OpenStack REST API
DELETE/requests/requstcsv . . . . . . . 99 reference . . . . . . . . . . . . . 167
Statisticsresourceservices . . . . . . . . . 100
OverviewofIBMOpenStackRESTAPIreference 167
GET/stats/free . . . . . . . . . . . 100
AccessOpenStackAPIs . . . . . . . . . . 167
GET/stats/totals . . . . . . . . . . . 102
OpenStackRESTAPIs . . . . . . . . . . 168
GET/stats/usage. . . . . . . . . . . 103
Keystone. . . . . . . . . . . . . . 169
Userservices . . . . . . . . . . . . . 105
Glance. . . . . . . . . . . . . . . 173
GET/users . . . . . . . . . . . . . 105
Neutron . . . . . . . . . . . . . . 174
GET/users/{username}. . . . . . . . . 106
Cinder. . . . . . . . . . . . . . . 180
POST/users . . . . . . . . . . . . 107
Nova . . . . . . . . . . . . . . . 182
PUT/users/{username}. . . . . . . . . 108
DELETE/users/{username} . . . . . . . 109
Related information. . . . . . . . . 201
Virtualserverservices . . . . . . . . . . 109
GET/workloads/{id}/virtualServers . . . . 109
Accessibility. . . . . . . . . . . . 203
GET/workloads/{id}/virtualServers/{id} . . . 111
GET/workloads/{id}/virtualServers/{id}/
credentials . . . . . . . . . . . . . 113 Notices . . . . . . . . . . . . . . 205
PUT/workloads/{id}/virtualServers/{id}/ Trademarks . . . . . . . . . . . . . . 207
credentials . . . . . . . . . . . . . 113 Privacypolicyconsiderations . . . . . . . . 207
GET/virtualServers . . . . . . . . . . 114 Codelicenseanddisclaimerinformation . . . . 208
GET/virtualServers/{id} . . . . . . . . 115
PUT/virtualServers/{id} . . . . . . . . 118
iv IBMCloudManagerwithOpenStack: RESTAPIReference,version4.2
Chapter 1. IBM Cloud Manager with OpenStack REST API
reference
IBM® Cloud Manager with OpenStack version 4.2 provides a self-service portal for the cloud user that
complements VMware vSphere, and Hyper-V through OpenStack. IBM Cloud Manager with OpenStack
also supports Linux Kernel-based Virtual Machine (KVM) and PowerVC through OpenStack. IBM Cloud
Manager with OpenStack is implemented as a lightweight web-based application that runs as an Open
Services Gateway initiative (OSGi) application. IBM Cloud Manager with OpenStack provides an
environment that enables cloud users serve themselves while they maintain control over the allocation of
resources.
The self-service capabilities of IBM Cloud Manager with OpenStack simplify the process to carry out
many common public or private cloud operations such as the following operations:
v Provisioning (deploying) and de-provisioning servers
v Drafting and cloning workloads
v Taking workloads captures
v Starting and shutting down servers
v Resizing existing servers
v Creating projects to give team-specific access to workloads
v Providing network configurations that set unique network properties to different workloads
v Billing, accounting, and metering support
v Providing request and approval workflow support
v Identifying the current capacity of the resources in a virtualization environment
These and many other features are included in this version of the IBM Cloud Manager with OpenStack.
For more detailed documentation about the IBM Cloud Manager with OpenStack capabilities, see the
IBM Cloud Manager with OpenStack User Guide and the IBM Cloud Manager with OpenStack
Administrator Guide.
Related information:
“Code license and disclaimer information” on page 208
Overview of IBM Cloud Manager with OpenStack REST web services
IBM Cloud Manager with OpenStack provides a set ofAPIs that can be used to access IBM Cloud
Manager with OpenStack data and services from applications that are running outside of the IBM Cloud
Manager with OpenStack framework. TheseAPIs are based on the Representational State Transfer (REST)
architecture and are accessed by using the HTTP or HTTPS protocol.
REST refers to an architecture used to create stateless web services that are typically accessed by using
the HTTP or HTTPS protocol.
The RESTAPIs are implemented with complete compatibility from release to release. This means is that
newer versions of IBM Cloud Manager with OpenStack do not have an impact on the code that uses the
existing RESTAPIs.
Web services provided by IBM Cloud Manager with OpenStack
IBM Cloud Manager with OpenStack provides the web services that are listed here.
v Appliance library services
©CopyrightIBMCorp.2011,2014 1
v Authentication services
v Billing services
v Billing cloud product services
v Billing payment authorizer services
v Cloud management services
v Configuration services
v Delinquency policies services
v Event services
v Expiration policy services
v Key pair services
v Metering data services
v Network configuration services
v Product information services
v Project management services
v Request lifecycle services
v Statistics resource services
v User services
v Virtual server services
v Workload services
Connecting to an IBM Cloud Manager with OpenStack server
IBM Cloud Manager with OpenStack is implemented as a lightweight web-based application that runs as
an OSGi application.
For production environments, IBM recommends that you use secure sockets layer (SSL) HTTPS
communication between the IBM Cloud Manager with OpenStack server and the client that is using the
IBM Cloud Manager with OpenStack RESTAPIs. Using SSLprovides a greater level of security for the
data on the network. For more information about configuring the server to use SSLcommunications, see
the IBM Cloud Manager with OpenStackAdministrator Guide.
AllAPIs, except for the authenticationAPIs, require authentication. The preferred method to provide
credential information is to use the /auth API. Use the /auth API to authenticate your user name and
password and then use an authentication token for otherAPIs. For more information, see “POST /auth”
on page 17API.
To establish a connection to the IBM Cloud Manager with OpenStack server, the format of the URLmust
be:
<communication_scheme>://<SCE_server_host>:<port>/cloud/api/<service>
Where
<communication_scheme>
is the scheme that is used for the communication protocol, such as HTTP or HTTPS.
<SCE_server_host>
is the host (where the IBM Cloud Manager with OpenStack server is running) which is contacted as the
data provider.
<port>
2 IBMCloudManagerwithOpenStack: RESTAPIReference,version4.2
is the remote port that is used for the scheme. The IBM Cloud Manager with OpenStack server currently
uses 18080 for HTTP requests and 18443 for HTTPS requests.
IBM Cloud Manager with OpenStack REST API response codes
Find detailed information about the RESTAPI response codes.
200 OK
The request was fulfilled successfully.
201 Created
Following a POST command, this response indicates that the specified resource was successfully
created. This response includes the URI of the newly created resource in the HTTP Location
header.
202 Accepted
The request is accepted for processing, but the processing is not complete. The request might
eventually be acted upon, or it might be disallowed when processing takes place.
This response code is also used to indicate that a request is accepted, but that the request must be
approved by an administrator. The URI of the request that must be approved is included in the
HTTP Location header of the response. Thus, users can track the status of their request by using
that URI.
400 Bad request
The request has incorrect syntax. For example, the JSON object is not recognized or is not valid
JSON.
401 Unauthorized
The parameter to this message gives a specification of authorization schemes that are acceptable.
Submit the request with a suitableAuthorization header.
404 Not found
The server cannot find the resource that is requested in the URI.
500 Internal Error
The server encountered an unexpected condition that prevented it from fulfilling the request.
For more information, see the Response.Status Javadoc.
Related information:
Response.Status Javadoc
Appliance library services
IBM Cloud Manager with OpenStack provides the following services for appliance libraries.
Related information:
“Code license and disclaimer information” on page 208
GET /appliances
This service retrieves the appliances available in the appliance libraries of the cloud.
Sample Request
GET http://localhost:18080/cloud/api/appliances?architecture=*&cloudGroupId=251&user=admin
No HTTP body required.
Chapter1.IBMCloudManagerwithOpenStackRESTAPIreference 3
Query Parameters
Name Description Default Required
user Getsthelistofappliances N/A No
thatthisusernamecansee.
cloudGroupId Filtersthelistofappliances * No
bythespecified
cloudGroupId.
architecture Filtersthelistofappliances * No
bythespecifiedplatform
architecture.
start Theindexofthefirst 0 No
recordstoreturn.
count Thenumberofrecordsto 0 No
return.
owner Filtersthelistofappliances * No
bythespecifiedowner.
Sample Response
HTTP Status: 200
HTTP Response Body:
1. For all appliances, including the master and copied appliance, the HTTP Response Body shows the
creator as follows:
{
"total": "2",
"appliances": [
{
"cloudName": "mpcapture",
"changedDate": 1340720783000,
"cloudGroupId": "251",
"name": "mpcapture",
"uri": "http://localhost:18080/cloud/api/appliances/347",
"cloudId": "cloud://251/49826",
"state": {
"label": "OK",
"id": "OK"
},
"architecture": "Power",
"projectUri": "http://localhost:18080/cloud/api/projects/151",
"cloudGroupName": "9.123.100.141",
"specificationVersion": "1.1",
"hypervisor": "PowerVM",
"version": "1.1",
"id": "347",
"revision": "1.1",
"description": "true"
},
{
"cloudName": "mpcapture",
"changedDate": 1340199429000,
"cloudGroupId": "251",
"name": "mpcapture",
"uri": "http://localhost:18080/cloud/api/appliances/303",
"cloudId": "cloud://251/49567",
"state": {
"label": "Unknown",
4 IBMCloudManagerwithOpenStack: RESTAPIReference,version4.2