IBM Cloud Manager with OpenStack: REST API … 1. IBM Cloud Manager with OpenStack REST API...
Transcript of IBM Cloud Manager with OpenStack: REST API … 1. IBM Cloud Manager with OpenStack REST API...
IBM Cloud Manager with OpenStack
REST API Reference, version 4.2
���
IBM Cloud Manager with OpenStack
REST API Reference, version 4.2
���
NoteBefore using this information and the product it supports, read the information in “Notices” onpage 205.
Seventh Edition (December 2014)
© Copyright IBM Corporation 2011, 2014.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.
Contents
Chapter 1. IBM Cloud Manager withOpenStack REST API reference . . . . 1Overview of IBM Cloud Manager with OpenStackREST web services . . . . . . . . . . . . 1
Web services provided by IBM Cloud Managerwith OpenStack . . . . . . . . . . . . 1Connecting to an IBM Cloud Manager withOpenStack server . . . . . . . . . . . . 2IBM Cloud Manager with OpenStack REST APIresponse codes. . . . . . . . . . . . . 3
Appliance library services . . . . . . . . . . 3GET /appliances . . . . . . . . . . . . 3GET /appliances/{id} . . . . . . . . . . 5PUT/appliances/{id} . . . . . . . . . . 6DELETE/appliances/{id} . . . . . . . . . 6GET /appliances/{id}/copies . . . . . . . . 7GET /appliances/{id}/targets. . . . . . . . 7GET /appliances/{id}/customization . . . . . 8PUT /appliances/{id}/properties . . . . . . 13DELETE /appliances/{id}/customization . . . 14GET /appliances/{id}/log . . . . . . . . 14POST /appliances . . . . . . . . . . . 15GET /targets . . . . . . . . . . . . . 15GET /targets/{TargetId}/virtualServers . . . . 17
Authentication services . . . . . . . . . . 17POST /auth . . . . . . . . . . . . . 17GET /auth/reminder . . . . . . . . . . 18POST /auth/registration . . . . . . . . . 19GET /auth/reminder/isEnabled . . . . . . 19
Billing services . . . . . . . . . . . . . 20GET /accounts . . . . . . . . . . . . 20POST /accounts . . . . . . . . . . . . 21GET /accounts/{id} . . . . . . . . . . 21PUT /accounts/{id} . . . . . . . . . . 22DELETE /accounts/{id} . . . . . . . . . 22GET /accounts/users . . . . . . . . . . 23GET /accounts/{id}/users . . . . . . . . 24GET /accounts/{id}/users/{id} . . . . . . . 24POST /accounts/{id}/users . . . . . . . . 25DELETE /accounts/{id}/users/{id} . . . . . 26GET /accounts/{id}/bills . . . . . . . . . 27GET /accounts/{id}/bills/{id} . . . . . . . 27GET /accounts/{id}/charges . . . . . . . 28GET /accounts/{id}/credits . . . . . . . . 29POST /accounts/{id}/credits . . . . . . . 29
Billing cloud product services . . . . . . . . 30GET /billing/cloudProducts . . . . . . . . 30GET /billing/cloudProducts/{prodId} . . . . 31
Billing payment authorizer services . . . . . . 32GET /billing/paymentAuthorizers . . . . . 32GET /billing/paymentAuthorizers/{id} . . . . 32
Configuration services . . . . . . . . . . . 33GET /configuration/properties . . . . . . . 33GET /configuration/ipAddressPools . . . . . 34GET /configuration/ldap.xml . . . . . . . 34
PUT /configuration/ldap.xml . . . . . . . 35GET /configuration/ldapCert . . . . . . . 36PUT /configuration/ldapCert . . . . . . . 37
Cloud management services . . . . . . . . . 37GET /clouds/certificate . . . . . . . . . 37POST /clouds . . . . . . . . . . . . 38DELETE /clouds/{id} . . . . . . . . . . 40GET /clouds . . . . . . . . . . . . . 40GET /clouds/{id} . . . . . . . . . . . 41GET /clouds?types . . . . . . . . . . . 42GET /clouds/{id}/certificate . . . . . . . 42PUT /clouds/{id} . . . . . . . . . . . 43
Delinquency policies services . . . . . . . . 44GET /billing/delinquencyPolicies . . . . . . 44GET /billing/delinquencyPolicies/{id} . . . . 44
Event services . . . . . . . . . . . . . 45DELETE /events . . . . . . . . . . . 45GET /events . . . . . . . . . . . . . 45GET /events/eventcsv. . . . . . . . . . 48GET /events/{id} . . . . . . . . . . . 48
Expiration policy services. . . . . . . . . . 49GET /expirationPolicies . . . . . . . . . 49PUT /expirationPolicy. . . . . . . . . . 50GET /expirationPolicy/{id} . . . . . . . . 51PUT /expirationPolicy/{id} . . . . . . . . 51GET /projects/{id}/expirationPolicy . . . . . 52
Key pair services . . . . . . . . . . . . 53GET /keypairs . . . . . . . . . . . . 53GET /keypairs/{id}. . . . . . . . . . . 54POST /keypairs . . . . . . . . . . . . 54
License key services . . . . . . . . . . . 56GET /licensing . . . . . . . . . . . . 56PUT /licensing . . . . . . . . . . . . 57
Metering data services. . . . . . . . . . . 57GET /udrfiles . . . . . . . . . . . . 57GET /udrfiles/{directoryName} . . . . . . 57GET /udrfiles/{directoryName}/{fileName} . . 58GET /udrs . . . . . . . . . . . . . 58GET /udrs/{id} . . . . . . . . . . . . 60
Network configuration services . . . . . . . . 61GET /networkConfigurations . . . . . . . 61POST /networkConfigurations . . . . . . . 65GET /networkConfigurations/{id}. . . . . . 68PUT /networkConfigurations/{id}. . . . . . 69DELETE /networkConfigurations/{id} . . . . 70GET /networkConfigurations/{id}/ipAddresses 71POST /networkConfigurations/{id}/ipAddresses 72GET /networkConfigurations/{id}/ipAddresses/{ip} . . . . . . . . . . . . . . . . 74PUT /networkConfigurations/{id}/ipAddresses/{ip} . . . . . . . . . . . . . . . . 74DELETE /networkConfigurations/{id}/ipAddresses/{ip} . . . . . . . . . . . 75GET /networks/{cloudid}/floatingips . . . . 75GET /networks/{cloudid}/floatingips/{serverid} 76
© Copyright IBM Corp. 2011, 2014 iii
PUT /networks/{cloudid}/floatingips/{floatingip id} . . . . . . . . . . . . . . . 77
Product information services . . . . . . . . 78GET /productInfo/version . . . . . . . . 78GET /productInfo/shortName . . . . . . . 78GET /productInfo/name . . . . . . . . . 78GET /productInfo/fullName . . . . . . . 79GET /productInfo/vendorName . . . . . . 79GET /productInfo/vendorIcon . . . . . . . 80GET /productInfo/splash . . . . . . . . 80GET /productInfo/icon{type} . . . . . . . 80
Project management services . . . . . . . . 81GET /projects . . . . . . . . . . . . 81POST /projects . . . . . . . . . . . . 82DELETE /projects/{id} . . . . . . . . . 83PUT /projects/{id} . . . . . . . . . . . 83GET /projects/{id} . . . . . . . . . . . 84GET /projects/{id}/workloads . . . . . . . 84GET /projects/{id}/appliances . . . . . . . 86GET /projects/{id}/users . . . . . . . . . 87GET /projects/{id}/expirationPolicy . . . . . 87POST /projects/{id}/users . . . . . . . . 88PUT /projects/{id}/users/{username} . . . . 89DELETE /projects/{id}/users/{username} . . . 89
Request lifecycle services . . . . . . . . . . 90GET /requests . . . . . . . . . . . . 90PUT /requests . . . . . . . . . . . . 91GET /requests/{id} . . . . . . . . . . . 92PUT /requests/{id} . . . . . . . . . . . 92GET /requests/{id}/parameters . . . . . . 93PUT /requests/{id}/parameters . . . . . . 94GET /requests/{id}/comments . . . . . . . 94POST /requests/{id}/comments . . . . . . 95GET /requests/handlers . . . . . . . . . 95PUT /requests/handlers . . . . . . . . . 98GET /requests/requestcsv . . . . . . . . 98DELETE /requests/requstcsv . . . . . . . 99
Statistics resource services . . . . . . . . . 100GET /stats/free . . . . . . . . . . . 100GET /stats/totals . . . . . . . . . . . 102GET /stats/usage . . . . . . . . . . . 103
User services . . . . . . . . . . . . . 105GET /users . . . . . . . . . . . . . 105GET /users/{username} . . . . . . . . . 106POST /users . . . . . . . . . . . . 107PUT /users/{username} . . . . . . . . . 108DELETE /users/{username} . . . . . . . 109
Virtual server services . . . . . . . . . . 109GET /workloads/{id}/virtualServers . . . . 109GET /workloads/{id}/virtualServers/{id} . . . 111GET /workloads/{id}/virtualServers/{id}/credentials . . . . . . . . . . . . . 113PUT /workloads/{id}/virtualServers/{id}/credentials . . . . . . . . . . . . . 113GET /virtualServers . . . . . . . . . . 114GET /virtualServers/{id} . . . . . . . . 115PUT /virtualServers/{id} . . . . . . . . 118
GET /virtualServers/{id}/log . . . . . . . 119GET /virtualServers/{id}/storages . . . . . 120GET /virtualServers/{id}/storages/{id} . . . 120POST /virtualServers/{id}/storages . . . . . 121DELETE /virtualServers/{id}/storages/{id} . . 122GET /virtualServers/{id}/networks . . . . . 123GET /virtualServers/{id}/networks/{id} . . . 125GET /virtualServers/{id}/backups . . . . . 127GET /virtualServers/{id}/backups/{id} . . . 127POST /virtualServers/{id}/backups . . . . . 128PUT /virtualServers/{id}/backups/{id} . . . 128DELETE /virtualServers/{id}/backups/{id} . . 129GET /virtualServers/{id}/repositories . . . . 129GET /virtualServers/{id}/repositories/{id}/customization . . . . . . . . . . . . 130
Workload services . . . . . . . . . . . . 130GET /multiWorkloads/{id} . . . . . . . . 130GET /workloads . . . . . . . . . . . 132POST /workloads . . . . . . . . . . . 133GET /workloads/{id} . . . . . . . . . 138GET /workloads/{id}/customization . . . . 139GET /workloads/{id}/target . . . . . . . 152GET /workloads/{id}/log . . . . . . . . 153GET /workloads/{id}/virtualServers . . . . 153GET /workloads/{id}/virtualServers/{id} . . . 155GET /workloads/{id}/virtualServers/{id}/credentials . . . . . . . . . . . . . 157PUT /workloads/{id}/virtualServers/{id}/credentials . . . . . . . . . . . . . 157GET /workloads/{id}/timestamps . . . . . 158PUT /workloads/{id} . . . . . . . . . 159DELETE /workloads/{id} . . . . . . . . 163GET /workloads/stats . . . . . . . . . 164GET /workloads/owners . . . . . . . . 164
Chapter 2. IBM OpenStack REST APIreference . . . . . . . . . . . . . 167Overview of IBM OpenStack REST API reference 167Access OpenStack APIs . . . . . . . . . . 167OpenStack REST APIs . . . . . . . . . . 168
Keystone . . . . . . . . . . . . . . 169Glance. . . . . . . . . . . . . . . 173Neutron . . . . . . . . . . . . . . 174Cinder. . . . . . . . . . . . . . . 180Nova . . . . . . . . . . . . . . . 182
Related information. . . . . . . . . 201
Accessibility . . . . . . . . . . . . 203
Notices . . . . . . . . . . . . . . 205Trademarks . . . . . . . . . . . . . . 207Privacy policy considerations . . . . . . . . 207Code license and disclaimer information . . . . 208
iv IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
Chapter 1. IBM Cloud Manager with OpenStack REST APIreference
IBM® Cloud Manager with OpenStack version 4.2 provides a self-service portal for the cloud user thatcomplements VMware vSphere, and Hyper-V through OpenStack. IBM Cloud Manager with OpenStackalso supports Linux Kernel-based Virtual Machine (KVM) and PowerVC through OpenStack. IBM CloudManager with OpenStack is implemented as a lightweight web-based application that runs as an OpenServices Gateway initiative (OSGi) application. IBM Cloud Manager with OpenStack provides anenvironment that enables cloud users serve themselves while they maintain control over the allocation ofresources.
The self-service capabilities of IBM Cloud Manager with OpenStack simplify the process to carry outmany common public or private cloud operations such as the following operations:v Provisioning (deploying) and de-provisioning serversv Drafting and cloning workloadsv Taking workloads capturesv Starting and shutting down serversv Resizing existing serversv Creating projects to give team-specific access to workloadsv Providing network configurations that set unique network properties to different workloadsv Billing, accounting, and metering supportv Providing request and approval workflow supportv 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 theIBM Cloud Manager with OpenStack User Guide and the IBM Cloud Manager with OpenStackAdministrator Guide.Related information:“Code license and disclaimer information” on page 208
Overview of IBM Cloud Manager with OpenStack REST web servicesIBM Cloud Manager with OpenStack provides a set of APIs that can be used to access IBM CloudManager with OpenStack data and services from applications that are running outside of the IBM CloudManager with OpenStack framework. These APIs 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 usingthe HTTP or HTTPS protocol.
The REST APIs are implemented with complete compatibility from release to release. This means is thatnewer versions of IBM Cloud Manager with OpenStack do not have an impact on the code that uses theexisting REST APIs.
Web services provided by IBM Cloud Manager with OpenStackIBM Cloud Manager with OpenStack provides the web services that are listed here.v Appliance library services
© Copyright IBM Corp. 2011, 2014 1
v Authentication servicesv Billing servicesv Billing cloud product servicesv Billing payment authorizer servicesv Cloud management servicesv Configuration servicesv Delinquency policies servicesv Event servicesv Expiration policy servicesv Key pair servicesv Metering data servicesv Network configuration servicesv Product information servicesv Project management servicesv Request lifecycle servicesv Statistics resource servicesv User servicesv Virtual server servicesv Workload services
Connecting to an IBM Cloud Manager with OpenStack serverIBM Cloud Manager with OpenStack is implemented as a lightweight web-based application that runs asan OSGi application.
For production environments, IBM recommends that you use secure sockets layer (SSL) HTTPScommunication between the IBM Cloud Manager with OpenStack server and the client that is using theIBM Cloud Manager with OpenStack REST APIs. Using SSL provides a greater level of security for thedata on the network. For more information about configuring the server to use SSL communications, seethe IBM Cloud Manager with OpenStack Administrator Guide.
All APIs, except for the authentication APIs, require authentication. The preferred method to providecredential information is to use the /auth API. Use the /auth API to authenticate your user name andpassword and then use an authentication token for other APIs. For more information, see “POST /auth”on page 17 API.
To establish a connection to the IBM Cloud Manager with OpenStack server, the format of the URL mustbe:<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 thedata provider.<port>
2 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
is the remote port that is used for the scheme. The IBM Cloud Manager with OpenStack server currentlyuses 18080 for HTTP requests and 18443 for HTTPS requests.
IBM Cloud Manager with OpenStack REST API response codesFind detailed information about the REST API response codes.
200 OKThe request was fulfilled successfully.
201 CreatedFollowing a POST command, this response indicates that the specified resource was successfullycreated. This response includes the URI of the newly created resource in the HTTP Locationheader.
202 AcceptedThe request is accepted for processing, but the processing is not complete. The request mighteventually 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 beapproved by an administrator. The URI of the request that must be approved is included in theHTTP Location header of the response. Thus, users can track the status of their request by usingthat URI.
400 Bad requestThe request has incorrect syntax. For example, the JSON object is not recognized or is not validJSON.
401 UnauthorizedThe parameter to this message gives a specification of authorization schemes that are acceptable.Submit the request with a suitable Authorization header.
404 Not foundThe server cannot find the resource that is requested in the URI.
500 Internal ErrorThe 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 servicesIBM Cloud Manager with OpenStack provides the following services for appliance libraries.Related information:“Code license and disclaimer information” on page 208
GET /appliancesThis 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.
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 3
Query Parameters
Name Description Default Required
user Gets the list of appliancesthat this user name can see.
N/A No
cloudGroupId Filters the list of appliancesby the specifiedcloudGroupId.
* No
architecture Filters the list of appliancesby the specified platformarchitecture.
* No
start The index of the firstrecords to return.
0 No
count The number of records toreturn.
0 No
owner Filters the list of appliancesby the specified owner.
* No
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 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
"id": "UNKNOWN"},"architecture": "Power","projectUri": "http://localhost:18080/cloud/api/projects/151","cloudGroupName": "9.123.100.141","specificationVersion": "1.1","hypervisor": "PowerVM","version": "1.1","id": "303","revision": "1.1","description": "true"
}]
2. If the appliance is a copy of another appliance, the HTTP Response Body shows the creator asfollows:{
cloudId: "cloud://301/46047",cloudGroupId: "301",projectUri: "http://localhost:18080/cloud/api/projects/1",cloudGroupName: "9.123.100.120",state: {
id: "OK",label: "OK"
},architecture: "Power",logsUri: "http://localhost:18080/cloud/api/appliances/357/log",uri: "http://localhost:18080/cloud/api/appliances/357",specificationVersion: "1.1",creator: {
id: "admin",name: "SmartCloud Entry Administrator"
},cloudName: "RHEL63-Master",id: "357",changedDate: 1358392009084,revision: "1.1",customizationUri: "http://localhost:18080/cloud/api/appliances/357/customization",description: "root / passw0rd - RSCT 1.3.2.1 + fixes, AE 2.4.2.1",hypervisor: "PowerVM",name: "RHEL63-Master 2013-01-17 11:06:44",isMaster: false,targetsUri: "http://localhost:18080/cloud/api/appliances/357/targets"
}
GET /appliances/{id}This service retrieves the properties of a specific appliance by id.
Sample Request
GET http://localhost:18080/cloud/api/appliances/347
No HTTP body required.
Sample Response
HTTP Status: 200
Localized values: "state"
HTTP Response Body:
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 5
{
"cloudName": "mpcapture","changedDate": 1340720783000,"priority": 2,"cloudGroupId": "251","targetsUri": "http://localhost:18080/cloud/api/appliances/347/targets","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","customizationUri": "http://localhost:18080/cloud/api/appliances/347/customization","id": "347","revision": "1.1","description": "true","logsUri": "http://localhost:18080/cloud/api/appliances/347/log"
}
PUT/appliances/{id}This service updates the specific appliance by id.
Sample Request
PUT http://host/cloud/api/appliances/5415{
"name": "MyApp on AIX Image (dual-NIC) New Name","description": "Some Better Descripton)"
}
Sample Response
HTTP Status: 200
DELETE/appliances/{id}This service deletes an appliance that was captured by IBM Cloud Manager with OpenStack but failedduring capture or was deleted from the cloud.
This service deletes an appliance. If the appliance is in “Failed” state, “Unknown” state, or is a copy ofanother appliance, the appliance is only deleted from IBM Cloud Manager with OpenStack. If theappliance is in an OpenStack cloud, then it is deleted from the cloud as well. Deleting a master appliancethat is in an OpenStack cloud will delete all copies of the appliance as well.
Sample Request
DELETE http://host/cloud/api/appliances/5415
No HTTP body required.
Sample Response
HTTP Status: 200
6 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
GET /appliances/{id}/copiesThis service retrieves copies of the target appliance that is available in the cloud.
The master appliance is the first appliance link to the VMWare or OpenStack cloud appliance. When theID is the master image, this function returns a list of all its copies. When the ID is a copied image, thisfunction returns its master and all its copies
Query Parameters
N/A
Sample Request
Get http://host/cloud/api/appliances/1122/copies
Sample Response
HTTP Status: 200 OK{
total: "1",appliances: [
{cloudId: "cloud://301/46047",cloudGroupId: "301",projectUri: "http://localhost:18080/cloud/api/projects/1",cloudGroupName: "9.123.100.120",state: {
id: "UNKNOWN",label: "Unknown"
},architecture: "Power",uri: "http://localhost:18080/cloud/api/appliances/357",specificationVersion: "1.1",cloudName: "RHEL63-Master",version: "1.1",id: "357",changedDate: 1358392009084,revision: "1.1",description: "root / passw0rd - RSCT 1.3.2.1 + fixes, AE 2.4.2.1",hypervisor: "PowerVM",name: "RHEL63-Master 2013-01-17 11:06:44",isMaster: false,projectName: "Public"
}]
}
GET /appliances/{id}/targetsThis service retrieves the targets that are available in the cloud and that can handle a workload of thisappliance.
This list of targets can be used to select a target by ID and update the default target in the appliancedefault customization. This is an admin web service.
Query Parameters
Name Description Default Required
cpu The desired CPU size 0 No
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 7
Name Description Default Required
memory The desired memory size 0 No
Sample Request
To retrieve the workload targets for appliance with ID 1
GET http://host/cloud/api/appliances/1/targets
Sample Response
HTTP Status: 200 OK{
"total": "5","identifier": "id","targets": [
{"id": "cloud://551/123993","name": "DRSCluster (CLUSTER)","type": {"label": "Cluster","id": "CLUSTER"},"timeStamp": "Wed May 22 23:42:05 CST 2013","parent": "cloud://551/1239","hypervisor": "VMware","cloudGroupId": "31801","architecture": "x86","hypervisorVersion": "5.0","totalMem": 131046,"totalCpu": 32,"usedCpu": 20,"usedMem": 105421,"totalDisk": 7809,"usedDisk": 7051,"children": ["cloud://31801/44"],"virtualServers": [],"state": {"label": "OK","id": "ACTIVE"},"isDeployable": true
}]
}
GET /appliances/{id}/customizationThis service retrieves a default customization for an appliance.
When a user deploys an appliance, IBM Cloud Manager with OpenStack uses the default customizationas the workload configuration for the appliance. Customizations are configured by administrators.
This is an admin web service.
Query Parameters
N/A
8 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
Sample Request
To retrieve the default customization for appliance with ID 347:
GET http://host/cloud/api/appliances/1/customization
Sample Response
HTTP Status: 200 OK{
"target": "cloud://352/352","properties": [
{"category": "Network adapters","valueOrigin": [
"36ea3a9b-d4e6-4b4f-b13b-ddafa55a91e9"],"values": [
"36ea3a9b-d4e6-4b4f-b13b-ddafa55a91e9"],"basic": false,"description": "Networks settings of the image or virtual machine","classification": {
"id": "NETWORK","label": "Network"
},"name": "networkdevice.Network adapters.networks","required": true,"type": "MULTIPLE_SELECTION","rules": [
{"id": "max","value": "1"
},{
"id": "min","value": "1"
}],"options": [
{"id": "36ea3a9b-d4e6-4b4f-b13b-ddafa55a91e9","value": "flat (11.1.1.2 - 11.1.1.254)"
}]
},{
"category": "OpenStack Flavor","values": [
"1"],"basic": true,"description": "Flavors describe the different options for sizing the deployed instances","classification": {
"id": "HARDWARE","label": "Hardware"
},"name": "openstack.flavors","required": true,"type": "SINGLE_SELECTION","options": [
{"id": "1","value": "{\"ram\":512,\"disk\":1,\"name\":\"m1.tiny\",\"OS-FLV-EXT-DATA:ephemeral\":0,\"vcpus\":1}"
},{
"id": "2","value": "{\"ram\":2048,\"disk\":20,\"name\":\"m1.small\",\"OS-FLV-EXT-DATA:ephemeral\":0,\"vcpus\":1}"
},{
"id": "3","value": "{\"ram\":4096,\"disk\":40,\"name\":\"m1.medium\",\"OS-FLV-EXT-DATA:ephemeral\":0,\"vcpus\":2}"
},{
"id": "4",
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 9
"value": "{\"ram\":8192,\"disk\":80,\"name\":\"m1.large\",\"OS-FLV-EXT-DATA:ephemeral\":0,\"vcpus\":4}"},{
"id": "5","value": "{\"ram\":16384,\"disk\":160,\"name\":\"m1.xlarge\",\"OS-FLV-EXT-DATA:ephemeral\":0,\"vcpus\":8}"
}]
},{
"category": "Virtual Machine Configuration","values": [
true],"basic": false,"description": "Enable config drive (used to pass additional configuration data)","classification": {
"id": "SOFTWARE","label": "Software"
},"name": "openstack.config.drive","required": false,"type": "BOOLEAN"
},{
"category": "Access and Security","values": [
""],"basic": true,"description": "Keypair to use for SSH access to the virtual machine","classification": {
"id": "SOFTWARE","label": "Software"
},"name": "openstack.keypairs","required": false,"type": "SINGLE_SELECTION","options": [
{"id": "","value": ""
}]
},{
"category": "Virtual Machine Customization","values": [
""],"basic": false,"description": "Enter the contents of the customization script (user data)","classification": {
"id": "SOFTWARE","label": "Software"
},"name": "openstack.server.customizations","required": false,"type": "STRING","rules": [
{"id": "maxlen","value": "65535"
}]
},{
"category": "Virtual Machine Personality Files","values": [
""],"basic": false,"description": "Enter the contents of personality file 1","classification": {
"id": "SOFTWARE","label": "Software"
},"name": "openstack.server.personality.source.1","required": false,"type": "STRING",
10 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
"rules": [{
"id": "maxlen","value": "65536"
}]
},{
"category": "Virtual Machine Personality Files","values": [
""],"basic": false,"description": "Enter the target path and file name for personality file 1","classification": {
"id": "SOFTWARE","label": "Software"
},"name": "openstack.server.personality.target.1","required": false,"type": "STRING"
},{
"category": "Virtual Machine Personality Files","values": [
""],"basic": false,"description": "Enter the contents of personality file 2","classification": {
"id": "SOFTWARE","label": "Software"
},"name": "openstack.server.personality.source.2","required": false,"type": "STRING","rules": [
{"id": "maxlen","value": "65536"
}]
},{
"category": "Virtual Machine Personality Files","values": [
""],"basic": false,"description": "Enter the target path and file name for personality file 2","classification": {
"id": "SOFTWARE","label": "Software"
},"name": "openstack.server.personality.target.2","required": false,"type": "STRING"
},{
"category": "Virtual Machine Personality Files","values": [
""],"basic": false,"description": "Enter the contents of personality file 3","classification": {
"id": "SOFTWARE","label": "Software"
},"name": "openstack.server.personality.source.3","required": false,"type": "STRING","rules": [
{"id": "maxlen","value": "65536"
}]
},
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 11
{"category": "Virtual Machine Personality Files","values": [
""],"basic": false,"description": "Enter the target path and file name for personality file 3","classification": {
"id": "SOFTWARE","label": "Software"
},"name": "openstack.server.personality.target.3","required": false,"type": "STRING"
},{
"category": "Virtual Machine Personality Files","values": [
""],"basic": false,"description": "Enter the contents of personality file 4","classification": {
"id": "SOFTWARE","label": "Software"
},"name": "openstack.server.personality.source.4","required": false,"type": "STRING","rules": [
{"id": "maxlen","value": "65536"
}]
},{
"category": "Virtual Machine Personality Files","values": [
""],"basic": false,"description": "Enter the target path and file name for personality file 4","classification": {
"id": "SOFTWARE","label": "Software"
},"name": "openstack.server.personality.target.4","required": false,"type": "STRING"
},{
"category": "Virtual Machine Personality Files","values": [
""],"basic": false,"description": "Enter the contents of personality file 5","classification": {
"id": "SOFTWARE","label": "Software"
},"name": "openstack.server.personality.source.5","required": false,"type": "STRING","rules": [
{"id": "maxlen","value": "65536"
}]
},{
"category": "Virtual Machine Personality Files","values": [
""],"basic": false,"description": "Enter the target path and file name for personality file 5",
12 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
"classification": {"id": "SOFTWARE","label": "Software"
},"name": "openstack.server.personality.target.5","required": false,"type": "STRING"
}],"instances": 1,"appliance": {
"name": "mini-hyper-v","uri": "http://10.1.0.81:18080/cloud/api/appliances/1151"
}}
IBM Cloud Manager with OpenStack uses the rootpassword property to save the default root passwordfor the appliance. This property can be configured by an administrator on the appliance so each userdoes not need to configure the property for each workload.
PUT /appliances/{id}/propertiesThis service enables you to update the default customization for an appliance. You can use this service tospecify that an appliance is deployed to a specific target by default.
The customization for the appliance can also be given default values. These default values do notoverride explicit values that are given by a user for any workload property.
This is an admin web service.
Query Parameters
N/A
Sample Requests1. Update the default workload target for appliance 1, make it target with id 123.
PUT http://host/api/appliances/1/properties{
"target":"123"}
2. Update the default customization such that when deploying appliance 1, CPU mode is Dedicated andthe number of CPUs is 2 by default.PUT http://host/api/appliances/1/properties{
"properties":[{
"name":"cpumode","value": "DEDICATED"
},{
"name":"cpudedicated","value":2
}]
}
Sample Response
HTTP Status: 200
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 13
DELETE /appliances/{id}/customizationThis service resets the default customization for an appliance.
An administrator can use the DELETE /appliances/{id}/customization service to reset the customizedappliance to its initial settings. A customization, however, will never be null. This service resets thecustomization to the original values based on what is available in the cloud.
This is an admin web service.
Query Parameters
N/A
Sample Request
Reset the default customization for appliance 1
DELETE http://host/cloud/api/appliances/1/customization
Sample Response
HTTP Status: 200
GET /appliances/{id}/logThis service retrieves any capture progress logs for an appliance that is captured in the cloud.
The exact contents of the logs are dependent on how the cloud stores the logs for capture. Logs might bedeleted after an operation completes or fails; or, the logs might be maintained for an extended time. Theactual string data that is returned in the JavaScript Object Notation (JSON) response is HTML formatted.Rather than having Java™ new line strings, the data shows <br> tags.
Query Parameters
N/A
Sample Request
Get capture progress logs for appliance 1122.
GET http://host/cloud/api/appliances/1122/log
Sample Response
HTTP Status: 200 OK{
"log":"Workload, AIX 5L for POWER Version 5.3 , was created.
Start asynch work run for deploy of virtual appliance :8498
Workload removed due to exception: 11738
Workload, AIX 5L for POWER Version 5.3 , was deleted.
Error performing asynch work run for deploy of virtual appliance:8498
14 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
New workload removed: 11738"
}
POST /appliancesThis service creates a new appliance on the cloud. The appliance is created by capturing the current stateof a workload or by copying a master appliance that links to the VMware or OpenStack cloud appliance.
Note: This API does not support capture of an OpenStack PowerVM® instance, which is not in"STOPPED" state.
Query Parameters
N/A
Sample Requests1. Create an appliance by taking a capture of workload with workload ID 133.
POST http://host/cloud/api/appliances{
"workload":133
}
2. Create an appliance by capturing a workload with workload ID 133. The new appliance is a Linuximage and is at the image repository with ID 102.POST http://host/cloud/api/appliances{
"workload":133,"repository":"102","properties":[
{"name":"ostypecapture","value":"36"
}]
}
3. Create an appliance by copying the appliance (5415).{
"appliance":5415,"name":"TonyTest","description":"NIM mksysb 12/09/09",
}
Sample Response
HTTP Status: 201
HTTP Location Header: The URI of the new appliance
HTTP Body: CYX1008I: SUCCESS.
GET /targetsBased on your query parameters, this service returns a target list with cloud infrastructure and capacities,including the children and parent relationship, basic and advanced capacities and more.
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 15
Query Parameters
Table 1. Query parameters
Parameter Description Type Default Required or Optional
cloudGroupId The ID(s) of the cloud that the targets belongto, separated by a comma “,”.
String * Optional
architecture The architecture of the pool (x86 or Power). String * Optional
targetType The supported target types(host/systempool/resourcepool/az).
String * Optional
start The start index. Int 0 Optional
count The count of the returned results. Int 0 Optional
hypervisor The hypervisor of the targets. String * Optional
sortBy Sort by the target name, ID, state or the generalmetric IDs, such as totalCpu.
String ID Optional
order Descending or Ascending String desc Optional
parentCloudId Retrieve the children targets whose parentcloud ID is the given parentId.
String * Optional
vsId This parameter is used to get the target for avirtual server.
String * Optional
targetId The ID(s) of the target(s), separated by acomma.
String * Optional
includeUndeployable Whether to include the undeployable targets inthe response
String true Optional
Sample Request
To retrieve the workload targets for a hypervisor, such as VMware:
GET http://host/cloud/api/appliances/1/targets?hypervisor=VMware
Sample Response{
"total": "5","identifier": "id","targets": [
{"id": "cloud://551/123993","name": "DRSCluster (CLUSTER)","type": {"label": "Cluster","id": "CLUSTER"
},"timeStamp": "Wed May 22 23:42:05 CST 2013","parent": "cloud://551/1239","hypervisor": "VMware","cloudGroupId": "31801","architecture": "x86","hypervisorVersion": "5.0","totalMem": 131046,"totalCpu": 32,"usedCpu": 20,"usedMem": 105421,"totalDisk": 7809,"usedDisk": 7051,"children": ["cloud://31801/44"
16 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
],"virtualServers": [],"state": {"label": "OK","id": "ACTIVE"},"isDeployable": true
}]
}
GET /targets/{TargetId}/virtualServersRetrieve the virtual servers running on a given target. If no virtual servers exist on this target, the queryreturns an empty list.
Query Parameters
N/A
Sample Request
To retrieve the workload targets for an appliance with ID 1:
GET http://host/cloud/api/targets/101/virtualServers
Sample Response{
"virtualServers":[{
"uri":"http://localhost:8080/cloud/api/workloads/id/virtualServers/5416","credentialsUri":"http://localhost:8080/cloud/api/workloads/id/virtualServers/5416","storagesUri":"http://localhost:8080/cloud/api/virtualServers/5416/storages","savedServerImages":"http://localhost:8080/cloud/api/virtualServers/5416/serverimages","id":5416,"hostname":"VS 1","ip":"9.9.9.9, 10.10.10.10","state":"Deployment desc"
}]
}
Authentication servicesIBM Cloud Manager with OpenStack provides services for requesting new users and services that arerelated to passwords.Related information:“Code license and disclaimer information” on page 208
POST /authThe POST /auth API validates the credentials for a user.
The service takes an x-www-form-urlencoded form with two parameters: user name and password.
Upon successful credential validation, the service returns an encrypted authentication token and theexpiration for the token (in UTC format). This encrypted authentication token can then be used onsubsequent secure API calls rather than using x-www-form-urlencoded credentials for each API call.Using authentication tokens for secure REST APIs is the recommended method of authentication. Thex-www-form-urlencoded form is deprecated for anything other than the auth service.
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 17
To use an encrypted authentication token on REST API calls, the REST agent must populate the HTTPrequest header with the cookie field name configured to transport authentication tokens (see the IBMCloud Manager with OpenStack Administrator Guide). The IBM Cloud Manager with OpenStack RESTAPIs then obtain the encrypted authentication token from the cookie header and use it to validate theREST agent's identity.
If IBM Cloud Manager with OpenStack is configured to renew authentication tokens that are based onAPI usage, successfully authenticated API responses will also include a Set-Cookie header with arenewed authentication token and its associated expiration. The agent can then use this renewed token onsubsequent REST calls. However if an authentication token expires, the agent must again use the authservice REST API to re-authenticate their credentials and obtain a new token.
This is an unauthenticated web service. This web service does not require authentication, so it isunsecured. The base uri for this web service is '/unsecured/cloud/api', so the complete URI looks likethe following:
http://localhost:18080/unsecured/cloud/api/auth
HTTP Status: 200 if the user successfully authenticated 401 Unauthorized and 403 Forbidden.
Sample Response
HTTP Status: 200
HTTP Response Body:{
"access":{"expires":1358206562876,"id":"S9EWN4xGHr7Knp583hyEWVHQohvg1PwycSvARknLNxNeMdU5db4qn9p+i1dFae2X"
}}
GET /auth/reminderThe GET /auth/reminder API requests that a password reminder is sent to the associated user with anemail notification (as of version 1.1).
The actual reminder is sent only if the user name is specified and the installation has enablednotifications.
This web service does not require authentication, so it is unsecured. The base URI for this web serviceis “/unsecured/cloud/api”, so the complete URI looks like the following:
http://localhost:18080/unsecured/cloud/api/auth/reminder
Query Parameters
Name Description Default Required
user The user name that is requesting the password reminder. NA Yes
email The email the password reminder sent to. NA Yes
Sample Request
Send a password reminder to the user 'john' for this account.
GET http://host/unsecured/cloud/api/auth/reminder?user=john&[email protected]
18 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
HTTP Request Body:
N/A
Sample Response
HTTP Status: 200
POST /auth/registrationThe POST /auth/registration API creates a request for the administrator to approve. After approval, anew user account is created.
The JSON in the request body should define the suggested values for the new user account. If thenotification is enabled, an email is sent to the administrator with the request.
This web service does not require authentication, so it is unsecured. The base URI for this web serviceis “/unsecured/cloud/api”, so the complete URI looks like the following:
http://localhost:18080/unsecured/cloud/api/auth/registration
Specify the Content Type as application/json.
Query Parameters
N/A
Sample Request
Send the administrator a notification that requests a new user account for “john”.
POST http://host/unsecured/cloud/api/auth/registration
HTTP Request Body:{
"username":"john","name":"Mr John","password":"pwd4me","email":"[email protected]"
}
Sample Response
HTTP Status: 202
No HTTP Response Body
GET /auth/reminder/isEnabledThe GET /auth/reminderisEnabled API sends a password reset reminder.
No resource is returned.
Sample Response
HTTP Status:v 200 if the password reset reminder is enabled.
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 19
v 500 if the password reset reminder is not enabled
Billing servicesThe IBM Cloud Manager with OpenStack product provides the billing services that are listed here.Related information:“Code license and disclaimer information” on page 208
GET /accountsThis service retrieves the accounts that are defined in IBM Cloud Manager with OpenStack.
Query Parameters
Name Description Default Required
user Retrieve only the accountsthat this user has access to(either by ownership or bymembership).Administrators can see allaccounts.
false No
Sample Requests1. Get all accounts known to the system
GET http://host/cloud/api/accountsNo HTTP body required.
2. Get all accounts to which user “user1”belongs to, owns, or is a member of.GET http://host/cloud/api/accounts?user=user1No HTTP body required.
Sample Response
HTTP Status: 200
HTTP Response Body:{
"accounts": [{
"state": {"label": "Delinquent","id": "DELINQUENT"
},"isDelinquent": true,"currency": "USD","owner": "user1","accountNumber": "1401","name": "acc1","id": "1401","balance": 0,"description": "acc1","uri": "http://localhost:18080/cloud/api/accounts/1401"
}]
}
20 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
POST /accountsThis service creates a new account in IBM Cloud Manager with OpenStack. Use the POST/accounts/{id}/users API to add members to the account.
This request JSON allows for an (optional) 'startingBalance' attribute, which enables the user to specify aninitial balance for the account during creation. If specified, the newly created account is credited for the'startingBalance' amount.
Sample Request
POST http://host/cloud/api/accounts
HTTP Request Body:{
"currency":"USD","owner":"admin","lowFundsThreshold":"5.00","name":"test account.","description":"Test account for development purposes.","defaultPaymentAuthorizer": "admin","delinquencyPolicy": "com.ibm.cfs.services.billing.policies.shutdown","startingBalance":1203.22,"currency": "USD"
}
Sample Response
HTTP Status: 201
HTTP Location Header: The URI of the new account
HTTP Response Body:{"billsUri":"http://host.rchland.ibm.com:18080/cloud/api/accounts/101651/bills",
"isDelinquent":false,"usersUri":"http://host.rchland.ibm.com:18080/cloud/api/accounts/101651/users","delinquencyPolicy":"com.ibm.cfs.services.billing.policies.shutdown","name":"test account.","uri":"http://host.rchland.ibm.com:18080/cloud/api/accounts/101651","defaultPaymentAuthorizer":"admin","lowFundsThreshold":5.0,"currency":"USD","state":{
"label":"OK","id":"OK"
},"creditsUri":"http://host.rchland.ibm.com:18080/cloud/api/accounts/101651/credits","owner":"admin","accountNumber":"101651","id":"101651","description":"Test account for development purposes.","balance":-1203.22
}
GET /accounts/{id}This service retrieves the properties of a specific account by ID.
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 21
Sample Request
GET http://host/cloud/api/accounts/1
No HTTP body required.
Sample Response
Note: The "total" is presented formatted in currency for account.
HTTP Status: 200
HTTP Response Body:{"billsUri":"http://localhost:18080/cloud/api/accounts/451/bills",
"isDelinquent":false,"usersUri":"http://localhost:18080/cloud/api/accounts/451/users","name":"Admin Account","uri":"http://localhost:18080/cloud/api/accounts/451","lowFundsThreshold":"$1,000.00","currency":"USD","state":{
"label":"OK","id":"OK"
},"creditsUri":"http://localhost:18080/cloud/api/accounts/451/credits","owner":"admin","accountNumber":"451","id":"451","description":"","balance":"($10,000,000.00)"
}
PUT /accounts/{id}This service updates the properties of a specific account by ID.
Sample Request
PUT http://host/cloud/api/accounts/1{
"name":"Admin Account Changed","lowFundsThreshold":100000
}
Sample Response
HTTP Status: 200
SUCCESS: Account 451 updated.
DELETE /accounts/{id}This service removes an account.
Query Parameters
N/A
22 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
Sample Request
Remove the account “123”.
DELETE http://host/cloud/api/accounts/123
Sample Response
HTTP Status: 200
GET /accounts/usersThis service retrieves all users that do not belong to any account. For IBM Cloud Manager withOpenStack 2.0, users can belong to only one billing account. You can use this service to list all users whoare not members of any account. This service can be useful if you want to identify users that mightpotentially be added to a new account.
Query Parameters
N/A
Sample Request
Retrieve a listing of all users that do not belong to an account.
GET http://host/cloud/api/accounts/users
No HTTP body required.
Sample Response
HTTP Status: 200
HTTP Response Body:{
"users":[{
"username":"admin","name":"Administrator","isAdmin":true,"isApprover":true,"emailNotifications":false,"email":"[email protected]","uri":"http://localhost:18080/cloud/api/users/admin"
},{
"username":"[email protected]","name":"John Doe","isAdmin":false,"isApprover":true,"emailNotifications":true,"email":"[email protected]","uri":"http://localhost:18080/cloud/api/users/[email protected]"
}]
}
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 23
GET /accounts/{id}/usersThis service retrieves the all users (members) associated with this account. The list is the same format asthat returned under the 'users' resource but lists only those users who are members of this account. Users(members) can be added and removed with POST and DELETE as well.
Query Parameters
N/A
Sample Request
To retrieve all users for account with ID 1: GET http://host/cloud/api/accounts/1/users
Sample Response{
"users": [{
"isLocked": false,"isAdmin": true,"role": {
"label": "Admin","id": "ADMIN"
},"username": "admin","name": "Cloud Administrator","emailNotifications": false,"email": "","isApprover": true
},{
"isLocked": false,"isAdmin": false,"role": {
"label": "User","id": "USER"
},"username": "testUser","name": "testUser","emailNotifications": false,"email": "[email protected]","isApprover": false
}]
}
GET /accounts/{id}/users/{id}This service retrieves the specific user (member) associated with this account.
Query Parameters
N/A
Sample Request
To retrieve all users for account with ID 1: GET http://host/cloud/api/accounts/1/users/tester
Sample Response{
"cloudId":"cloud://351/0e158ff8847a47eaaef6e9be435b259d","emailNotifications": false,"username": "tester","isApprover": false,"name": "tester",
24 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
"role":{
"id": "USER","label": "User"
}"isAdmin": false,"uri": "http://localhost:18080/cloud/api/accounts/1/users/tester","isLocked": false
}
POST /accounts/{id}/usersThis service adds users to the member list for the account. This API does not create new users, so theusers must exist in the IBM Cloud Manager with OpenStack registry.
Query Parameters
N/A
Sample Request 1
Add the user with user name "admin" to the member list of account ID {id}:
POST http://localhost:18080/cloud/api/accounts/{id}/users
HTTP Request Body:{
"users": [{
"username": "test"}
]}Response:{
"users": [{
"isLocked": false,"isAdmin": false,"role": {
"label": "User","id": "USER"
},"username": "test","name": "test","emailNotifications": false,"isApprover": false
}]
}
Sample Response 1
HTTP Status: 201
HTTP Response Body:{
"users":[{
"isAdmin":true,"username":"admin","name":"Admin","emailNotifications":false,"isApprover":true
}]
}
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 25
Sample Request 2
Add the users with usernames “john”and “luis”to the member list of account ID 1.
POST http://host/cloud/api/accounts/1/users
HTTP Request Body:{"users":[
{"username":"john"
},{
"username":"luis"}
]}
Sample Response 2
HTTP Status: 201
HTTP Response Body:{"users":[
{"isAdmin":false,"username":"john","name":"John Doe","emailNotifications":false,"isApprover":false
},{
"isAdmin":false,"username":"luis","name":"Luis G","emailNotifications":false,"isApprover":false
}]
}
DELETE /accounts/{id}/users/{id}This service removes a user from the member list for an account. The user is not deleted from the IBMCloud Manager with OpenStack user registry, only the account association.
Query Parameters
N/A
Sample Request
Remove the user “jdoe” from the account ID 1.
DELETE http://host/cloud/api/accounts/1/users/jdoe
Sample Response
HTTP Status: 200
26 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
GET /accounts/{id}/billsThis service retrieves the bills for this account. This list of bills can be used to find the individual bill andtheir associated charges.
Query Parameters
N/A
Sample Request
To retrieve the bills for account with ID 1:
GET http://host/cloud/api/accounts/1/bills
Sample Response
Note: The "total" is presented formatted in the currency for the account.{
"bills": [{
"currency": "USD","total": 18.66666667008,"resourceID":"1120","resourceType": "workload","resourceName": "MyApp on SUSE Image 2012-07-19 10:52:15","id": "1151","creator": "admin","uri": "http://localhost:18080/cloud/api/accounts/551/bills/1151","invoice": "1151"
},{
"currency": "USD","total": 0,"resourceID":"1120","resourceType": "workload","resourceName": "MyApp on SUSE Image 2012-07-19 10:54:37","id": "1152","creator": "admin","uri": "http://localhost:18080/cloud/api/accounts/551/bills/1152","invoice": "1152"
}]
}
GET /accounts/{id}/bills/{id}This service retrieves a specific bill from the specified account. From this information, you can find linksto the deployment associated with this bill and list of all charges that are associated with the bill.
Query Parameters
N/A
Sample Request
Get bill with ID 1 from account with ID 1:
GET http://host/cloud/api/accounts/1/bills/1
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 27
Sample Response
In this sample, the total is presented formatted in currency for the account.{
"currency": "USD","total": 37.33333334016,"resourceID":"1120","resourceType": "workload","resourceName": "MyApp on SUSE Image 2012-07-19 10:52:15","id": "1151","creator": "admin","uri": "http://localhost:18080/cloud/api/accounts/551/bills/1151","chargesUri": "http://localhost:18080/cloud/api/accounts/551/bills/1151/charges","invoice": "1151"
}
GET /accounts/{id}/chargesThis service retrieves the charges from all bills for this account.
Query Parameters
N/A
Sample Request
To retrieve the all charges for account with ID 1:
GET http://host/api/accounts/1/charges
Sample Response
In this sample, the total is presented formatted in currency for the account. The values for currency,unitPrice, product, andid are defined in the SmartCloud Entry home path/products/*.xml file.{
"charges": [{
"currency": "USD","total": 0.0668,"unitPrice": 0.0167,"id": "com.ibm.cfs.cloud.openstack.products.cpu","date": 1340695970654,"product": "CPU","units": "4"
},{
"currency": "USD","total": 0.03333333334016,"unitPrice": 0.00001627604167,"id": "com.ibm.cfs.cloud.openstack.products.mem","date": 1340695970654,"product": "RAM","units": "2048"
},{
"currency": "USD","total": 0,"unitPrice": 0.00001627604167,"id": "com.ibm.cfs.cloud.openstack.products.storage","date": 1340695970654,"product": "Active Disk","units": "0"
}]
}
28 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
GET /accounts/{id}/creditsThis service retrieves the credits over all bills for this account.
Query Parameters
N/A
Sample Request
To retrieve the credits for account with ID 1:
GET http://host/cloud/api/accounts/1/credits
Sample Response
Note: The "amount" is presented formatted in currency for account.{{
"credits":[{
"currency":"USD","amount":"10.99","date":1296761386473,"description":"Credit description 1"
},{
"currency":"USD","amount":"15.99","date":1296761386473,"description":"Credit description 2"
}]
}
POST /accounts/{id}/creditsThis service adds credits to the specified account. You can use this service to add a credit or make apayment.
Payments can be added by any user. Payments are posted to the account if the payment passes thepayment authorization verification.
Credits can be made only by administrators. Credits are automatically added to an account when thecredit is made.
Query Parameters
Name Description Default Required
payment If true, then a payment authorizer is used. false No
Sample Requests1. Add $100.00 in credits to account ID 1.
POST http://host/cloud/api/accounts/1/creditsHTTP Request Body:{
"amount":100.00,"description":"Free 100 based on coupon."
}
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 29
2. Make a $50 payment to account 1, using the accounts default payment system.POST http://host/cloud/api/accounts/1/credits?payment=trueHTTP Request Body:{
"amount":50}
3. Make a $50 payment to account 1, using a provided payment system.POST http://host/cloud/api/accounts/1/credits?payment=trueHTTP Request Body:{
"amount":50.0,"paymentAuthorizer":"visa.payments"
}
Sample Response
HTTP Status: 200
HTTP Response Body: SUCCESS: The account is credited the requested amount.
Billing cloud product servicesIBM Cloud Manager with OpenStack provides the billing cloud product services that are listed here.Related information:“Code license and disclaimer information” on page 208
GET /billing/cloudProductsThis service gets the summary list of all products.
Sample Request
GET http://host/cloud/api/billing/cloudProducts
No HTTP body required.
Sample Response
HTTP Status: 200
Localized values: "state"
HTTP Response Body:{
"cloudProducts": [{
"currency": "USD","name": "Active Disk","id": "com.ibm.cfs.cloud.openstack.products.storage","description": "The storage space allocated to a virtual machine.","uri": "http://localhost:18080/cloud/api/billing/cloudProducts/com.ibm.cfs.cloud.openstack.products.storage"
},{
"currency": "USD","name": "CPU","id": "com.ibm.cfs.cloud.vmware.products.cpu","description": "The cpu allocated to a virtual machine.","uri": "http://localhost:18080/cloud/api/billing/cloudProducts/com.ibm.cfs.cloud.vmware.products.cpu"
30 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
},{
"currency": "USD","name": "RAM","id": "com.ibm.cfs.cloud.openstack.products.mem","description": "The ram allocated to a virtual machine.","uri": "http://localhost:18080/cloud/api/billing/cloudProducts/com.ibm.cfs.cloud.openstack.products.mem"
},{
"currency": "USD","name": "Active Disk","id": "com.ibm.cfs.cloud.vmware.products.storage","description": "The storage space allocated to a virtual machine.","uri": "http://localhost:18080/cloud/api/billing/cloudProducts/com.ibm.cfs.cloud.vmware.products.storage"
},{
"currency": "USD","name": "CPU","id": "com.ibm.cfs.cloud.openstack.products.cpu","description": "The cpu allocated to a virtual machine.","uri": "http://localhost:18080/cloud/api/billing/cloudProducts/com.ibm.cfs.cloud.openstack.products.cpu"
},{
"currency": "USD","name": "RAM","id": "com.ibm.cfs.cloud.vmware.products.memory","description": "The ram allocated to a virtual machine.","uri": "http://localhost:18080/cloud/api/billing/cloudProducts/com.ibm.cfs.cloud.vmware.products.memory"
}]
}
GET /billing/cloudProducts/{prodId}This service gets the information for a specific product.
Sample Request
GET http://host/cloud/api/billing/cloudProducts/com.ibm.cfs.services.billing.products.cpu
No HTTP body required.
Sample Response
HTTP Status: 200
Localized values: "state"
HTTP Response Body:{
"currency": "USD","price": "$0.00","actualPrice": "0.00006627604167","name": "RAM","id": "com.ibm.cfs.cloud.openstack.products.mem","description": "The ram allocated to a virtual machine.","uri": "http://localhost:18080/cloud/api/billing/cloudProducts/com.ibm.cfs.cloud.openstack.products.mem","priceInterval": 60
}
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 31
Billing payment authorizer servicesIBM Cloud Manager with OpenStack provides the following services that are related to paymentauthorizers.Related information:“Code license and disclaimer information” on page 208
GET /billing/paymentAuthorizersThis service retrieves all the payment authorizers that are defined within IBM Cloud Manager withOpenStack.
Sample Request
GET http://host/cloud/api/billing/paymentAuthorizers
No HTTP body required.
Sample Response
HTTP Status: 200
HTTP Response Body:{
"paymentAuthorizers":[{
"name":"Administrator","id":"admin","uri":"http://localhost:18080/cloud/api/users/admin"
},{
"name":"John Doe","id":"[email protected]","uri":"http://localhost:18080/cloud/api/users/[email protected]"
}]
}
GET /billing/paymentAuthorizers/{id}This service retrieves the properties of a specific payment authorizer by id.
Sample Request
GET http://host/cloud/api/paymentAuthorizers/admin
No HTTP body required.
Sample Response
HTTP Status: 200
HTTP Response Body:{
"name":"Administrator","id":"admin","uri":"http://localhost:18080/cloud/api/billing/paymentAuthorizers/admin"
}
32 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
Configuration servicesIBM Cloud Manager with OpenStack provides several services that are related to cloud configuration.Related information:“Code license and disclaimer information” on page 208
GET /configuration/propertiesThis service retrieves the configuration properties that are specified for the framework, from all theproperties files in the home directory for the framework.
Query Parameters
N/A
Sample Request
Get current configuration properties:
GET http://host/cloud/api/configuration/properties
Sample Response
HTTP Status: 200
HTTP Response Body:{
"product.AIX1.com.ibm.ovf.vim.2.networkport.6.dns2.ip":"10.10.1.17","product.AIX1.com.ibm.ovf.vim.2.networkport.7.dns2.ip":"9.10.244.100","admin.name":"Administrator","com.ibm.csk.email.relay.host":"relay.us.ibm.com","com.ibm.cfs.cloud.hostname":"csk-mgr.rchland.ibm.com","product.AIX1.com.ibm.ovf.vim.2.networkport.6.ip":"{SKC_Test_VLAN2}","product.AIX1.com.ibm.ovf.vim.2.nim.7.nim.Resource.1":"CB_LPAR_FIXUP","admin.username":"admin","product.AIX1.com.ibm.ovf.vim.2.networkport.7.domainname":"rchland.ibm.com","product.AIX1.com.ibm.ovf.vim.2.system.domainname":"icbvm.cloud.com","admin.password":"admin","com.ibm.csk.email.from.address":"[email protected]","product.AIX1.com.ibm.ovf.vim.2.networkport.6.dns1.ip":"10.10.1.17","product.AIX1.com.ibm.ovf.vim.2.networkport.7.dns1.ip":"9.10.244.200","com.ibm.cfs.billing.delinquency.policy":"com.ibm.cfs.services.billing.policies.shutdown","com.ibm.cfs.cloud.mock":"true","com.ibm.cfs.billing.enabled":"false","authentication.secure":"true","com.ibm.csk.deployments.threads":"4","authentication.type":"LOCAL","product.AIX1.com.ibm.ovf.vim.2.networkport.7.ip":"{SKC_Test_VLAN3}","com.ibm.cfs.billing.account.balance.threshold.interval":"24","virtualnetworks-1":"[Network 1]=hostVnet:ETHERNET0/2","com.ibm.cfs.cloud.username":"root","com.ibm.csk.deployments.target.strategy":"anyPoolOrHost","product.AIX1.com.ibm.ovf.vim.2.networkport.6.gateway":"10.10.1.17","com.ibm.cfs.request.lifecycle.enabled":"true","com.ibm.cfs.cloud.password":"passw0rd","com.ibm.cfs.billing.delinquency.finder.interval":"120","product.AIX1.com.ibm.ovf.vim.2.networkport.7.gateway":"9.5.110.1","product.AIX1.com.ibm.ovf.vim.2.networkport.6.domainname":"icbvm.cloud.com","product.AIX1.com.ibm.ovf.vim.2.networkport.6.netmask":"255.255.0.0","product.AIX1.com.ibm.ovf.vim.2.networkport.7.netmask":"255.255.0.0""product.cloud.name.replacements": "Unknown",
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 33
GET /configuration/ipAddressPoolsThis service retrieves the IP address pools for each network configuration.
Query Parameters
N/A
Sample Request
Get current configuration properties for IP address pools:
GET http://host/cloud/api/configuration/ipAddressPools
Sample Response
HTTP Status: 200
HTTP Response Body:
{"ipAddressPools":[
{"size":1,"id":"1","name":"Default Network Configuration","uri":"http://localhost:18080/cloud/api/configuration/ipAddressPools/1"
},{
"size":508,"id":"2","name":"VLAN1","uri":"http://localhost:18080/cloud/api/configuration/ipAddressPools/2"
},{
"size":508,"id":"3","name":"VLAN2","uri":"http://localhost:18080/cloud/api/configuration/ipAddressPools/3"
}]
}
GET /configuration/ldap.xmlThis service retrieves the ldap.xml file, which defines the authentication properties and authenticationprocess that is used to connect to an LDAP server.
This is an admin web service.
Query Parameters
N/A
Sample Request
Get the ldap.xml file
GET http://host/cloud/api/configuration/ldap.xml
34 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
Sample Response
HTTP Status: 200
Content-Type: application/xml<?xml version="1.0"?><config>
<host>ldap://ldap.company.com</host><adminUsers>[email protected],[email protected]</adminUsers><enableSecureConn>true</enableSecureConn><userNameCaseSensitive>true</userNameCaseSensitive><step>
<authDN password=encryptedPassword>dnname</authDN><searchFilter>(|(mail={FILTER}))</searchFilter><searchContext>ou=directory,o=company.com</searchContext><outputs>
<output attribute="fullname"><get>cn</get>
</output></outputs>
</step><step>
<authDN>{PERSON_DN}</authDN></step>
</config>
PUT /configuration/ldap.xmlThis service updates the ldap.xml file, which defines the authentication properties and authenticationprocess that is used to connect to an LDAP server.
This is an admin web service.
Query Parameters
N/A
Sample Request
Put the ldap.xml file
PUT http://host/cloud/api/configuration/ldap.xml
Content-Type: application/xml<?xml version="1.0"?><config>
<host>ldap://ldap.company.com</host><adminUsers>[email protected],[email protected]</adminUsers><enableSecureConn>true</enableSecureConn><userNameCaseSensitive>true</userNameCaseSensitive><step>
<authDN password=”password”>dnname</authDN><searchFilter>(|(mail={FILTER}))</searchFilter><searchContext>ou=directory,o=company.com</searchContext><outputs>
<output attribute="fullname"><get>cn</get>
</output></outputs>
</step>
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 35
<step><authDN>{PERSON_DN}</authDN>
</step></config>
Sample Response
HTTP Status: 200
GET /configuration/ldapCertThis service retrieves the LDAP certificates from the keystore file.
This is an admin web service.
Query Parameters
N/A
Sample Request
Get LDAP certificates from the keystore file.
GET http://host/cloud/api/configuration/ldapCert
Sample Response
HTTP Status: 200Alias: 91fc5d38-666e-4ee8-8acb-ca4e6754bab4Certificate: [
[Version: V3
Subject:
Signature Algorithm: SHA1withRSA, OID = 1.2.840.113549.1.1.5
Key: IBMJCE RSA Public Key:
modulus:
233222840559682160552494424168914123465535459927653816465538057056380630737573784084810165986593848641823781282052957155127020307894828777406433888459126501090251570862777428297841969331959525949251495884729242486972388882015395506744068463728289890342219176969498408904442936096168789191506795847812228078478276325922978043105122401057247226929270908857988324895606460992532903008736334186459710375419934944750492088292593539274329220188443389038090302693755401527571833727323114502906949469212417296045437833283
public exponent:
65537
- - - - - -- - -
- - - - - - - -
]
36 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
PUT /configuration/ldapCertThis service updates the LDAP keystore file with the certificate provided.
This is an admin web service.
Query Parameters
N/A
Sample Request
Put LDAP certificate in the keystore file.
PUT http://host/cloud/api/configuration/ldapCert
File: C:\Users\IBM_ADMIN\Documents\abcd.cer
Content-Type: application/binary
Sample Response
HTTP Status: 200
Cloud management servicesUse the services that are listed to work with clouds.Related information:“Code license and disclaimer information” on page 208
GET /clouds/certificateUse this service to get the SSL certificate based on the cloud group configuration.
You can apply the GET/clouds/certificate service to view a certificate before you accept the certificate fora cloud group.
Query Parameters
hostnameThe host name of the cloud group.
portThe cloud group port.
Sample Request
GET http://host/cloud/api/clouds/certificate?hostname=hostname&port=port
For example, the hostname can be the IP address of iaasgateway and the port can be the port ofiaasgateway(9973).
Sample Response
HTTP Status: 200
HTTP Response Body:
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 37
{-"md5Fingerprint": "BB:1A:9A:22:D7:99:C1:D0:C4:2A:17:32:59:BB:F7:DF",-"validFrom": 1331063224000,-"issuedTo": "www.ibm.com",-"trusted": false,-"validTo": 2119981624000,-"issuer": "www.ibm.com, STG, IBM, Austin, TX, US",-"subject": "www.ibm.com, STG, IBM, Austin, TX, US",-"serialNumber": "4F:56:69:B8",-"sha1Fingerprint": "C1:D0:1A:98:92:44:5B:E8:A0:52:5B:A9:E2:B9:CC:18:3A:EB:36:46"
}
POST /cloudsUse this service to create cloud connections that are based on the provided cloud configurationinformation.
By default, this service trusts the SSL certificate from the cloud provider. If you specify cloud names thatare not unique, the creation of the cloud connections fails.
Query Parameters
testThe test parameter is set to false by default. To allow clients to test the cloud configuration, changethe value to true. When the value is set to true and clients are testing the cloud connection, the SSLcertificate is always trusted.
trustSpecifies whether to trust the SSL certificate. By default, the POST /clouds service always trusts thecertificate.
Sample Request 1: VMware cloud
Create a VMware cloud from the configuration.POST http://host/cloud/api/clouds{
"name":"vmware-120","description":"vmware-120","hostname":"9.111.222.333","username":"root","password":"vmware","cloudType":"VMware"
}
Sample Response 1
HTTP Status: 201 Created
HTTP Response Body:Location Header : http://host/cloud/api/clouds/1253{
"timeout":600,"isComplete":true,"hostname":"9.125.13.120","isJmsSSL":false,"username":"root","name":"vmware-120","id":"1253","uri":"http://localhost:18080/cloud/api/clouds/1253","description":"vmware-120","cloudType":"VMware”
}
38 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
Sample Request 2: Openstack cloud
Create an Openstack cloud from the configuration. The first example is appropriate is you use theRabbitMQ messaging service.POST http://host/cloud/api/clouds{
"name":"Test Cloud","description":"Openstack Test Cloud","hostname":hostname,"password":"qpidclient","cloudType":"OpenStack","regionName":"RegionOne","port":5671,"qpidUsername":"qpidclient","qpidPassword":"qpidclient","mqType":"RABBIT","virtualHost":"/","sslEnabled":"true","tenantName":"Public","timeout":"600"
}
The next example is appropriate if you use the Qpid messaging service.{
"name":"Test Cloud","description":"Openstack Test Cloud","hostname":hostname,"password":"qpidclient","cloudType":"OpenStack","regionName":"RegionOne","port":5671,"qpidUsername":"qpidclient","qpidPassword":"qpidclient","mqType":"QPID","sslEnabled":"true","tenantName":"Public","timeout":"600"
}
Sample Response 2
HTTP Status: 201 – Created
HTTP Response Body:for ’RABBIT’:Location Header : http://host/cloud/api/clouds/1753{
"name":"Test Cloud","description":"Openstack Test Cloud","timeout":600, "port":9973,"isComplete":true,"isJmsSSL":false,"uri":"http://localhost:18080/cloud/api/clouds/1753","cloudType":"OpenStack","qpidUsername":"qpidclient","mqType":"RABBIT","virtualHost":"/","hostname":"10.1.0.49","tenantName":"Public","sslEnabled":true,"username":"sceagent","id":"1753"
}
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 39
for ’QPID’ :{
"name":"Test Cloud","description":"Openstack Test Cloud","timeout":600, "port":9973,"isComplete":true,"isJmsSSL":false,"uri":"http://localhost:18080/cloud/api/clouds/1753","cloudType":"OpenStack","qpidUsername":"qpidclient","mqType":"QPID","hostname":"10.1.0.49","tenantName":"Public","sslEnabled":true,"username":"sceagent","id":"1753"
}
DELETE /clouds/{id}This service is used to remove a cloud from management.
All appliances and workloads that are associated with the cloud are removed. The cloud is removed as amanaged cloud. Additionally, all information that is associated with the cloud, such as deployment andnetwork properties, is lost.
Query Parameters
N/A
Sample Request
Delete a cloud:
DELETE http://host/cloud/api/clouds/123
Sample Response
HTTP Status: 200 success
GET /cloudsThis service is used to view the status of the current clouds that are being managed.
Query Parameters
N/A
Sample Request
Get the configuration information and status of all clouds:
GET http://host/cloud/api/clouds
Sample Response
HTTP Status: 200 success{
"clouds":[{
40 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
"timeout":600,"state":{
"label":"OK","id":"OK"
},"isComplete":true,"hostname":"9.111.222.333","isJmsSSL":false,"username":"root","type":"VMware","name":"vmware-120","id":"1253","description":"vmware-120","uri":"http://localhost:18080/cloud/api/clouds/1253"
},{"port": 5671,"isComplete": true,"cloudType": "OpenStack","regionName": "regionOne","state": {
"id": "OK","label": "OK"
},"hostname": "10.1.0.81","qpidUsername": "qpidclient","uri": "http://10.1.0.81:18080/cloud/api/clouds/352","tenantName": "Public","id": "352","sslEnabled": true,"username": "sceagent","description": "","name": "os","isJmsSSL": false,"timeout": 300
}]
}
GET /clouds/{id}Use this service to view the status of a single cloud that is being managed.
Query Parameters
N/A
Sample Request
Get the configuration information and status of a single cloud:
GET http://host/cloud/api/clouds/{id}
Sample Response
HTTP Status: 200 success{
"port": 5671,"isComplete": true,"cloudType": "OpenStack","regionName": "regionOne","state": {
"id": "OK","label": "OK"
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 41
},"hostname": "10.1.0.81","qpidUsername": "qpidclient","uri": "http://10.1.0.81:18080/cloud/api/clouds/352","tenantName": "Public","id": "352","sslEnabled": true,"username": "sceagent","description": "","name": "os","isJmsSSL": false,"timeout": 300
}
GET /clouds?typesThis service retrieves the supported cloud types.
Query Parameters
N/A
Sample Request
Get the supported cloud types:
GET http://host/cloud/api/clouds?types=true
Sample Response
HTTP Status: 200 success{
"cloudTypes": [{
"versions": [],"type": "OpenStack"
},{
"versions": [],"type": "VMware"
}],"uri": "http://10.1.0.81:18080/cloud/api/clouds"
}
GET /clouds/{id}/certificateThis service is used to get the SSL certificate for the cloud.
Query Parameters
N/A
Sample Request
GET http://host/cloud/api/clouds/{id}/certificate
Sample Response
HTTP Status: 200 success
42 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
{"md5Fingerprint":"30:1E:7E:67:B8:E4:CD:D9:97:26:DF:7D:47:2C:24:E9","validFrom":1223274478000,"issuedTo":"www.ibm.com","trusted":true,"validTo":2000874478000,"issuer":"www.ibm.com, , IBM, US","subject":"www.ibm.com, IBM, US","serialNumber":"44:EE:AF:EE","sha1Fingerprint":"2C:A4:C8:AA:73:05:45:A8:94:B1:73:F4:FE:21:F6:17:C2:FE:01:05"
}
PUT /clouds/{id}This service is used to update the cloud configuration and the cloud connection that is based on theprovided cloud configuration information.
By default, this service trusts the SSL certificate from the cloud provider.
Query Parameters
testDefault value for this parameter is false. This gives the clients of the service the option to test thecloud configuration. By default, the SSL certificate is always trusted when testing the cloudconnection.
Note: When you have an existing connection, testing the connection is not supported. Use the testparameter only when you do not have a valid connection and want to test the new configuration.
trustSpecifies whether to trust the SSL certificate. By default, this service always trusts the certificate. Thisparameter also controls whether to trust the cloud connection. You might choose not to trust theconnection if something about the cloud configuration has changed.
Sample Request 1
Update the cloud name and description.PUT http://host/cloud/api/clouds/{id}{"name":"Test Cloud Changed","description":"Test OpenStack Cloud Changed."}
Sample Response 1
HTTP Status: 200 success
Sample Request 2
Untrust the current cloud connection and certificate.PUT http://host/cloud/api/clouds/{id}?trust=false
Sample Response 2
HTTP Status: 200 success
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 43
Delinquency policies servicesIBM Cloud Manager with OpenStack provides services for managing delinquency policies.Related information:“Code license and disclaimer information” on page 208
GET /billing/delinquencyPoliciesThis service retrieves all the delinquency policies that are defined within IBM Cloud Manager withOpenStack.
Sample Request
GET http://host/cloud/api/billing/delinquencyPolicies
No HTTP body required.
Sample Response
HTTP Status: 200
HTTP Response Body:{
"delinquencyPolicies":[{
"name":"Shutdown deployments","id":"com.ibm.cfs.services.billing.policies.shutdown","uri":"http://localhost:18080/cloud/api/billing/delinquencyPolicies/com.ibm.cfs.services.billing.policies.shutdown"
},{
"name":"Destroy deployments","id":"com.ibm.cfs.services.billing.policies.destroy","uri":"http://localhost:18080/cloud/api/billing/delinquencyPolicies/com.ibm.cfs.services.billing.policies.destroy"
},{
"name":"Do nothing","id":"com.ibm.cfs.services.billing.policies.do.nothing","uri":"http://localhost:18080/cloud/api/billing/delinquencyPolicies/com.ibm.cfs.services.billing.policies.do.nothing"
}]
}
GET /billing/delinquencyPolicies/{id}This service retrieves the properties of a specific delinquency policy by id.
Sample Request
GET http://host/cloud/api/delinquencyPolicies/com.ibm.cfs.services.billing.policies.shutdown
No HTTP body required.
Sample Response
HTTP Status: 200
HTTP Response Body:{
"name":"Shutdown deployments","id":"com.ibm.cfs.services.billing.policies.shutdown","uri":"http://localhost:18080/cloud/api/billing/delinquencyPolicies/com.ibm.cfs.services.billing.policies.shutdown"
}
44 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
Event servicesIBM Cloud Manager with OpenStack provides the following services for events.Related information:“Code license and disclaimer information” on page 208
DELETE /eventsThis service clears event messages by a specified combination of conditions.
Query Parameters
Name Description Default Required
severity String of form severity=(INFO,WARNING,SEVERE).Represents query by event severity. The severity maybe a combination of values, such as any of thefollowing:
v severity=INFO,SEVERE
v severity=INFO,WARNING
v severity=SEVERE,WARNING
v severity=INFO,SEVERE,WARNING
null No
startTime This is a timestamp that is used to specify a startingtimeframe for events returned. Events that occur beforethis timestamp are not returned. The startTime andendTime can be used together or alone to specify atimeframe for the events returned. This value is atimestamp that is the number of milliseconds sinceJanuary 1, 1970, 00:00:00 GMT.
null No
endTime This is a timestamp that is used to specify an endingtimeframe for events returned. Events that occur afterthis timestamp are not returned. The startTime andendTime can be used together or alone to specify atimeframe for the events returned. This value is atimestamp that is the number of milliseconds sinceJanuary 1, 1970, 00:00:00 GMT.
null Yes
Sample Request
To remove events with combination of conditions:
DELETE http://host/cloud/api/events?startTime=1341734400000&endTime=1341907199000&severity=INFO,WARNING
Sample Response
HTTP Status: 200 if successful
GET /eventsThis service retrieves a list of events for the current user.
The current user is defined in the request header cookie savedUserId, therefore callers must ensure thatset this cookie specifies the user for which to retrieve events. The events that are retrieved are indescending order.
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 45
The API current provides the following resource types for event messages (that is, the type in an elementof the resources array); cloudConfiguration, workload, deploymentTarget, appliance, project, user, andvirtualServer.
Query Parameters
Name Description Default Required
start This is the index of the first record that is returnedfrom the database must >=0 and Integer
1 No
count This is the number of records to return after the "start"parameter record, must >0 and Integer.
20 No
all If true, then all known events are retrieved for the user. false No
originator String of form originator=admin or originator=rykal,and represents query by event originator.
null No
severity String of form severity=(INFO,WARNING,SEVERE).Represents query by event severity
null No
participants String of form /participants=USER:nate,sue;PROJECT:1.Both the Type and ids are required.
null No
startTime This is a timestamp that is used to specify a startingtimeframe for events returned. Events that occur beforethis timestamp are not returned. The startTime andendTime can be used together or alone to specify atimeframe for the events returned. This value is atimestamp that is the number of milliseconds sinceJanuary 1, 1970, 00:00:00 GMT.
null No
endTime This is a timestamp that is used to specify an endingtimeframe for events returned. Events that occur afterthis timestamp are not returned. The startTime andendTime can be used together or alone to specify atimeframe for the events returned. This value is atimestamp that is the number of milliseconds sinceJanuary 1, 1970, 00:00:00 GMT.
null No
order This is the order that is used to specify the orderdirection for the events returned. Order can bedescending (desc) or ascending (asc).
desc No
sortBy This the sorting column that is used to retrieve theevents.
timestamp No
Sample Request
GET http://host/cloud/api/events
No HTTP body required.
Sample Response
HTTP Status: 200
HTTP Response Body:{
"events":[{
"resources":[{
46 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
"type":"USER","id":"test","name":"test"
}],
"timestamp":"1302153806444","message":"User ${0} was created.","id":"404","uri":"http://localhost:18080/cloud/api/events/404","originator":"SKC Administrator","severity":{
"label":"Info","id":"INFO"
}},{
"resources":[{
"type":"APPLIANCE","id":"102","name":"MyApp on AIX Image (dual-NIC)"
}],
"timestamp":"1302149649132","message":"New appliance ${0} discovered in cloud.","id":"403","uri":"http://localhost:18080/cloud/api/events/403","originator":"System","severity":{
"label":"Info","id":"INFO"
}},{
"resources":[{
"type":"APPLIANCE","id":"101","name":"MyApp on SUSE Image"
}],
"timestamp":"1302149648960","message":"New appliance ${0} discovered in cloud.","id":"402","uri":"http://localhost:18080/cloud/api/events/402","originator":"System","severity":{
"label":"Info","id":"INFO"
}},{
"resources":[{
"type":"WORKLOAD","id":"251","name":"Workload 1"
}],
"timestamp":"1302149648054","message":"New workload ${0} discovered in cloud.","id":"401","uri":"http://localhost:18080/cloud/api/events/401","originator":"System","severity":{
"label":"Info","id":"INFO"
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 47
}}
],"total":"46"
}
GET /events/eventcsvThis service exports the events that are retrieved for the current user with specified conditions. Theexported file is in comma-separated value (CSV) format.
Query Parameters
Name Description Default Required
severity String of form severity=(INFO,WARNING,SEVERE).Represents query by event severity. The severity mightbe a combination of values, such as any of thefollowing:
v severity=INFO,SEVERE
v severity=INFO,WARNING
v severity=SEVERE,WARNING
v severity=INFO,SEVERE,WARNING
null No
startTime This is a timestamp that is used to specify a startingtimeframe for events returned. Events that occur beforethis timestamp are not returned. The startTime andendTime can be used together or alone to specify atimeframe for the events returned. This value is atimestamp that is the number of milliseconds sinceJanuary 1, 1970, 00:00:00 GMT.
null No
endTime This is a timestamp that is used to specify an endingtimeframe for events returned. Events that occur afterthis timestamp are not returned. The startTime andendTime can be used together or alone to specify atimeframe for the events returned. This value is atimestamp that is the number of milliseconds sinceJanuary 1, 1970, 00:00:00 GMT.
null Yes
Sample Request
To export file of events that query with combination of conditions:
GET http://host/cloud/api/events/eventcsv?startTime=1341734400000&endTime=1341907199000&severity=INFO,WARNING
Sample Response
HTTP Status: 200 if successful
This service creates a new CSV file and exports it to the serverhome/.skc/archives directory. The nameof the file includes events_, and the file is timestamped with the creation date. Columns included in theCSV file include EventID, Event, Severity, Originator, Time.
GET /events/{id}This service retrieves an event by its ID.
This service can be used by callers if they know a specific event id to retrieve.
48 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
Query Parameters
N/A
Sample Request
GET http://host/cloud/api/events/105
No HTTP body required.
Sample Response
HTTP Status: 200
HTTP Response Body:{
"id": "404","message": "!user.created!","resources": [
{"type": "USER","id": "test","name": "test"
}],
"severity": {"id": "INFO","label": "Info"
},"timestamp": "1302153806444","uri": "http://localhost:18080/cloud/api/events/404"
}
Expiration policy servicesThe IBM Cloud Manager with OpenStack product provides the following expiration policy services.Related information:“Code license and disclaimer information” on page 208
GET /expirationPoliciesThis service gets the expiration policies.
Query Parameters
N/A
Sample Request
Retrieve all the expiration policies.
GET http://host/cloud/api/expirationPolicies
No HTTP body required.
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 49
Sample Response
HTTP Status: 200
HTTP Response Body:{
"expirationPolicies": [{
"notificationFrequency": 3,"maxExpirationPeriod": 30,"deleteAfterGrace": true,"notificationStart": 14,"gracePeriod": 0,"id": "51","enableExtension": true,"maxExtensionPeriod": 30,"maxExpirationPeriodWithoutSetting": 1825,"ownerType": "project","workloadExpirationSettingAppliable": false,"ownerId": "1"
},{
"notificationFrequency": 3,"maxExpirationPeriod": 30,"deleteAfterGrace": true,"notificationStart": 14,"gracePeriod": 0,"id": "52","enableExtension": true,"maxExtensionPeriod": 30,"maxExpirationPeriodWithoutSetting": 1825,"ownerType": "project","workloadExpirationSettingAppliable": false,"ownerId": "2"
}]
}
PUT /expirationPolicyThis service updates the properties of the default expiration policy.
Query Parameters
N/A
Sample Request
Update the properties of the default expiration policy.
PUT http://host/cloud/api/expirationPolicy{
"id" :"701","notificationFrequency":3,"notificationStart",14,"maxExpirationPeriod":30,"maxExpirationPeriodWithoutSetting":1825,"maxExtensionPeriod":30,"gracePeriod" :30,"workloadExpirationSettingAppliable":false,"enableExtension":true,"deleteAfterGrace":false
}
50 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
Sample Response
HTTP Status: 200
GET /expirationPolicy/{id}This service retrieves expiration policy by the expiration policy id.
Query Parameters
N/A
Sample Request
GET http://host/cloud/api/expirationPolicies/52
No HTTP body required.
Sample Response
HTTP Status: 200
HTTP Response Body:{
"notificationFrequency": 3,"maxExpirationPeriod": 30,"deleteAfterGrace": true,"notificationStart": 14,"gracePeriod": 0,"id": "52","enableExtension": true,"maxExtensionPeriod": 30,"maxExpirationPeriodWithoutSetting": 1825,"ownerType": "project","workloadExpirationSettingAppliable": false,"ownerId": "2"
}
PUT /expirationPolicy/{id}This service updates the expiration policy identified by the expiration policy id.
Query Parameters
N/A
Sample Request
PUT http://host/cloud/api/expirationPolicies/52
HTTP Request Body:{
"notificationFrequency": 5,"maxExpirationPeriod": 30,"deleteAfterGrace": true,"notificationStart": 14,"gracePeriod": 0,"enableExtension": true,"maxExtensionPeriod": 30,
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 51
"maxExpirationPeriodWithoutSetting": 1825,"workloadExpirationSettingAppliable": true
}
Sample Response
HTTP Status: 200
HTTP Response Body:{
"notificationFrequency": 5,"maxExpirationPeriod": 30,"deleteAfterGrace": true,"notificationStart": 14,"gracePeriod": 0,"id": "52","enableExtension": true,"maxExtensionPeriod": 30,"maxExpirationPeriodWithoutSetting": 1825,"ownerType": "project","workloadExpirationSettingAppliable": true,"ownerId": "2"
}
GET /projects/{id}/expirationPolicyThis service retrieves the expiration policy of the project.
Query Parameters
N/A
Sample Request
GET http://host/cloud/api/projects/1234/expirationPolicy
No HTTP body required.
Sample Response
HTTP Status: 200
HTTP Response Body:{"notificationFrequency":3,"maxExpirationPeriod":30,"deleteAfterGrace":true,"notificationStart":14,"gracePeriod":0,"id":"52","enableExtension":true,"maxExtensionPeriod":30,"maxExpirationPeriodWithoutSetting":1825,"ownerType":"project","workloadExpirationSettingAppliable":false,"ownerId":"1234"}
52 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
Key pair servicesIBM Cloud Manager with OpenStack provides the following services for key pairs. These functions applyonly to an OpenStack cloud.Related information:“Code license and disclaimer information” on page 208
GET /keypairsThis service retrieves key pairs from the IBM Cloud Manager with OpenStack associated with the requestauthenticated user.
Sample Request
Retrieve a listing of key pairs from the IBM SmartCloud® Entry.
GET http://host/cloud/api/keypairs
No HTTP body required.
Sample Response
HTTP Status: 200
HTTP Response Body:{
"keypairs": [{
"cloudId": "301","fingerprint": "88:c9:d3:fc:75:a3:77:da:2e:bb:54:fe:f5:70:ed:89","publicKey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDToRZemLJB5CwwN0hu9MgU0Mk1Hwbg/C7e+QgP38z8gp
HrBMF3fV7HpQbB3xnkrhr/jo15qk8GPMckZ0DhzkYrXQtdjmNBDESbwCWnJZEhgIYePIqgBQmslhJhl
FZ5ZKTaK6A7xySzFiF1HKFKoYagfTMloPIBAwhQqABuyChIlDOxpvIgaP9l13x8ZKjILGP+5Rrw1dAQqaY6R
QWeFHX2SkXhJawFhOYdmIcukQ7H7bpqASt4IZPMaE3FZcNFieltX71+IU0T1UBd/4Kt7edK0nsK93U1xCWc6
FFazxnPp7i950yClzups91OdSigOVMNB+rTm8zmo02ux8JzJRh/ Generated by Nova\n","name": "test_keypair1","id": "cloud://301/test_keypair1","privateKey": "","uri": "http://9.123.137.54:18080/cloud/api/keypairs/cloud%3A%2F%2F301%2Ftest_keypair1"
},{
"cloudId": "301","fingerprint": "fa:95:ce:90:09:10:d2:5d:43:a9:9d:28:3f:71:9f:aa","publicKey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC702CI0gVq45Hn740s/H5EALv/yhMleCn86XWsuqjy
TIFMOt1Kr23J6DNCPk2stJRpbqNSu4WF2rQyB6rdMXfiLSy3C4zQ/5MJiOV8kFtZHDkjZaXKOYgDZ72UWHEj7
KdDP8J7wFtWYhaHR0Y/SwfCze5hsNMa7/ITzWdsBsb00fRQ+CmVk8xWqMovmjO2aUMagKmXIHssGnCaNuIk060yv
XU06sv8MS8wfYV1y5gzmojkUKKdz34BeTdCfjMTXlqAzQx2yn9j32yBVf2I0/rWyb076Pg5zKG7HUjJc0Q6TbbC2w
NnfWHAv9x4cVyfRTbWubhy9yFqyEOAGV7NedmT Generated by Nova\n","name": "test_keypair2","id": "cloud://301/test_keypair2","privateKey": "","uri": "http://9.123.137.54:18080/cloud/api/keypairs/cloud%3A%2F%2F301%2Ftest_keypair2"
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 53
}]
}
GET /keypairs/{id}This service retrieves the properties for a specific key pair from the IBM Cloud Manager with OpenStack.The key pair ID must be URL encoded.
Query Parameters
N/A
Sample Request
GET http://host/cloud/api/keypairs/cloud%3A%2F%2F301%2Ftest_keypair1
No HTTP body required.
Sample Response
HTTP Status: 200
HTTP Response Body:{
"cloudId": "301","fingerprint": "88:c9:d3:fc:75:a3:77:da:2e:bb:54:fe:f5:70:ed:89","publicKey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDToRZemLJB5CwwN0hu9MgU0Mk1Hwbg/C7e+QgP38z8gp
HrBMF3fV7HpQbB3xnkrhr/jo15qk8GPMckZ0DhzkYrXQtdjmNBDESbwCWnJZEhgIYePIqgBQmslhJhlFZ5ZKTaK6A7xySzFiF1HKFKoYagfTMloPIBAwhQqABuyChIlDOxpvIgaP9l13x8ZKjILGP+5Rrw1dAQqaY6RQWeFHX2SkXhJawFhOYdmIcukQ7H7bpqASt4IZPMaE3FZcNFieltX71+IU0T1UBd/4Kt7edK0nsK93U1xCWc6FFazxnPp7i950yClzups91OdSigOVMNB+rTm8zmo02ux8JzJRh/ Generated by Nova\n",
"name": "test_keypair1","id": "cloud://301/test_keypair1","privateKey": ""
}
POST /keypairsThis service generates or imports a key pair.
Query Parameters
N/A
Sample Request 1
Generate the key pair “test_keypair1”.
POST http://host/cloud/api/keypairs
HTTP Request Body:{
"cloudId": “301”,"name": "test_keypair1"
}
54 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
Sample Response 1
HTTP Status: 201
HTTP Response Body:{
{"cloudId": "301","fingerprint": "88:c9:d3:fc:75:a3:77:da:2e:bb:54:fe:f5:70:ed:89","publicKey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDToRZemLJB5CwwN0hu9MgU0Mk1Hwbg/C7e
+QgP38z8gpHrBMF3fV7HpQbB3xnkrhr/jo15qk8GPMckZ0DhzkYrXQtdjmNBDESbwCWnJZEhgIYePIqgBQmslhJhlFZ5ZKTaK6A7xySzFiF1HKFKoYagfTMloPIBAwhQqABuyChIlDOxpvIgaP9l13x8ZKjILGP+5Rrw1dAQqaY6RQWeFHX2SkXhJawFhOYdmIcukQ7H7bpqASt4IZPMaE3FZcNFieltX71+IU0T1UBd/4Kt7edK0nsK93U1xCWc6FFazxnPp7i950yClzups91OdSigOVMNB+rTm8zmo02ux8JzJRh
/ Generated by Nova\n","name": "test_keypair1","id": "cloud://301/test_keypair1","privateKey": "private key contents"
}}
Sample Request 2
Import the key pair 'test_keypair2'.
POST http://host/cloud/api/keypairs
HTTP Request Body:{
"cloudId": “301”,"name": "test_keypair2","publicKey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDToRZemLJB5CwwN0hu9MgU0Mk1Hwbg/C7e
+QgP38z8gpHrBMF3fV7HpQbB3xnkrhr/jo15qk8GPMckZ0DhzkYrXQtdjmNBDESbwCWnJZEhg
IYePIqgBQmslhJhlFZ5ZKTaK6A7xySzFiF1HKFKoYagfTMloPIBAwhQqABuyChIlDOxpvIgaP9l13x8ZKjILGP
+5Rrw1dAQqaY6RQWeFHX2SkXhJawFhOYdmIcukQ7H7bpqASt4IZPMaE3FZcNFieltX71+IU0T1UBd/
4Kt7edK0nsK93U1xCWc6FFazxnPp7i950yClzups91OdSigOVMNB+rTm8zmo02ux8JzJRh/ Generated by Nova\n"
}
Sample Response 2
HTTP Status: 201
HTTP Response Body:{
{"cloudId": "301","fingerprint": "88:c9:d3:fc:75:a3:77:da:2e:bb:54:fe:f5:70:ed:89","publicKey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDToRZemLJB5CwwN0hu9MgU0Mk1Hwbg/C7e
+QgP38z8gpHrBMF3fV7HpQbB3xnkrhr/jo15qk8GPMckZ0DhzkYrXQtdjmNBDESbwCWnJZEhg
IYePIqgBQmslhJhlFZ5ZKTaK6A7xySzFiF1HKFKoYagfTMloPIBAwhQqABuyChIlDOxpvIgaP9l13x8ZKjILGP
+5Rrw1dAQqaY6RQWeFHX2SkXhJawFhOYdmIcukQ7H7bpqASt4IZPMaE3FZcNFieltX71+IU0T1UBd
/4Kt7edK0nsK93U1xCWc6FFazxnPp7i950yClzups91OdSigOVMNB+rTm8zmo02ux8JzJRh/Generated by Nova\n",
"name": "test_keypair2","id": "cloud://301/test_keypair2"}
}
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 55
License key servicesIBM Cloud Manager with OpenStack provides the following services for license keys.Related information:“Code license and disclaimer information” on page 208
GET /licensingThis service retrieves license key information of IBM Cloud Manager with OpenStack. You must haveAdministrator access to use this API.
Sample Request
Retrieve the license key from IBM Cloud Manager with OpenStack.
GET http://host:port/cloud/api/licensing
No HTTP body required.
Sample Response1. This is a sample response if IBM Cloud Manager with OpenStack is configured with a license key
containing an expiration date.HTTP Status: 200HTTP Response Body:{
"product":"SCE","startDate":"2013-12-13","duration":1084,"expirationDate":"2016-12-01","type":"TRIAL_MODE_EXPIRITION_DATE","leftDays":1081,"version":"4.1.0.0"}
2. This is a sample response if IBM Cloud Manager with OpenStack is configured with a license keycontaining a 90 day trail period.HTTP Status: 200HTTP Response Body:{"product":"SCE","startDate":"2013-12-16","duration":90,"expirationDate":"2014-03-16","type":"TRIAL_MODE_DURATION","leftDays":90,"version":"4.1.0.0"}
3. This is a sample response if IBM Cloud Manager with OpenStack is configured with a permanentlicense key.HTTP Status: 200HTTP Response Body:{"product":"SCE","startDate":"2013-12-16","type":"PERMANENT","version":"4.1.0.0"}
56 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
PUT /licensingThis service updates the license key.
Query Parameters
Iaasgw
Note: This is an optional parameter. The default value is true.
Sample Requestv Sample 1: The administrator needs to update the license key of IBM Cloud Manager with OpenStack
and the IaaS gateway.PUT http://host:port/cloud/api/licensingContent-Type :application/octet-stream Or application/binary,multipart/form-data(for IE9 only)
Sample Response
HTTP Status: 200 OK
Metering data servicesIBM Cloud Manager with OpenStack provides the following services managing metering data.Related information:“Code license and disclaimer information” on page 208
GET /udrfilesThis service gets the directories list containing all metering data (UDR) files.
Sample Request
GET http://host/cloud/api/udrfiles
No HTTP body required.
Sample ResponseHTTP Status: 200 HTTP Response Body:{
"total": 2,"udrfiles": [
{"type": "directory","name": "201101023","uri": "http://localhost:18080/cloud/api/udrfiles/201101023"
},{
"type": "directory","name": "20111111","uri": "http://localhost:18080/cloud/api/udrfiles/20111111"
}]
}
GET /udrfiles/{directoryName}This service retrieves the files list in a specific directory.
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 57
Sample Request
GET http://host/cloud/api/udrfiles/{directoryName}
No HTTP body required.
Sample Response
HTTP Status: 200
HTTP Response Body:{"total": 2,"udrfiles": [
{"type": "file","name": "UDR_20111108010000.csv","uri":"http://localhost:18080/cloud/api/udrfiles/20111023/UDR_20111108010000.csv"
},{
"type": "file","name": "UDR_20111108010000.csv.digest","uri":"http://localhost:18080/cloud/api/udrfiles/20111023/UDR_20111108010000.csv.digest"
}]
}
GET /udrfiles/{directoryName}/{fileName}This service retrieves the file of specific file name.
Sample Request
GET http://host/cloud/api/udrfiles/{directoryName}/{fileName}
No HTTP body required.
Sample Response
HTTP Status: 200
HTTP Response Body: The specific file according the file name.
GET /udrsThis service gets all the universal data records (UDRs) for metering data.
Sample Request
GET http://host/cloud/api/udrs
No HTTP body required.
Query Parameters
Name Description Default Required
userId Gets the UDRs that can beviewed by this userId.
N/A No
globalObjectId Gets the UDRs for thespecified globalObjectId.
N/A No
58 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
Name Description Default Required
cloudId Gets the UDRs for thespecified cloudId.
N/A No
objectType Gets the UDRs for thespecified objectType.
N/A No
objectId Gets the UDRs for thespecified objectId.
N/A No
projectId Gets the UDRs the specifiedprojectId.
N/A No
architecture Gets the UDRs for thespecified architecture.
N/A No
hypervisor Gets the UDRs for thespecified hypervisor.
N/A No
startTime Gets the UDRs for whichthe start time is afterspecified value.
N/A No
endTime Gets the UDRs for whichthe end time is after thespecified value.
Now No
start This is the index of the firstrecord that will be returnedfrom the database. Thevalue must be an integergreater than zero.
0 No
count This is the number ofrecords to return after the"start" parameter record.The value must be aninteger greater than zero.
1000 No
sortBy This parameter supportsobjectName, projectName,userId, startTime, andcloudName. Caseinsensitive.
startTime No
order Specify order withascending or descending.Parameter can be set todesc or asc.
desc No
cloudName Gets the UDRs for thespecified cloudName.
N/A No
Sample Response
HTTP Status: 200
HTTP Response Body{
"total": 2,"udrs": [
{"cloudId": "352","cloudType": "OpenStack","resourceValues": {
"MEMORY": 1-24,"DISK": 50,
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 59
"CPU": 1},"meteringInterval": 1,"endTime": 1398277549561,"uri": "http://10.1.0.81:18080/cloud/api/udrs/1405","cloudName": "os","id": "1405","startTime": 1398191275553,"identifierValues": {
"objectName": "instance-00000004","hypervisor": "KVM","IP": "","state": {
"id": "UNKNOWN","label": "Unknown"
},"workloadName": "kvm2","projectId": "51","architecture": "x86","projectName": "Public","workloadId": "1302"
},"objectId": "1352","userId": "admin","globalObjectId": "cloud://352/8c62c2f3-ee0a-44d8-8741-4d35fb127b13","objectType": "virtual machine"
},{
"cloudId": "352","cloudType": "OpenStack","resourceValues": {
"MEMORY": 2048,"DISK": 100,"CPU": 2
},"meteringInterval": 1,"endTime": 1398277549561,"uri": "http://10.1.0.81:18080/cloud/api/udrs/1404","cloudName": "os","id": "1404","startTime": 1398183721134,"identifierValues": {
"objectName": "instance-00000005","hypervisor": "KVM","IP": "11.1.1.4","state": {
"id": "RUNNING","label": "Running"
},"workloadName": "kvm-test1","projectId": "51","architecture": "x86","projectName": "Public","workloadId": "1303"
},"objectId": "1353","userId": "admin","globalObjectId": "cloud://352/83b93226-626d-46b5-befb-ae91f4b16a07","objectType": "virtual machine"
},],"uri": "http://10.1.0.81:18080/cloud/api/udrs"
}
GET /udrs/{id}This service retrieves the UDR with the udrId.
Sample Request
GET http://host/cloud/api/udrs/{id}
No HTTP body required.
60 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
Sample Response
HTTP Status: 200
HTTP Response Body:{
"resourceValues": {"MEMORY": 1024,"CPU": 0.5,"DISK": 5120
},"cloudId": "352","cloudName": "OSCloud","cloudType": "OpenStack","userId": "","endTime": "0","objectType": "virtual machine","objectId": "751","identifierValues": {
"state": {"id": "RUNNING","label": "RUNNING"
},"workloadName": "naj_1202","workloadId": "701","architecture": "x86","projectName": "Public","projectId": "151","hypervisor": "KVM","objectName": "naj-1202-192-168-128-15"
},"id": "952","uri": "http://localhost:18080/cloud/api/udrs/952","globalObjectId": "cloud://default/13227","meteringInterval": 1,"startTime": "20140402 13:12:35"
}
Network configuration servicesWork with your network configuration using the services described here.Related information:“Code license and disclaimer information” on page 208
GET /networkConfigurationsThis service retrieves all network configurations.
Network configurations are used to automatically provide IP addresses, host names, DNS, gatewayaddresses, subnet masks, domain suffix search list, DHCP setting, and WINS addresses for workloads. Anappliance can be configured to use a network configuration from an existing network configuration upondeployment.
This is an admin web service.
Query Parameters
cloudGroupId (optional)Filters network configuration by cloudGroupId. Returns the network configurations that are validfor the specified cloudGroupId. If you specify * for the cloudGroupId, all network configurationsare returned.
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 61
Sample Request
GET http://localhost:18080/cloud/api/networkConfigurations
No HTTP body required.
Sample Response
Note: The IPv6 related fields are returned only when there is an IPv6 subnet configured in this network.
HTTP Status: 200
HTTP Response Body:{"networkConfigurations": [{"domainSuffixes": {"value": "","label": "Domain suffix search list"},"ipAddressPoolUri": "http://localhost:18080/cloud/api/networkConfigurations/151/ipAddresses","blockedCount": 0,"freeCount": 41,"domain": {"value": "private.cloud.com","label": "Domain name"},"hostnamePrefix": {"value": "sce","label": "Host name prefix"},"dns1": {"value": "203.0.113.100","label": "DNS 1"},"networkId": {"value": "","label": "Network ID"},"dns2": {"value": "203.0.113.200","label": "DNS 2"},"name": "Default","uri": "http://localhost:18080/cloud/api/networkConfigurations/151","gateway1": {"value": "192.0.2.1","label": "Gateway address"},"gateway2": {"value": "","label": "Alternate gateway address"},"workgroup": {"value": "WORKGROUP","label": "Workgroup"},"usedCount": 0,"isDefault": false,"useDHCP": {"value": false,
62 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
"label": "Use DHCP"},"computerNamePrefix": {"value": "sce","label": "Computer name prefix"},"wins1": {"value": "203.0.113.40","label": "Primary WINS address"},"obtainFromDNS": {"value": false,"label": "Obtain hostname and domain name from DNS server"},"id": "151","wins2": {"value": "203.0.113.140","label": "Secondary WINS address"},"description": "Default Network Configuration","subnet": {"value": "255.255.255.0","label": "Subnet mask"}},{"cloudGroupUri": "http://localhost:18080/cloud/api/clouds/306","ipAddressPoolUri": "http://localhost:18080/cloud/api/networkConfigurations/2052/ipAddresses","blockedCount": 0,"freeCount": -1,"hostnamePrefix": {"value": "sce","label": "Host name prefix"},"cloudGroupId": "306","networkId": {"value": "VM Network","label": "Network ID"},"name": "DHCP","uri": "http://localhost:18080/cloud/api/networkConfigurations/2052","workgroup": {"value": "WORKGROUP","label": "Workgroup"},"cloudType": "VMware","usedCount": -1,"cloudGroupName": "vCenter10","isDefault": false,"useDHCP": {"value": true,"label": "Use DHCP"},"computerNamePrefix": {"value": "sce","label": "Computer name prefix"},"obtainFromDNS": {"value": false,"label": "Obtain hostname and domain name from DNS server"},"id": "2052","description": "Sample DHCP configuration",
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 63
"subnet": {"value": "255.255.255.0","label": "Subnet mask"}},{"cloudGroupUri": "http://localhost:18080/cloud/api/clouds/304","blockedCount": 0,"freeCount": 253,"cloudGroupId": "304","networkType": {"value": "vlan","label": "Network type"},"name": "VLAN50","cloudType": "OpenStack","usedCount": 0,"physicalNetwork": {"value": "default","label": "Physical network"},"endAllocation": {"value": "192.168.50.254","label": "IP allocation pool end address"},"id": "304_6c72f74b-f335-4aef-bb23-9afcd89341a4","blockedIpv6Count": 0,"freeIpv6Count": 253,"ipv6Gateway": {"value": "2001:db8::192:168:50:1","label": "IPv6 gateway address"},"subnet": {"value": "255.255.255.0","label": "Subnet mask"},"vlanId": {"value": 50,"label": "VLAN id"},"ipv6PrefixLength": {"value": "120","label": "IPv6 prefix length"},"startAllocation": {"value": "192.168.50.2","label": "IP allocation pool start address"},"ipAddressPoolUri": "http://localhost:18080/cloud/api/networkConfigurations/
304_6c72f74b-f335-4aef-bb23-9afcd89341a4/ipAddresses","dns1":{"value": "203.0.113.100","label": "DNS 1"},"dns2": {"value": "203.0.113.200","label": "DNS 2"},"networkId": {"value": "6c72f74b-f335-4aef-bb23-9afcd89341a4","label": "Network ID"},
64 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
"usedIpv6Count": 0,"uri": "http://localhost:18080/cloud/api/networkConfigurations/
304_6c72f74b-f335-4aef-bb23-9afcd89341a4","gateway1": {"value": "192.168.50.1","label": "Gateway address"},"ipv6Dns1": {"value": "2001:db8:0:0:203:0:113:100","label": "IPv6 DNS1"},"ipv6Dns2": {"value": "2001:db8:0:0:203:0:113:200","label": "IPv6 DNS2"},"ipv6EndAllocation": {"value": "2001:db8:0:0:192:168:50:fe","label": "IPv6 IP allocation pool end address"},"cloudGroupName": "OpenStack","isDefault": false,"useDHCP": {"value": false,"label": "Use DHCP"},"useDHCPv6": {"value": false,"label": "Use IPv6 DHCP"},"obtainFromDNS": {"value": false,"label": "Obtain hostname and domain name from DNS server"},"ipv6StartAllocation": "2001:db8:0:0:192:168:50:2"} ]}
The query response might include cloudGroupUri, cloudGroupId, and cloudGroupName or include none ofthe three if the networkConfiguration does not belong to any cloud groups.
POST /networkConfigurationsThis service adds a network configuration.
Network configuration names must be unique. If a new network configuration name conflicts with anexisting network configuration name, the service responds with a 400 status code. You can also specifysome IP addresses when you create a network configuration.
This is an admin web service.
Sample Request 1
Add a network configuration named Sample Network Configuration without a cloudGroupId:
POST http://host/cloud/api/networkConfigurations
HTTP Request Body:{
"name":"Sample Network Configuration","description":"Sample network configuration","networkId":"VM Network",
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 65
"gateway1":"192.168.1.1","subnet":"255.255.255.0","dns1":"203.0.113.100","domain":"private.cloud.com"
}
Sample Response 1
HTTP Status: 201
HTTP Location: URL of the new network configuration
HTTP Response Body:{"ipAddressPoolUri": "http://localhost:18080/cloud/api/networkConfigurations/2053/ipAddresses","blockedCount": 0,"freeCount": 0,"domain": {"value": "private.cloud.com","label": "Domain name"},"dns1": {"value": "203.0.113.100","label": "DNS 1"},"networkId": {"value": "VM Network","label": "Network ID"},"name": "Sample Network Configuration","uri": "http://localhost:18080/cloud/api/networkConfigurations/2053","gateway1": {"value": "192.168.1.1","label": "Gateway address"},"usedCount": 0,"isDefault": false,"useDHCP": {"value": false,"label": "Use DHCP"},"obtainFromDNS": {"value": false,"label": "Obtain hostname and domain name from DNS server"},"id": "2053","description": "Sample network configuration","subnet": {"value": "255.255.255.0","label": "Subnet mask"}
Sample Request 2
Add a network configuration for OpenStack Cloud named OpenStack VLAN10 with a cloudGroupId of 304:
POST http://host/cloud/api/networkConfigurations
HTTP Request Body:{
"name":"OpenStack VLAN10","cloudGroupId":"304","networkType":"vlan","physicalNetwork":"default","vlanId":10,"gateway1":"192.168.10.1","subnet":"255.255.255.0","startAllocation":"192.168.10.2","endAllocation":"192.168.10.254","dns1":"203.0.113.100","ipv6Gateway":"2001:db8:0:0:192:168:10:1",
66 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
"ipv6PrefixLength":"120","ipv6StartAllocation":"2001:db8:0:0:192:168:10:2","ipv6EndAllocation":"2001:db8:0:0:192:168:10:fe"
}
Sample Response 2{"cloudGroupUri": "http://localhost:18080/cloud/api/clouds/304","freeCount": 253,"blockedCount": 0,"cloudGroupId": "304","networkType": {"value": "vlan","label": "Network type"},"name": "OpenStack VLAN10","cloudType": "OpenStack","usedCount": 0,"physicalNetwork": {"value": "default","label": "Physical network"},"id": "304_b45cd4b5-c4d8-4836-99de-e97e63c3366a","endAllocation": {"value": "192.168.10.254","label": "IP allocation pool end address"},"freeIpv6Count": 253,"blockedIpv6Count": 0,"ipv6Gateway": {"value": "2001:db8:0:0:192:168:10:1","label": "IPv6 gateway address"},"subnet": {"value": "255.255.255.0","label": "Subnet mask"},"vlanId": {"value": 10,"label": "VLAN id"},"ipv6PrefixLength": {"value": "120","label": "IPv6 prefix length"},"startAllocation": {"value": "192.168.10.2","label": "IP allocation pool start address"},"ipAddressPoolUri": "http://localhost:18080/cloud/api/networkConfigurations/
304_b45cd4b5-c4d8-4836-99de-e97e63c3366a/ipAddresses", "dns1": {"value": "203.0.113.100","label": "DNS 1"},"networkId": {"value": "b45cd4b5-c4d8-4836-99de-e97e63c3366a","label": "Network ID"},"usedIpv6Count": 0,"uri": "http://localhost:18080/cloud/api/networkConfigurations/
304_b45cd4b5-c4d8-4836-99de-e97e63c3366a","gateway1": {"value": "192.168.10.1","label": "Gateway address"},"ipv6EndAllocation": {"value": "2001:db8:0:0:192:168:10:fe","label": "IPv6 IP allocation pool end address"},"cloudGroupName": "OpenStack","isDefault": false,
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 67
"useDHCPv6": {"value": false,"label": "Use IPv6 DHCP"},"useDHCP": {"value": false,"label": "Use DHCP"},"obtainFromDNS": {"value": false,"label": "Obtain hostname and domain name from DNS server"},"ipv6StartAllocation": "2001:db8:0:0:192:168:10:2"}
GET /networkConfigurations/{id}This service retrieves a specific network configuration.
Network configurations are used to automatically provide IP addresses, host names, DNS, gatewayaddresses, subnet masks, domain suffix search list, DHCP setting, and WINS addresses for workloads. Anappliance can be configured to use an existing network configuration upon deployment. This serviceretrieves all known information about a network configuration such as DNS1, DNS2, and gatewayaddresses.
This is an admin web service.
Query Parameters
N/A
Sample Request
GET http://host/cloud/api/networkConfigurations/304_6c72f74b-f335-4aef-bb23-9afcd89341a44
No HTTP body required.
Sample Response
Note: The IPv6 related fields are returned only when there is an IPv6 subnet configured in this network.
HTTP Status: 200
HTTP Response Body:{"cloudGroupUri": "http://localhost:18080/cloud/api/clouds/304","freeCount": 253,"blockedCount": 0,"cloudGroupId": "304","networkType": {"value": "vlan","label": "Network type"},"name": "VLAN50","cloudType": "OpenStack","usedCount": 0,"physicalNetwork": {"value": "default","label": "Physical network"},"id": "304_6c72f74b-f335-4aef-bb23-9afcd89341a4","endAllocation": {"value": "192.168.50.254","label": "IP allocation pool end address"},
68 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
"freeIpv6Count": 253,"blockedIpv6Count": 0,"ipv6Gateway": {"value": "2001:db8::192:168:50:1","label": "IPv6 gateway address"},"subnet": {"value": "255.255.255.0","label": "Subnet mask"},"vlanId": {"value": 50,"label": "VLAN id"},"ipv6PrefixLength": {"value": "120","label": "IPv6 prefix length"},"startAllocation": {"value": "192.168.50.2","label": "IP allocation pool start address"},"ipAddressPoolUri": "http://localhost:18080/cloud/api/
networkConfigurations/304_6c72f74b-f335-4aef-bb23-9afcd89341a4/ipAddresses","dns1": {"value": "203.0.113.100","label": "DNS 1"},"dns2": {"value": "203.0.113.200","label": "DNS 2"},"networkId": {"value": "6c72f74b-f335-4aef-bb23-9afcd89341a4","label": "Network ID"},"usedIpv6Count": 0,"uri": "http://localhost:18080/cloud/api/networkConfigurations/304_6c72f74b-f335-4aef-bb23-9afcd89341a4","gateway1": {"value": "192.168.50.1","label": "Gateway address"},"ipv6Dns1": {"value": "2001:db8:0:0:203:0:113:100","label": "IPv6 DNS1"},"ipv6Dns2": {"value": "2001:db8:0:0:203:0:113:200","label": "IPv6 DNS2"},"ipv6EndAllocation": {"value": "2001:db8:0:0:192:168:50:fe","label": "IPv6 IP allocation pool end address"},"cloudGroupName": "OpenStack","isDefault": false,"useDHCPv6": {"value": false,"label": "Use IPv6 DHCP"},"useDHCP": {"value": false,"label": "Use DHCP"},"obtainFromDNS": {"value": false,"label": "Obtain hostname and domain name from DNS server"},"ipv6StartAllocation": "2001:db8:0:0:192:168:50:2"}
PUT /networkConfigurations/{id}This service updates a new network configuration.
Note: You can update only the following fields in the network configuration for an OpenStack cloud:v name
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 69
v gateway1v dns1v dns2v ipv6Gatewayv ipv6Dns1v ipv6Dns2
In the OpenStack cloud network configuration, the order of the values for dns1 and dns2 might changeafter the values are updated.
Network configurations names must be unique. If a new network configuration name conflicts with anexisting network configuration name, the service responds with a 400 status code.
This is an admin web service.
Sample Request
Update a network configuration named specified by id 2053:
PUT http://host/cloud/api/networkConfigurations/2053
HTTP Request Body:{
"name":"Sample Network Configuration - Renamed","description":"Sample network configuration - Description renamed","gateway1":"192.168.1.254","dns1":"203.0.113.101","dns2":"203.0.113.102","wins1":"203.0.113.103","wins2":"203.0.113.104"
}
Sample Response
HTTP Status: 200
The response might include cloudGroupUri, cloudGroupId, and cloudGroupName or include none of thethree if the networkConfiguration does not belong to any cloud groups.
DELETE /networkConfigurations/{id}This service removes an existing network configuration and all of the IP addresses that it manages.
If the network configuration to delete still has IP addresses in use, a 500 response is returned. Onlynetwork configurations with no used IP addresses can be deleted.
This is an admin web service.
Query Parameters
N/A
Sample Request
Remove the network configuration with ID 2053
DELETE http://host/cloud/api/networkConfigurations/2053
70 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
Sample Response
HTTP Status: 200
GET /networkConfigurations/{id}/ipAddressesThis service retrieves all known managed IP addresses in a network configuration.
A managed IP address is either “used” or “unused” as indicated by the IP addresses “isUsed” value, and“blocked” and “unblocked” is indicated by “'isBlocked'”. If an IP address is free, it is available for use ina workload.
This is an admin web service.
Query Parameters
Name Description Default Required
used The IP addresses retrievedshould all be unused.
false No
start The index of the first itemthat is returned. Must be ≥0 and an integer.
0 No
count The number of items thatare returned. Must be ≥ 0and an integer. 0 = all itemsafter starting index.
0 No
isUsed Filter to limit output toonly those records thatmatch the specified value.Must be either true or false.By default, isUsed propertyis not filtered.
* No
isBlocked Filter to limit output toonly those records thatmatch the specified value.Must be either true or false.By default, isBlockedproperty is not filtered.
* No
ipAddress Filter to limit output toonly those records thatmatch the specified value.By default, ipAddressproperty is not filtered.Filters of "." and ":" can beused to limit output to justIPv4 or IPv6 addresses.
* No
Note: The query parameter of isUsed will always override the query parameter of used unless thedefault "*" is specified. For example:
If the following value is specified: The query will return the following:
used = true Only those IP addresses that are in use.
used = false All IP addresses regardless of the isUsed setting.
isUsed = true Only those IP addresses that are in use.
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 71
If the following value is specified: The query will return the following:
isUsed = false Only those IP addresses that are not in use.
inUsed = * All IP addresses.
isUsed = false and used = true IP address that are not in use. isUsed property haspriority.
Sample Request
GET http://host/cloud/api/networkConfigurations/2053/ipAddresses
No HTTP body required.
Sample Response
HTTP Status: 200
HTTP Response Body:{
"ipAddresses":[{
"isBlocked":false,"hostname":"skc-host1","isUsed":false,"uri":"http://localhost:18080/cloud/api/networkConfigurations/2053/ipAddresses/192.168.1.1","ipAddress":"192.168.1.1"
},{
"isBlocked":false,"hostname":"skc-host2","isUsed":false,"uri":"http://localhost:18080/cloud/api/networkConfigurations/2053/ipAddresses/192.168.1.2","ipAddress":"192.168.1.2"
}]
}
POST /networkConfigurations/{id}/ipAddressesThis service adds one or more IP addresses to the network configuration.
Note: This interface is not supported for network configurations in an OpenStack cloud. All IP addressesmust be defined when the OpenStack network configuration is first created.
IP addresses are always created as unused and unblocked so the value of "isUsed" and ''isBlocked'' areignored on a POST service.
If any IP addresses specified to this service are already managed, none of them are added to the pool ofmanaged IP addresses. A 400 response is returned.
To update the "isUsed" or ''isBlocked'' values, use the PUT service.
This is an admin web service.
Query Parameters
N/A
72 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
Sample Requests1. Adding an IP address to the network configuration with ID 2053:
POST http://host/cloud/api/networkConfigurations/2053/ipAddressesHTTP Request Body:{
"ipAddress":"192.168.1.221","hostname":"cfs-221"
}
2. Adding multiple IP addresses to the network configuration with ID 2053:POST http://host/cloud/api/networkConfigurations/2053/ipAddressesHTTP Request Body:[
{"ipAddress":"192.168.1.222","hostname":"cfs-222"
},{
"ipAddress":"9.5.12.223","hostname":"cfs-223"
}]
3. Adding multiple IP addresses in an address range to the network configuration with ID 2053:POST http://host/cloud/api/networkConfigurations/2053/ipAddressesHTTP Request Body:
{"ipAddressRange":{"start":"192.168.1.201","end":"192.168.1.205"}
}
Sample Response
HTTP Status: 201
HTTP Response Body:
Note: The following HTTP response body is specific to sample request 2. The HTTP response body forthe other sample requests is similar.{
"ipAddresses":[{
"isBlocked":false,"hostname":"cfs-222","isUsed":false,"uri":"http://localhost:18080/cloud/api/networkConfigurations/2053/ipAddresses/192.168.1.222","ipAddress":"192.168.1.222"
},{
"isBlocked":false,"hostname":"cfs-223","isUsed":false,"uri":"http://localhost:18080/cloud/api/networkConfigurations/2053/ipAddresses/192.168.1.223","ipAddress":"192.168.1.223"
}]
}
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 73
GET /networkConfigurations/{id}/ipAddresses/{ip}This service retrieves the properties of a specific managed IP address by IP address.
If the “isUsed” and “'isBlocked'” values for the IP address are “false”, the IP is free and available for useby a workload. If the value of either “isUsed” or “isBlocked” is “true”, the IP cannot be used by aworkload.
This is an admin web service.
Query Parameters
N/A
Sample Request
GET http://host/cloud/api/networkConfigurations/2053/ipAddresses/192.168.1.221
No HTTP body required.
Sample Response
HTTP Status: 200
HTTP Response Body:{
"isBlocked":false,"hostname":"cfs-221","isUsed":false,"uri":"http://localhost:18080/cloud/api/networkConfigurations/2053/ipAddresses/192.168.1.221","ipAddress":"192.168.1.221"
}
PUT /networkConfigurations/{id}/ipAddresses/{ip}This service enables updating of an existing managed IP address.
The service is used to mark a managed IP address as blocked so that the IP address cannot be used inworkloads. If the IP address is not in the managed IP pool, a 404 response is returned.
This is an admin web service.
Query Parameters
N/A
Sample Requests1. Set IP address “192.168.1.221”to blocked and host name to “cfs-221-Blocked”
PUT http://host/cloud/api/networkConfigurations/2053/ipAddresses/192.168.1.221{
"isBlocked":true,"hostname":"cfs-221-Blocked"
}
Note: Setting the host name of the IP address is not supported for network configurations in anOpenStack cloud.
2. Set IP addresses "192.168.1.222" and "192.168.1.223" to blocked
74 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
PUT http://host/cloud/api/networkConfigurations/2053/ipAddresses/192.168.1.222,192.168.1.223{
"isBlocked":true}
3. Set IP addresses that range from "192.168.1.201" to ''192.168.1.205'' to blockedPUT http://host/cloud/api/networkConfigurations/2053/ipAddresses/192.168.1.201-192.168.1.205{
"isBlocked":true,}
Sample Response
HTTP Status: 200
DELETE /networkConfigurations/{id}/ipAddresses/{ip}This service removes an existing IP address from the network configuration of managed IP addresses.
Note: This interface is not supported for network configurations in an OpenStack cloud. IP addressescannot be deleted from an OpenStack network configuration.
If the specified IP is not in the network configuration of managed IP addresses, a 404 response isreturned.
This is an admin web service.
Query Parameters
N/A
Sample Requests1. Remove the managed IP address "192.168.1.221" in network configuration with ID 2053.DELETE http://host/cloud/api/networkConfigurations/2053/ipAddresses/192.168.1.221
2. Remove the managed IP addresses "192.168.1.222" and "192.168.1.223"DELETE http://host/cloud/api/networkConfigurations/2053/ipAddresses/192.168.1.222,192.168.1.223
3. Remove the managed IP addresses that range from "192.168.1.201" to ''192.168.1.205''DELETE http://host/cloud/api/networkConfigurations/2053/ipAddresses/192.168.1.201-192.168.1.205
Sample Response
HTTP Status: 200
GET /networks/{cloudid}/floatingipsThis API returns a list of free floating IP addresses under a tenant.
Query Parameters
The following parameters are optional.v projectId: Specify the project ID to which the floating IP addresses belong. If the ID is missing, the
user's default project is used. Use a string value. The project ID can either be the self-service portalproject ID or the OpenStack ID, which is a UUID. For example, the following two calls return the samedata.http://localhost:18080/cloud/api/networks/6803/floatingips?projectId=53http://localhost:18080/cloud/api/networks/6803/floatingips?projectId=e772a28ef6b64e3ca333582ef8841fcb
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 75
v unused: The default value is true, so the result contains only free floating IP addresses. Set to false toreturn all floating IP addresses, including IP addresses already associated to a fixed IP address. Use aBoolean value.
Sample Request
To retrieve the list of free floating IP addresses:
GET http://localhost:18080/cloud/api/networks/652/floatingips/
Sample Response
HTTP Status: 200
HTTP Response Body:{
"total":"1","floatingips":[
{"id":"6416b5e3-7a34-4a06-9780-c5f10bc11214","floating_ip_address":"192.168.1.4","port_id":"","fixed_ip_address":"","uri":"http://localhost:18080/cloud/api/networks/6803/floatingips/6416b5e3-7a34-4a06-9780-c5f10bc11214"
}]
}
HTTP Response Body:{
"total":"2","floatingips":[
{"id":"520d25a8-13af-4707-a5e4-5700ba98074a","floating_ip_address":"192.168.1.15","port_id":"","fixed_ip_address":"","uri":"http://localhost:18080/cloud/api/networks/6803/floatingips/520d25a8-13af-4707-a5e4-5700ba98074a"},
{"id":"fd6d8f71-9dc0-459e-bfa2-0938b0c09261","floating_ip_address":"192.168.1.18","port_id":"","fixed_ip_address":"","uri":"http://localhost:18080/cloud/api/networks/6803/floatingips/fd6d8f71-9dc0-459e-bfa2-0938b0c09261"
}]
}
GET /networks/{cloudid}/floatingips/{serverid}This API returns a list of floating IP addresses of a server with its related fixed IP address.
Query Parameters
N/A
Sample Request
To retrieve the list of floating IP addresses with the related fixed IP address:
76 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
GET http://localhost:18080/cloud/api/networks/652/floatingips/3d3790c1-7396-49d7-bdf3-f35b055c90e1
If the server has no floating IP associated with it, this API lists all fixed IP addresses without any floatingIP address. In this case, you must use the port ID to pick and associate a floating IP address. See the lastresponse body listed on this page.
GET http://localhost:18080/cloud/api/networks/6803/floatingips/173f38be-60ef-4247-8587-ed09670b20e3
Note: The {serverid} value can either be the OpenStack server UUID or the IBM Cloud Manager withOpenStack virtual server ID. For more information about how to obtain the virtual server ID, see “GET/virtualServers” on page 114.
Sample Response
HTTP Status: 200
HTTP Response Body:{
"total":"1","floatingips":[
{"id":"","floating_ip_address":"192.168.1.3","port_id":"f288d2b4-3129-4dda-8d8c-007ec70b8cee","fixed_ip_address":"192.168.2.3","uri":"http://localhost:18080/cloud/api/networks/6803/floatingips/173f38be-60ef-4247-8587-ed09670b20e3/4f6dc870-a471-4178-a398-94e93654c8ca"
}]
}
HTTP Response Body:{
"total":"1","floatingips":[{"port_id":"f288d2b4-3129-4dda-8d8c-007ec70b8cee","fixed_ip_address":"192.168.2.3","uri":"http://localhost:18080/cloud/api/networks/6803/floatingips/173f38be-60ef-4247-8587-ed09670b20e3/null"}
]}
PUT /networks/{cloudid}/floatingips/{floating ip id}This API updates the floating IP address associated to a fixed IP address on a server.
Query Parameters
port: The port ID to which you want to associate this floating IP. If this is missing, the associated fixed IPaddress is removed.
Sample Request
To add a floating IP to a port:
PUT http://localhost:18080/cloud/api/networks/6803/floatingips/4f6dc870-a471-4178-a398-94e93654c8ca?port=f288d2b4-3129-4dda-8d8c-007ec70b8cee
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 77
To remove the floating IP associated to a port:
PUT http://localhost:18080/cloud/api/networks/6803/floatingips/4f6dc870-a471-4178-a398-94e93654c8ca
Sample Response
HTTP Status: 200
HTTP Response Body:CYX1190I: SUCCESS: Floating IP address ’4f6dc870-a471-4178-a398-94e93654c8ca’ is updated.
Product information servicesUse the services listed here to obtain product information about the IBM Cloud Manager with OpenStackoffering.Related information:“Code license and disclaimer information” on page 208
GET /productInfo/versionThis service retrieves the IBM Cloud Manager with OpenStack product version.
Query Parameters
N/A
Sample Request
GET http://host/cloud/api/productInfo/version
No HTTP body required.
Sample Response
3.1.0.0
GET /productInfo/shortNameThis service retrieves the IBM Cloud Manager with OpenStack product's short name.
Query Parameters
N/A
Sample Request
GET http://host/cloud/api/productInfo/shortName
No HTTP body required.
Sample Response
SmartCloud Entry
GET /productInfo/nameThis service retrieves the product's name.
78 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
Query Parameters
N/A
Sample Request
GET http://host/cloud/api/productInfo/name
No HTTP body required.
Sample Response
IBM Cloud Manager with OpenStack
GET /productInfo/fullNameThis is a utility service that retrieves the full name and version of the IBM Cloud Manager withOpenStack product.
Query Parameters
N/A
Sample Request
GET http://host/cloud/api/productInfo/fullName
No HTTP body required.
Sample Response
HTTP Status: 200
Content-Type: text/plain
HTTP Response Body:
IBM Cloud Manager with OpenStack 3.1.0.0
GET /productInfo/vendorNameThis is a utility service that retrieves the IBM Cloud Manager with OpenStack product's vendor name.
Query Parameters
N/A
Sample Request
GET http://host/cloud/api/productInfo/vendorName
No HTTP body required.
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 79
Sample Response
HTTP Status: 200
Content-Type: text/plain HTTP Response Body:
IBM
GET /productInfo/vendorIconThis is a utility service that retrieves the IBM Cloud Manager with OpenStack product's vendor icon.
Query Parameters
N/A
Sample Request
GET http://host/cloud/api/productInfo/vendorIcon
No HTTP body required.
Sample Response
HTTP Status: 200
Content-Type: image/* HTTP Response Body is binary image stream.
GET /productInfo/splashThis is a utility service that retrieves the IBM Cloud Manager with OpenStack product's splash icon.
Query Parameters
N/A
Sample Request
GET http://host/cloud/api/productInfo/splash
No HTTP body required.
Sample Response
HTTP Status: 200
Content-Type: image/* HTTP Response Body is binary image stream.
GET /productInfo/icon{type}This is a utility service that retrieves the IBM Cloud Manager with OpenStack product's icon, returns a16x16 icon if type is small, returns a 32x32 icon if type is medium, pr returns a 48x48 icon if type is large.
Query Parameters
type, return 16x16 icon if type is small, return 32x32 icon if type is medium, return 48x48 icon if type islarge
80 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
Sample Request
GET http://host/cloud/api/productInfo/icon{type}
No HTTP body required.
Sample Response
HTTP Status: 200
Content-Type: image/* HTTP Response Body is binary image stream.
Project management servicesThe IBM Cloud Manager with OpenStack product provides the following project management services.Related information:“Code license and disclaimer information” on page 208
GET /projectsThis service retrieves the list of projects in IBM Cloud Manager with OpenStack.
The owner field in the returned json string is deprecated from IBM Cloud Manager with OpenStack 2.2,because there can be more than owners.
Query Parameters
Name Description Default Required
user Gets the list of projects towhich this user belongs
N/A No
role Gets the list of projects towhich this user belongsand this user has thepermission of specified role.This parameter should beused with the userparameter. This parametersupports OWNER, USER,and VIEWER. Thisparameter is caseinsensitive. OWNER haspermission of USER andVIEWER. USER haspermission of VIEWER. Forexample, if role is specifiedas USER, projects of whichthis user is OWNER andUSER will be returned.
N/A No
Sample Request
GET http://host/cloud/api/projects?user=jonest&role=user
No HTTP body required.
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 81
Sample Response
HTTP Status: 200
HTTP Response Body:{
"identifier":"id","projects":[{
"isStaging":false,"useCloudApprovalPolicy": true,"isPublic":true,
"isDefault":true,"name":"Public","id":"51","description":"This is the default project for all existing Cloud resources.","uri":"http://localhost:18080/cloud/api/projects/51","useCloudExpirationPolicy":true
}]
}
POST /projectsThis service creates a new project in IBM Cloud Manager with OpenStack.
Sample Request
POST http://host/cloud/api/projects
HTTP Request Body:{
"name":"myProject1","description":"My number 1
project","members":[
{"username":"user1","role":"OWNER"
}]
}
Sample Response
HTTP Status: 201
HTTP Location Header: The URI of the new project
HTTP Response Body:{
"workloadsUri":" Header: The URI of the new project"http://localhost:18080/cloud/api/projects/62951/workloads">http://localhost:18080/cloud/api/projects/62951/workloads",
"isStaging":false,"owner":"admin","isPublic":false,"usersUri":"oud/api/projects/62951/workloads">http://localhost:18080/cloud/api/projects/62951/workloads",
"http://localhost:18080/cloud/api/projects/62951/users">http://localhost:18080/cloud/api/projects/62951/users","appliancesUri":"i/projects/62951/users">http://localhost:18080/cloud/api/projects/62951/users",
"http://localhost:18080/cloud/api/projects/62951/appliances">http://localhost:18080/cloud/api/projects/62951/appliances","isDefault":false,"name":"myProject2","id":"62951","description":"My number 1 project",
82 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
"uri":" number 1"useCloudExpirationPolicy":true"http://localhost:18080/cloud/api/projects/62951">http://localhost:18080/cloud/api/projects/62951"}
DELETE /projects/{id}This service deletes the project with the specified ID.
Sample Request
DELETE http://host/cloud/api/projects/1234
No HTTP body required.
Sample Response
HTTP Status: 200
No HTTP response body
PUT /projects/{id}This service updates the attributes of the project identified by ID.
If the JavaScript Object Notation (JSON) in the request body does not contain a “members”array attribute,only the top-level project fields are synchronized. If the “members”array attribute is present in theincoming JSON, then the members are also synchronized. User names specified in the “members” arraymust exist as users. The implication of such is that you can update project members in bulk.
Sample Requests1. Update the project with id “1234”to have the description “My number 1 project”.
PUT http://host/cloud/api/projects/1234HTTP Request Body:{
"description":"My number 1 project"}
2. Update the project with id “1234” to have the name “My Project,”a description of “A simple project,”and have the project members “admin” and “john.” The underlying project members exactly matchthe members specified.
3. PUT http://host/cloud/api/projects/1234HTTP Request Body:{
"name":"My Project","description":"A simple description","members":[
{"username":"admin"
},{
"username":"john"}
]}
4. Update the project with id “1234” to have the useCloudExpirationPolicy as false.PUT http://host/cloud/api/projects/1234HTTP Request Body:
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 83
{"useCloudExpirationPolicy":false
}
Sample Response
HTTP Status: 200
No HTTP Response Body
GET /projects/{id}This service retrieves the attributes of the project identified by id.
Sample Request
GET http://host/cloud/api/projects/1234
No HTTP body required.
Sample Response
HTTP Status: 200
HTTP Response Body:{"workloadsUri":"http://localhost:18080/cloud/api/projects/1234/workloads","isStaging":false,"owner":"admin","isPublic":false,"useCloudApprovalPolicy": true,"usersUri":"http://localhost:18080/cloud/api/projects/1234/users","appliancesUri":"http://localhost:18080/cloud/api/projects/1234/appliances","isDefault":false,"name":"My Project","id":"1234","description":"A simple description","uri":"http://localhost:18080/cloud/api/projects/1234","useCloudExpirationPolicy":true
}
GET /projects/{id}/workloadsThis service retrieves the workloads with the specified ordering and counts associated with the projectidentified by id.
Query Parameters
Name Description Default Required
start This is the index of the firstrecord that will be returnedfrom the database. Ifspecified, the value must bean integer greater thanzero.
0 No
count This is the number ofrecords to return after the"start" parameter record.The value must be aninteger greater than zero.
20 No
84 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
Name Description Default Required
sortBy This is the sorted column inDeploymentEntity. Thisparameter supportsEXECUTION_DATE,NAME, DESCRIPTION andSTATE. This parameter iscase insensitive.
EXECUTION_DATE No
order Specify order withascending or descending.The parameter can be setdesc or asc.
desc No
includeHidden Specifies whether returnedworkloads should includehidden workloads.
false No
Sample Request
GET http://host/cloud/api/projects/1234/workloads?start=10&count=30&sortBy=NAME&order=asc
No HTTP body required.
Sample Response
HTTP Status: 200
HTTP Response Body:{
"total": "2","workloads": [
{"cloudName": "zhanxin-GVTTest-noDelete","cloudGroupId": "352","name": "zhanxin-GVTTest-noDelete","uri": "http://localhost:18080/cloud/api/workloads/531","cloudId": "cloud://352/422e40df-6415-0a7c-2056-36e91e74f804","state": {
"label": "OK","id": "OK"
},"projectUri": "http://localhost:18080/cloud/api/projects/103001","architecture": "x86","isHidden": false,"cloudGroupName": "VMware-120","hypervisor": "VMware","id": "531","description": "Workload could no longer be found in the Cloud.It could have been purposely deleted from the Cloud."
},{
"cloudName": "RHEL6_Template121 2012-07-03 12:41:05 test_ly_by_testUser","cloudGroupId": "352","name": "RHEL6_Template121 2012-07-03 12:41:05 test_ly_by_testUser","uri": "http://localhost:18080/cloud/api/workloads/73508","cloudId": "cloud://352/e7e213c5-4c6f-416b-9642-baa5ae6549cc","state": {
"label": "OK","id": "OK"
},"projectUri": "http://localhost:18080/cloud/api/projects/103001","architecture": "x86","isHidden": false,"cloudGroupName": "VMware-120","hypervisor": "VMware","id": "73508",
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 85
"description": "RHEL6_Template121 2012-07-03 12:41:05 test_ly_by_testUser"}
]}
GET /projects/{id}/appliancesThis service retrieves the appliances that are associated with the project identified by id.
Sample Request
GET http://host/cloud/api/projects/1234/appliances
No HTTP body required.
Sample Response
HTTP Status: 200
Localized values: "state"
HTTP Response Body:{
"total": "2","appliances": [
{"cloudName": "RHEL62_Mult_NIC_template","changedDate": 1341245438785,"cloudGroupId": "352","name": "RHEL62_Mult_NIC_template","uri": "http://localhost:18080/cloud/api/appliances/55151","revisionComments": "","cloudId": "cloud://352/422e3a6f-48cd-7f0d-5ec7-b4e2ec4fdb7a","state": {
"label": "OK","id": "OK"
},"projectUri": "http://localhost:18080/cloud/api/projects/103001","architecture": "x86","cloudGroupName": "VMware-120","specificationVersion": "vmx-08","hypervisor": "VMware","version": "vmx-08","id": "55151","revision": "","description": "Red Hat Enterprise Linux 5 (64-bit)"
},{
"cloudName": "GVTTestLinux6.1","changedDate": 1338301027525,"cloudGroupId": "352","name": "GVTTestLinux6.1","uri": "http://localhost:18080/cloud/api/appliances/498","revisionComments": "","cloudId": "cloud://352/422e0874-da6f-b06e-0f52-dacf7faa8a6d","state": {
"label": "OK","id": "OK"
},"projectUri": "http://localhost:18080/cloud/api/projects/103001","architecture": "x86","cloudGroupName": "VMware-120","specificationVersion": "vmx-08","hypervisor": "VMware","version": "vmx-08","id": "498","revision": "","description": "Red Hat Enterprise Linux 6 (64-bit)"
}]
}
86 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
GET /projects/{id}/usersThis service retrieves the users that have access to the project identified by id.
Sample Request
GET http://host/cloud/api/projects/1234/users
No HTTP body required.
Sample Response
HTTP Status: 200
HTTP Response Body:{
"users":[{
"uri":"http://host/cloud/api/projects/1234/users/admin","username":"admin","name":"Administrator","isAdmin":true,"emailNotifications":true,"email":"[email protected]","role":
{"id":"OWNER","label":"Owner"
}},{
"uri":"http://host/cloud/api/projects/1234/users/jonest","username":"jonest","name":"Tony Jones","isAdmin":false"emailNotifications":true,"email":"[email protected]","role":
{"id":"OWNER","label":"Owner"
}}
]}
GET /projects/{id}/expirationPolicyThis service retrieves the expiration policy of the project.
Query Parameters
N/A
Sample Request
GET http://host/cloud/api/projects/1234/expirationPolicy
No HTTP body required.
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 87
Sample Response
HTTP Status: 200
HTTP Response Body:{"notificationFrequency":3,"maxExpirationPeriod":30,"deleteAfterGrace":true,"notificationStart":14,"gracePeriod":0,"id":"52","enableExtension":true,"maxExtensionPeriod":30,"maxExpirationPeriodWithoutSetting":1825,"ownerType":"project","workloadExpirationSettingAppliable":false,"ownerId":"1234"}
POST /projects/{id}/usersThis service adds a user to the project identified by ID or sends the owner of the project a notification(email based as of 1.1) requesting access to the project for the specified user. For access requestnotification, the owner of the project must have notifications enabled to receive the access requestmessage.
Query Parameters
Name Description Default Required
requestOnly Send a notification to theproject owner requestingaccess.
false No
Sample Request 1
Add the “jonest” user to project with ID “1234”.
POST http://host/cloud/api/projects/1234/users
HTTP Request Body:{
"username":"jonest","role":"USER"
}
Sample Response 1
HTTP Status: 201
HTTP Location Header: The URI of the added user within the project
No HTTP Response Body
Sample Request 2
Send a notification to the owner of project “1234” requesting access for user “john”. The “john” user isnot added by this call, rather the owner receiving the notification must add the user from the webinterface.
88 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
POST http://host/cloud/api/projects/1234/users?requestOnly=true HTTP Request Body:{
"username":"john"}
Sample Response 2
HTTP Status: 200
PUT /projects/{id}/users/{username}This service will update a user's in the project identified by id.
The role of the user may be changed to OWNER, USER, or VIEWER. The role of a project member maybe changed only by an IBM SmartCloud Entry admin or the project's owner.
Query Parameters
Table 2. Query Parameters
Name Description Required
username The username of the user whose rolein the project is to be updated
yes
Sample Request
Change the 'jonest' user's role to USER in project with Id '1234'.
PUT http://host/cloud/api/projects/1234/users/jonest
HTTP Request Body:{
"role":"USER"}
Sample Response
HTTP Status: 200
No HTTP response body
DELETE /projects/{id}/users/{username}This service will remove the user identified by username from the project identified by id.
Sample Request
DELETE http://host/cloud/api/projects/1234/users/jonest
No HTTP body required.
Sample Response
HTTP Status: 200
No HTTP response body
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 89
Request lifecycle servicesThe IBM Cloud Manager with OpenStack product provides the following lifecycle services.Related information:“Code license and disclaimer information” on page 208
GET /requestsThis service retrieves a list of requests from the IBM Cloud Manager with OpenStack application. Theservice optionally allows the client to provide query parameters to retrieve specific requests by a givenusername or the request's resolved status.v The optional 'user' query parameter filters the list of requests by the given user. If the user is an admin
or an approver all requests are returned. Otherwise only requests made by the given user are returned.v The optional 'resolved' query parameter filters the returned requests by their resolved status. If
resolved is 'true' then only requests which are not in the 'PENDING' state are returned. If resolved isfalse only 'PENDING' requests are returned.
v The optional 'parameters' query parameter filters the returned requests by parameter name, such as"deployment". Specific IDs can be specified for each given parameter, separated from the type by acolon (:). Multiple parameters can be specified by adding a semicolon (;) between them.
v The optional 'state' query parameter filters the returned requests by their state, such as 'PENDING'.Multiple states can be checked for by adding a comma (,) between them to return requests that are inany of the states listed.
v The “user”, “resolved”, “parameter”, and “state” query parameters can be used together. If noparameter is used, then all requests are returned unfiltered.
There are other parameters related to pagination. Use the following query parameters to see moreinformation.
Query Parameters
Name Description Default Required
user Filters the list of requests by the given user. N/A No
resolved Filters the lists of requests by their resolved status. N/A No
parameters Filters the lists of requests by their parameter. N/A No
state Filters the lists of requests by their state. N/A No
start The index of the first record. 0 No
count The number of records to return. 20 No
sortBy This parameter supportsID,REQUESTOR,STATE,ACTION, and REQUESTDATE.This parameter is case insensitive.
ID No
order Specify ascending (ASC) or descending (DESC) order. DESC No
Sample Request
GET http://host/cloud/api/requests?user=myuser&resolved=true
Retrieves all requests for 'myuser' which are resolved. If 'myuser' is an admin or approver of requests,then all requests are returned which are resolved. Otherwise only resolved requests are returned whichwere initiated by 'myuser'.
No HTTP body required.
90 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
GET http://host/cloud/api/requests?parameters=deployment:10,12,22&state=PENDING,REJECTEDRetrieves all PENDING or REJECTED requests that are deployments that have the ids 10,12,22.
Sample Response
HTTP Status: 200
HTTP Response Body:{
"total":"1","requests":[
{"state":{
"label":"Approved","id":"APPROVED"
},"requestor":"admin","action":
{"label":"Deployment Executed","id":"DEPLOYMENT_EXECUTED"},
"parameters": [{
"value": "102""name": "deployment"
}],"id":"751","uri":"http://localhost:18080/cloud/api/requests/751","requestDate":1299703640794
}],"uri":"http://localhost:18080/cloud/api/requests"
}
PUT /requestsThis service enables or disables the request lifecycle service as a whole.
Query Parameters
N/A
Sample Request 1
Enables the request lifecycle service as a whole.
PUT http://host/cloud/api/requests{
"enabled":true}
Sample Response 1
HTTP Status: 200
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 91
Sample Request 2
Disables the request lifecycle service as a whole.
PUT http://host/cloud/api/requests{
"enabled":false}
Sample Response 2
HTTP Status: 200
GET /requests/{id}This service retrieves a specific request from IBM SmartCloud Entry by the request's id.
Query Parameters
None
Sample Request
GET http://host/cloud/api/requests/751
Retrieves the request which has the id of '751'.
No HTTP body required.
Sample Response
HTTP Status: 200
HTTP Response Body:{
"state":{
"label":"Approved","id":"APPROVED"
},"requestor":"admin","resolver":"admin","action":
{"label":"Deployment Executed","id":"DEPLOYMENT_EXECUTED"},
"commentsURI":"http://localhost:18080/cloud/api/requests/751/comments","parametersURI":"http://localhost:18080/cloud/api/requests/751/parameters","resolutionDate":1299704103719,"name":"DEPLOYMENT_EXECUTED","id":"751","uri":"http://localhost:18080/cloud/api/requests/751","requestDate":1299703640794
}
PUT /requests/{id}This service updates a specific request's status in IBM SmartCloud Entry specified by the request's id.This service cannot be use to modify other values associated with a request other than its state. Client'sshould use this service to approve, deny, reopen or withdraw requests.
The accepted states for a request are:
92 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
APPROVED - The request is approved.
REJECTED - The request is rejected and cannot be completed.
WITHDRAWN - The request has been withdrawn and is no longer PENDING.
PENDING - The request is open and pending approval.
Query Parameters
None
Sample Requests1. Approve request 751.
PUT http://host/cloud/api/requests/751HTTP Request Body:{
"state":"APPROVED"}
2. Deny request 732.PUT http://host/cloud/api/requests/732HTTP Request Body:{
"state":"REJECTED"}
Sample Response
HTTP Status: 200
HTTP Response Body: None
GET /requests/{id}/parametersThis service retrieves a specific request's parameters.
Query Parameters
None
Sample Request
GET http://host/cloud/api/requests/751/parameters
Retrieves the request which has the id of '751'.
No HTTP body required.
Sample Response
HTTP Status: 200
HTTP Response Body:
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 93
{"parameters":[
{"value":"OnedeployTest","name":"workloadName"
},{
"value":"65901","name":"workload"
},{
"value":"workload","name":"type"
}],"uri":"http://localhost:18080/cloud/api/requests/66151/parameters"
}
PUT /requests/{id}/parametersThis service updates a specific request's parameters.
Query Parameters
None
Sample Request
Update the request parameters called “cpu”in request 751.
PUT http://host/cloud/api/requests/751
HTTP Request Body:{
"parameters": [{"name":"cpu", "value":"2"}]
}
Sample Response
HTTP Status: 200
HTTP Response Body: None
GET /requests/{id}/commentsRetrieve the comments for a specific request specified by its id.
Query Parameters
None
Sample Request
Get the comments for request 751.
GET http://host/cloud/api/requests/751/comments
94 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
HTTP Request Body: None
Sample Response
HTTP Status: 200
HTTP Response Body:{
"comments":[{
"user":"admin","date":1299777502592,"comment":"This a sample comment"
},{
"user":"admin","date":1299777519726,"comment":"Yet another comment for request 751"
}],"uri":"http://localhost:18080/cloud/api/requests/751/comments"
}
POST /requests/{id}/commentsAdd a comment to the request specified by its id.
Query Parameters
None
Sample Request
Add a comment to request 751.
POST http://host/cloud/api/requests/751/comments
HTTP Request Body: This is a request comment
Sample Response
HTTP Status: 200
HTTP Response Body: None
GET /requests/handlersRetrieves sets of the request handlers for cloud groups and projects.
Request handlers are specified on a per action basis and will either be enabled or not. An enabled requesthandler for a specific action is used to process (handle) the request when fired within IBM CloudManager with OpenStack.
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 95
Query Parameters
Table 3. Query parameters
Name Description Default value Required
ownerType The type of object to whichthe handlers set belongs.Values are CLOUDGROUPor PROJECT.
N/A false
ownerId Cloud group id or projectid.
N/A false
Sample Request
Get a list of the request handlers:
GET http://host/cloud/api/requests/handlers
HTTP Request Body: None
Sample Response
HTTP Status: 200
HTTP Response Body:[
{"requestHandlers": [
{"enabled": false,"action": {
"label": "Workload expiration extend","id": "DEPLOYMENT_EXPIRATION_EXTEND"
}},{
"enabled": false,"action": {
"label": "Virtual server detach storage request","id": "STORAGE_DETACH_REQUEST"
}},{
"enabled": false,"action": {
"label": "Virtual server attach storage request","id": "STORAGE_ATTACH_REQUEST"
}},{
"enabled": false,"action": {
"label": "Virtual server restore","id": "VIRTUAL_SERVER_RESTORE_BACKUP"
}},{
"enabled": false,"action": {
"label": "Virtual server save image","id": "VIRTUAL_SERVER_CREATE_BACKUP"
}},{
"enabled": false,"action": {
"label": "Workload resize","id": "DEPLOYMENT_RESIZE"
96 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
}},{
"enabled": false,"action": {
"label": "Workload initiation","id": "DEPLOYMENT_EXECUTION"
}},{
"enabled": false,"action": {
"label": "Workload capture","id": "DEPLOYMENT_SNAPSHOT"
}}
],"uri": "http://localhost:18080/cloud/api/requests/handlers?ownerType=CLOUDGROUP&ownerId=551","ownerType": "CLOUDGROUP","ownerId": "551"
},{
"requestHandlers": [{
"enabled": false,"action": {
"label": "Workload expiration extend","id": "DEPLOYMENT_EXPIRATION_EXTEND"
}},{
"enabled": false,"action": {
"label": "Virtual server detach storage request","id": "STORAGE_DETACH_REQUEST"
}},{
"enabled": false,"action": {
"label": "Virtual server attach storage request","id": "STORAGE_ATTACH_REQUEST"
}},{
"enabled": false,"action": {
"label": "Virtual server restore","id": "VIRTUAL_SERVER_RESTORE_BACKUP"
}},{
"enabled": false,"action": {
"label": "Virtual server save image","id": "VIRTUAL_SERVER_CREATE_BACKUP"
}},{
"enabled": false,"action": {
"label": "Workload resize","id": "DEPLOYMENT_RESIZE"
}},{
"enabled": false,"action": {
"label": "Workload initiation","id": "DEPLOYMENT_EXECUTION"
}},{
"enabled": false,"action": {
"label": "Workload capture","id": "DEPLOYMENT_SNAPSHOT"
}}
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 97
],"uri": "http://localhost:18080/cloud/api/requests/handlers?ownerType=PROJECT&ownerId=1",
"ownerType": "PROJECT","ownerId": "1"
}]
PUT /requests/handlersThis service updates the handler enablement state within a specific owner scope.
Query Parameters
N/A
Sample Request
Update the request handler called "DEPLOYMENT_EXECUTION" for "CLOUDGROUP" 551 and handler"DEPLOYMENT_EXPIRATION_EXTEND" for "PROJECT" 1.
PUT http://host/cloud/api/requests/handlers
HTTP Request Body:[
{"requestHandlers": [
{"enabled": true,"action": "DEPLOYMENT_EXECUTION"
}],"ownerType": "CLOUDGROUP","ownerId": "551"
},{
"requestHandlers": [{
"enabled": true,"action": "DEPLOYMENT_EXPIRATION_EXTEND"
}],"ownerType": "PROJECT","ownerId": "1"
}]
Sample Response
HTTP Status: 200
HTTP Response Body: None
GET /requests/requestcsvExports requests, that are filtered by parameters, to file and saves it on a server architecture directory.
98 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
Query Parameters
Name Description Default Required
startTime Timestamp that specifies astarting timeframe forrequests returned. Requeststhat occur before thistimestamp will not bereturned. The startTime andendTime can be usedtogether to specify atimeframe for the requestsreturned. This value is atimestamp that is thenumber of millisecondssince January 1, 1970,00:00:00 GMT.
0 No
endTime Timestamp that specifies anending timeframe forrequests returned. Requeststhat occur after thistimestamp will not bereturned. The startTime andendTime can be usedtogether to specify atimeframe for the requestsreturned. This value is atimestamp that is thenumber of millisecondssince January 1, 1970,00:00:00 GMT.
Yes
state The request’s state can bePENDING, APPROVED,REJECTED, WITHDRAWNor some combination. Acomma is used toconcatenate them.
Yes
Sample Request
GET http://localhost:18080/cloud/api/requests/requestcsv?startTime=1341385199000&endTime=1341385299000&state=APPROVED,REJECTED
Sample Response
HTTP Status: 200 if successful
DELETE /requests/requstcsvDeletes requests that are filtered by parameters.
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 99
Query Parameters
Name Description Default Required
startTime Timestamp that specifies astarting timeframe fordeletion requests. Requeststhat occur before thistimestamp will not bedeleted. The startTime andendTime can be usedtogether to specify atimeframe for deleting therequests. This value is atimestamp that is thenumber of millisecondssince January 1, 1970,00:00:00 GMT.
0 No
endTime Timestamp that specifies anending timeframe fordeletion requests. Requeststhat occur after thistimestamp will not bedeleted. The startTime andendTime can be usedtogether to specify atimeframe for deleting therequests. This value is atimestamp that is thenumber of millisecondssince January 1, 1970,00:00:00 GMT.
Yes
state The request’s state can bePENDING, APPROVED,REJECTED, WITHDRAWNor some combination. Acomma is used toconcatenate them.
Yes
Sample Request
DELETE http://localhost:18080/cloud/api/requests/requestcsv?startTime=1341385199000&endTime=1341385299000&state=APPROVED,REJECTED
Sample Response
HTTP Status: 200 if successful
Statistics resource servicesThe IBM Cloud Manager with OpenStack product provides the following services for gathering statistics.Related information:“Code license and disclaimer information” on page 208
GET /stats/freeThis service retrieves the statistics of all available resources in the cloud, such as CPU, memory, andstorage.
100 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
The CPU statistic is measured in cores. Memory and storage are measured in Megabytes.
Query Parametersv cloudId (optional)
If you include a cloudId in the request URL, the service returns the free resource statistics for the singlecloud identified. If you do not specify a cloudId, the service returns the free resource statistics formultiple clouds.
Sample Request
Retrieve all available resources from cloud
GET http://host/cloud/api/stats/free
No HTTP body required.
Sample Response
HTTP Status: 200
HTTP Response Body:{
uri: http://localhost:18080/cloud/api/stats/freestats: [
{architecture: "Power"resources: [
{value: "24.0"label: "Processors"id: "freeCPU"
}{
value: "236304.0"label: "Memory"id: "freeMemory"
}{
value: "13645"label: "Storage"id: "freeDisk"
}}{
architecture: "x86"resources: [
{value: "24.0"label: "Processors"id: "freeCPU"
}{
value: "236304.0"label: "Memory"id: "freeMemory"
}{
value: "13645"label: "Storage"id: "freeDisk"
}
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 101
]}
]}
GET /stats/totalsThis service retrieves the statistics of all resources in the cloud, such as CPU, memory, and storage.
The CPU statistic is measured in cores. Memory and storage are measured in Megabytes.
Query Parametersv cloudId (optional)
If you include a cloudId in the request URL, the service returns the resource statistics for the singlecloud identified. If you do not specify a cloudId, the service returns the resource statistics for multipleclouds.
Sample Request
Retrieve all available resources from the cloud
GET http://host/cloud/api/stats/totals
No HTTP body required.
Sample Response
HTTP Status: 200
HTTP Response Body:{
uri: http://localhost:18080/cloud/api/stats/totalsstats: [
{architecture: "Power"resources: [
{value: "24.0"label: "Processors"id: "totalCPU"
}{
value: "236304.0"label: "Memory"id: "totalMemory"
}{
value: "13645"label: "Storage"id: "totalDisk"
}}{
architecture: "x86"resources: [
{value: "24.0"label: "Processors"id: "totalCPU"
}{
value: "236304.0"
102 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
label: "Memory"id: "totalMemory"
}{
value: "13645"label: "Storage"id: "totalDisk"
}]
}]
}
GET /stats/usageThis service retrieves usage resource statistics in the cloud, such as CPU, memory, and storage.
The CPU statistic is measured in cores. Memory and storage are measured in Megabytes.
Query Parameters
Name Description Default Required
user Get the statistic summaryof resource usage byspecified user.
N/A No
cloudId If you include a cloudId inthe request URL, theservice returns the usageresource statistics for thesingle cloud identified. Ifyou do not specify acloudId, the service returnsthe usage resource statisticsfor multiple clouds.
N/A No
Sample Request 1
Retrieve all resources usage statistics from the cloud
GET http://host/cloud/api/stats/usage
No HTTP body required.
Sample Response 1
HTTP Status: 200
HTTP Response Body:{uri:http://localhost:18080/cloud/api/stats/usage
stats: [{architecture:"Power"resources: [{value:"24.0"label:"Processors"id:"usageCPU"}{
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 103
value:"236304.0"label:"Memory"id:"usageMemory"
}{
value:"13645"label:"Storage"id:"usageDisk"
}}{
architecture:"x86"resources: [
{value:"24.0"label:"Processors"id:"usageCPU"
}{
value:"236304.0"label:"Memory"id:"usageMemory"
}{
value:"13645"label:"Storage"id:"usageDisk"
}]
}]}
Sample Request 2
Retrieve resources usage by admin
GET http://host/cloud/api/stats/usage?user=admin
No HTTP body required.
Sample Response 2
HTTP Status: 200
HTTP Response Body:{uri:http://localhost:18080/cloud/api/stats/usage
stats: [{
architecture:"Power"resources: [
{value:"24.0"label:"Processors"id:"usageCPU"
}{
value:"236304.0"label:"Memory"id:"usageMemory"
}{
value:"13645"label:"Storage"id:"usageDisk"
}
104 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
}{
architecture:"x86"resources: [
{value:"24.0"label:"Processors"id:"usageCPU"
}{
value:"236304.0"label:"Memory"id:"usageMemory"
}{
value:"13645"label:"Storage"id:"usageDisk"
}]
}]}
User servicesThe IBM Cloud Manager with OpenStack product provides the following services for managing the userregistry.Related information:“Code license and disclaimer information” on page 208
GET /usersThis service retrieves all known users from the IBM SmartCloud Entry user registry.
A IBM Cloud Manager with OpenStack Administrator user ('admin') is created by default and willalways exist. A client can also use this service to retrieve a list of users with admin authority by using theadmin query parameter. Note that a user's password is not returned in the response JSON.
Query Parameters
Name Description Default Required
admin The users retrieved shouldhave admin access.
false No
Sample Request
Retrieve a listing of all users in the IBM SmartCloud Entry user registry.
GET http://host/cloud/api/users
No HTTP body required.
Sample Response
HTTP Status: 200
HTTP Response Body:{
"users": [{
"emailNotifications": false,
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 105
"username": "admin","email": "","isApprover": true,"name": "Cloud Administrator","role": {
"id": "ADMIN","label": "label"
},"isAdmin": true,"uri": "http://9.123.152.202:18080/cloud/api/users/admin","isLocked": false
},{
"emailNotifications": false,"username": "test","isApprover": false,"name": "test","role": {
"id": "USER","label": "label"
},"isAdmin": false,"uri": "http://9.123.152.202:18080/cloud/api/users/test","isLocked": false
},{
"emailNotifications": false,"username": "xinzhan","isApprover": false,"name": "xinzhan","role": {
"id": "USER","label": "label"
},"isAdmin": false,"uri": "http://9.123.152.202:18080/cloud/api/users/xinzhan","isLocked": false
},{
"emailNotifications": false,"username": "zxx","isApprover": false,"name": "zxx","role": {
"id": "USER","label": "label"
},"isAdmin": false,"uri": "http://9.123.152.202:18080/cloud/api/users/zxx","isLocked": false
}]
}
GET /users/{username}This service retrieves the properties for a specific user from the IBM Cloud Manager with OpenStack userregistry.
If a user has admin authority, the "isAdmin" and "isSCEAdmin" attributes will be set to "true". Thepassword of users is not returned in the response JSON.
Query Parameters
N/A
Sample Request
GET http://host/cloud/api/users/[email protected]
No HTTP body required.
106 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
Sample Response 1
HTTP Status: 200
HTTP Response Body:{
"emailNotifications": false,"username": "admin","email": "","isApprover": true,"name": "Cloud Administrator","role": {
"id": "ADMIN","label": "label"
},"isAdmin": true,"uri": "http://9.123.152.202:8080/cloud/api/users/admin","isLocked": false
}
POST /usersThis service adds a user to the IBM Cloud Manager with OpenStack user registry.
Note: This API applies only when the IBM Cloud Manager with OpenStack server is using the localauthentication scheme. If your server is configured to use LDAP authentication, you get an error if youuse this API. For more information about authentication schemes, see the IBM Cloud Manager withOpenStack Administrator Guide.
A user can be added to the registry in one of two ways.v Use the POST /users service to add a user to the registry.v If a user is authenticated successfully with the /auth service, IBM Cloud Manager with OpenStack
adds the authenticated user to the registry if the user does not exist. The password is not returned inthe response JavaScript Object Notation (JSON).
This is an admin web service.
Query Parameters
N/A
Sample Request
Add the user “[email protected]” to the user registry.
POST http://host/cloud/api/users
HTTP Request Body:{
"username":"[email protected]","password":"fun4csk","isAdmin":false,"isApprover":true,"emailNotifications":true,"email":"[email protected]","name":"John Doe","timezone": {
"id": "America/Chicago"},
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 107
"locale": {"id": "en-US"
}}
Sample Response
HTTP Status: 201
HTTP Response Body:{
"isAdmin":false,"isLocked":false,"username":"[email protected]","timezone":{
"label":"Central Standard Time","id":"America/Chicago"
},"locale":{
"label":"English (United States)","id":"en-US"
},"name":"John Doe","emailNotifications":true,"email":"[email protected]","uri":"http://localhost:8080/cloud/api/users/jdoe%40us.ibm.com"
}
PUT /users/{username}This service enables updating of an existing user in the IBM Cloud Manager with OpenStack userregistry.
This service does not allow you to update the “username” associated with an existing user in the registry.If the “username” needs to be updated, the caller should first DELETE the user, and then use POST tocreate it with the new “username”. The PUT/users/{username} service does not allow you to update thedefault IBM Cloud Manager with OpenStack administrator user “admin”. After registering, a user canupdate the password in the service.
This is an admin Web service.
Query Parameters
N/A
Sample Request
Update user “[email protected]” to have “password” set to “new2pass” and “name” to be “Mr John Doe”
PUT http://host/cloud/api/users/[email protected]{
"username":"[email protected]","name":"Mr John Doe","isAdmin":false,"isApprover":true,"isLocked":false,"password":"new2pass","oldPassword":"old2pass","timezone": {
"id": "America/Chicago"},
108 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
"locale": {"id": "en-US"
}}
Sample Response
HTTP Status: 200
DELETE /users/{username}This service removes an existing user from the IBM Cloud Manager with OpenStack user registry.
If the specified user does not exist in the IBM Cloud Manager with OpenStack user registry, a 404response status is returned. Note that the default IBM Cloud Manager with OpenStack administrator user('admin') cannot be deleted.
If the specified user is the current authenticated user, a 202 response status is returned and a deletionrequest is created. After the approval of the IBM Cloud Manager with OpenStack administrator, the useris deleted.
Note: Users (without admin authority) only can request to delete themselves.
Query Parameters
N/A
Sample Request
Remove the user “[email protected]” from the user registry.
DELETE http://host/cloud/api/users/[email protected]
Sample Response
When the administrator deletes other users, HTTP Status: 200.
When users request to delete themselves, HTTP Status: 202.
Virtual server servicesThe IBM Cloud Manager with OpenStack product provides the following services for managing virtualservers.Related information:“Code license and disclaimer information” on page 208
GET /workloads/{id}/virtualServersThis service retrieves all the virtual servers within a workload by ID.
Workloads that have been executed and were successful will have virtual servers associated with them.Draft or failed workloads will return an empty array.
Query Parameters
N/A
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 109
Sample Request
Get virtual servers for workload with ID 1:
GET http://host/cloud/api/workloads/1/virtualServers
Sample Response
HTTP Status: 200
HTTP Response Body:{
"virtualServers": [{
"cloudId": "cloud://352/e7e213c5-4c6f-416b-9642-baa5ae6549cc","credentialsUri": "http://localhost:18080/cloud/api/workloads/73508/virtualServers/73555/credentials","state": {
"label": "Running","id": "RUNNING"
},"backups": "http://localhost:18080/cloud/api/virtualServers/73555/backups","hostname": "testhost235","storagesUri": "http://localhost:18080/cloud/api/virtualServers/73555/storages","capabilities": [
{"isEnabled": true,"id": "CREATE_DISK"
},{
"isEnabled": false,"id": "ATTACH_DISK"
},{
"isEnabled": true,"id": "DETACH_DISK"
},{
"isEnabled": true,"id": "THIN_PROVISIONED"
},{
"isEnabled": true,"id": "POWER_MANAGEMENT"
},{
"isEnabled": true,"id": "CAPTURE"
},{
"isEnabled": true,"id": "BACKUP"
},{
"isEnabled": false,"id": "SUSPEND_CAPABLE"
},{
"isEnabled": true,"id": "RESIZE"
},{
"isEnabled": false,"id": "PIN"
},{
"isEnabled": false,"id": "UNPIN"
}],"ip": "10.10.2.235","id": "73555",
110 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
"uri": "http://localhost:18080/cloud/api/virtualServers/73555"}
]}
GET /workloads/{id}/virtualServers/{id}This service retrieves a virtual server from the virtual servers in a workload by ID.
If a virtual server by the given ID doesn't exist in the workload, the service will return a 404.
Query Parameters
N/A
Sample Request
Get virtual server with ID 2 from workload with ID 1:
GET http://host/cloud/api/workloads/1/virtualServers/2
Sample Response
HTTP Status: 200
HTTP Response Body:{
"cloudId": "cloud://352/e7e213c5-4c6f-416b-9642-baa5ae6549cc","credentialsUri": "http://localhost:18080/cloud/api/workloads/73508/virtualServers/73555/credentials","state": {
"label": "Running","id": "RUNNING"
},"backups": "http://localhost:18080/cloud/api/virtualServers/73555/backups","properties": [
{"value": "1024","description": "Memory (MB)","category": "General Information"
},{
"value": "RHEL6_Template121 2012-07-03 12:41:05 test_ly_by_testUser","description": "Name","category": "General Information"
},{
"value": "1","description": "CPUs","category": "General Information"
},{
"value": "1","description": "Number of Ethernet Cards","category": "General Information"
},{
"value": "e7e213c5-4c6f-416b-9642-baa5ae6549cc","description": "UUID","category": "General Information"
},{
"value": "linuxGuest","description": "Guest Operating System","category": "General Information"
},{
"value": "rhel5_64Guest","description": "Guest ID","category": "General Information"
},
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 111
{"value": "testhost235","description": "Guest Hostname","category": "General Information"
},{
"value": "10.10.2.235","description": "Guest IP Addresses","category": "General Information"
},{
"value": "vm-2858","description": "ID","category": "General Information"
},{
"value": "Connected","description": "Connection State","category": "General Information"
},{
"value": "host-875","description": "Host","category": "General Information"
},{
"value": "Powered On","description": "Power State","category": "General Information"
}],"hostname": "testhost235","storagesUri": "http://localhost:18080/cloud/api/virtualServers/73555/storages","capabilities": [
{"isEnabled": true,"id": "CREATE_DISK"
},{
"isEnabled": false,"id": "ATTACH_DISK"
},{
"isEnabled": true,"id": "DETACH_DISK"
},{
"isEnabled": true,"id": "THIN_PROVISIONED"
},{
"isEnabled": true,"id": "POWER_MANAGEMENT"
},{
"isEnabled": true,"id": "CAPTURE"
},{
"isEnabled": true,"id": "BACKUP"
},{
"isEnabled": false,"id": "SUSPEND_CAPABLE"
},{
"isEnabled": true,"id": "RESIZE"
},{
"isEnabled": false,"id": "PIN"
},{
"isEnabled": false,"id": "UNPIN"
}],
112 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
"ip": "10.10.2.235","id": "73555","uri": "http://localhost:18080/cloud/api/virtualServers/73555"
}
GET /workloads/{id}/virtualServers/{id}/credentialsThis service retrieves the credentials associated with the given Virtual Server Id.
These credentials are used during the capture process in order to perform the required access to capture.Note that the 'authenticated' attribute is not used for this particular service and so it can be ignored.
Query Parameters
N/A
Sample Request
Get VS with ID 2 credentials from workload with ID 1.
GET http://host/cloud/api/workloads/1/virtualServers/2/credentials
Sample Response
HTTP Status: 200
HTTP Response Body:{
"uri":"https://myhost/cloud/api/workloads/1/virtualServers/2/credentials","user":"root","pass":"not2pass"
}
PUT /workloads/{id}/virtualServers/{id}/credentialsThis service updates the credentials associated with the given virtual server ID and workload ID.
These credentials are used during the capture process in order to perform the required access to capture.This service does not update any credentials on the configured cloud.
Query Parameters
N/A
Sample Request
Update VS with ID 2 credentials from workload with ID 1.
PUT http://host/cloud/api/workloads/1/virtualServers/2/credentials{
"user":"root","password":"not2pass"
}
Sample Response
HTTP Status: 200
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 113
GET /virtualServersThis service retrieves all the virtual servers in all workloads that are available to the requesting user.
Query Parameters
N/A
Sample Request
Get virtual servers for workload with ID 1:
GET http://host/cloud/api/virtualServers
Sample Response
HTTP Status: 200
HTTP Response Body:{
"virtualServers": [{
"cloudId": "cloud://352/422e8944-573e-0af4-f3f7-603e5ff35c5f","credentialsUri": "http://localhost:18080/cloud/api/virtualServers/3957/credentials","state": {
"label": "Unknown","id": "UNKNOWN"
},"backups": "http://localhost:18080/cloud/api/virtualServers/3957/backups","storagesUri": "http://localhost:18080/cloud/api/virtualServers/3957/storages","capabilities": [
{"isEnabled": false,"id": "CREATE_DISK"
},{
"isEnabled": false,"id": "ATTACH_DISK"
},{
"isEnabled": false,"id": "DETACH_DISK"
},{
"isEnabled": false,"id": "THIN_PROVISIONED"
},{
"isEnabled": false,"id": "POWER_MANAGEMENT"
},{
"isEnabled": false,"id": "CAPTURE"
},{
"isEnabled": false,"id": "BACKUP"
},{
"isEnabled": false,"id": "SUSPEND_CAPABLE"
},{
"isEnabled": false,"id": "RESIZE"
},{
"isEnabled": false,"id": "PIN"
},
114 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
{"isEnabled": false,"id": "UNPIN"
}],"ip": "","id": "3957","uri": "http://localhost:18080/cloud/api/virtualServers/3957"
},{
"cloudId": "cloud://352/422e0b45-fb4a-1629-24af-c6d0be945fb5","credentialsUri": "http://localhost:18080/cloud/api/virtualServers/3959/credentials","state": {
"label": "Running","id": "RUNNING"
},"backups": "http://localhost:18080/cloud/api/virtualServers/3959/backups","hostname": "CCS-hgq","storagesUri": "http://localhost:18080/cloud/api/virtualServers/3959/storages","capabilities": [
{"isEnabled": true,"id": "CREATE_DISK"
},{
"isEnabled": false,"id": "ATTACH_DISK"
},{
"isEnabled": true,"id": "DETACH_DISK"
},{
"isEnabled": true,"id": "THIN_PROVISIONED"
},{
"isEnabled": true,"id": "POWER_MANAGEMENT"
},{
"isEnabled": true,"id": "CAPTURE"
},{
"isEnabled": true,"id": "BACKUP"
},{
"isEnabled": false,"id": "SUSPEND_CAPABLE"
},{
"isEnabled": true,"id": "RESIZE"
},{
"isEnabled": false,"id": "PIN"
},{
"isEnabled": false,"id": "UNPIN"
}],"ip": "9.125.13.135, 11.0.0.11","id": "3959","uri": "http://localhost:18080/cloud/api/virtualServers/3959"
}]
}
GET /virtualServers/{id}This service retrieves a virtual server.
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 115
Query Parameters
N/A
Sample Request
Get virtual servers for workload with ID 1:
GET http://host/cloud/api/virtualServers/203
Sample Response
HTTP Status: 200
HTTP Response Body:{
"cloudId": "cloud://551/40052","credentialsUri": "http://localhost:18080/cloud/api/workloads/601/virtualServers/651/credentials","state": {
"label": "Running","id": "RUNNING"
},"backups": "http://localhost:18080/cloud/api/virtualServers/651/backups","properties": [
{"value": "true","id": "Encapsulated","description": "Encapsulated:","category": "General Information"
},{
"value": "TRUE","id": "Memory.ChangeableType","description": "Dynamic memory change capable:","category": "Memory"
},{
"value": "1024","id": "Memory.VirtualLimit","description": "Maximum memory size (MB):","category": "Memory"
},{
"value": "1024","id": "Memory.VirtualMinimum","description": "Minimum memory size (MB):","category": "Memory"
},{
"value": "1024","id": "Memory.VirtualQuantity","description": "Assigned memory size (MB):","category": "Memory"
},{
"value": "kaiqiang-no-delete","id": "Name","description": "Name:","category": "General Information"
},{
"value": "40052","id": "Oid","description": "Cloud object ID:","category": "General Information"
},{
"value": "TRUE","id": "Processor.ChangeableType","description": "Dynamic processor change capable:","category": "Processor"
},
116 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
{"value": "Shared","id": "Processor.ConsumerVisibility","description": "Processing mode:","category": "Processor"
},{
"value": "0.1","id": "Processor.Limit","description": "Maximum processing units:","category": "Processor"
},{
"value": "0.1","id": "Processor.Minimum","description": "Minimum processing units:","category": "Processor"
},{
"value": "System","id": "Processor.PoolID","description": "Shared processor pool:","category": "Processor"
},{
"value": "0.1","id": "Processor.Reservation","description": "Assigned processing units:","category": "Processor"
},{
"value": "1","id": "Processor.VirtualLimit","description": "Maximum processors:","category": "Processor"
},{
"value": "1","id": "Processor.VirtualMinimum","description": "Minimum processors:","category": "Processor"
},{
"value": "1","id": "Processor.VirtualQuantity","description": "Assigned processors:","category": "Processor"
},{
"value": "Medium(128)","id": "Processor.Weight","description": "Assigned share priority:","category": "Processor"
},{
"value": "Started","id": "State","description": "State:","category": "General Information"
},{
"value": "HMC","id": "Vendorinfo.ResourceType","description": "Host type:","category": "Vendor Information"
},{
"value": "FALSE","id": "Vendorinfo.VIOS","description": "Utility virtual server:","category": "Vendor Information"
},{
"value": "AIX or Linux","id": "Vendorinfo.VirtualSystemType","description": "Environment:","category": "Vendor Information"
}],
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 117
"hostname": "kaiqiang-no-delete","storagesUri": "http://localhost:18080/cloud/api/virtualServers/651/storages","capabilities": [
{"isEnabled": true,"id": "CREATE_DISK"
},{
"isEnabled": false,"id": "ATTACH_DISK"
},{
"isEnabled": false,"id": "DETACH_DISK"
},{
"isEnabled": false,"id": "THIN_PROVISIONED"
},{
"isEnabled": true,"id": "POWER_MANAGEMENT"
},{
"isEnabled": true,"id": "CAPTURE"
},{
"isEnabled": true,"id": "BACKUP"
},{
"isEnabled": false,"id": "SUSPEND_CAPABLE"
},{
"isEnabled": true,"id": "RESIZE"
},{
"isEnabled": false,"id": "PIN"
},{
"isEnabled": false,"id": "UNPIN"
}],"ip": "","id": "651","uri": "http://localhost:18080/cloud/api/virtualServers/651"
}
PUT /virtualServers/{id}This service migrates the virtual server to a target host. This service migrates the virtual server to thehost that is automatically selected by OpenStack.
Query Parameters
N/A
Sample Request 1
Migrate the virtual server to the host "samplehost"
PUT http://host/cloud/api/virtualServers/101/
HTTP Request Body:
118 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
{’state’:’MIGRATING’,’target’:’cloud://301/12344’
}
Sample Response 1
HTTP Status: 201
Created HTTP Response Body:{empty}
Sample Request 2
Migrate the virtual server to the host, which is selected by the OpenStack automatically.
PUT http://host/cloud/api/virtualServers/101/
HTTP Request Body:{
’state’:’MIGRATING’,}
Sample Response 2
HTTP Status: 201
Created HTTP Response Body:{empty}
GET /virtualServers/{id}/logThis service retrieves the console logs for a virtual server by ID. The console logs show the virtual serverconsole output. It can provide information about how the virtual server executes. These logs, comedirectly from the Cloud.
Note: Virtual server console logs are currently only obtained from an OpenStack cloud.
Query Parameters
N/A
Sample Request
Get the console log for virtual server 1601
GET http://host/cloud/api/virtualServers/1601/log
Sample Response
The following is an incomplete response shown as an example:
HTTP Status: 200
HTTP Response Body:{"log":"[ 0.000000] Initializing cgroup subsys cpu[ 0.000000] Linux version 3.0.012virtual (buildd@crested) (gcc version 4.6.1 (Ubuntu/Linaro 4.6.19ubuntu3) )
#20Ubuntu SMP Fri Oct 7 18:19:02 UTC 2011 (Ubuntu 3.0.012.20virtual 3.0.4)
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 119
[ 0.000000] Command line: LABEL=cirrosrootfs ro console=tty0 console=ttyS0 console=hvc0[ 0.000000] KERNEL supported cpus:[ 0.000000] Intel GenuineIntel[ 0.000000] AMD AuthenticAMD[ 0.000000] Centaur CentaurHauls[ 0.000000] Disabled fast string operations[ 0.000000] BIOSprovided physical RAM map:[ 0.000000] BIOSe820: 0000000000000000 000000000009dc00 (usable)[ 0.000000] BIOSe820: 000000000009dc00 00000000000a0000 (reserved)[ 0.000000] BIOSe820: 00000000000f0000 0000000000100000 (reserved)[ 0.000000] BIOSe820: 0000000000100000 000000001fffd000 (usable)[ 0.000000] BIOSe820: 000000001fffd000 0000000020000000 (reserved)[ 0.000000] BIOSe820: 00000000fffbc000 0000000100000000 (reserved)"
GET /virtualServers/{id}/storagesThis service retrieves all the storage volumes attached to the virtual server.
Query Parameters
N/A
Sample Request
Get virtual servers for workload with ID 1.
GET http://host/cloud/api/virtualServers/203/storages
Sample Response
HTTP Status: 200
HTTP Response Body:{
"storages":[{
"size":0,"id":"1313","name":"Unknown Storage","uri":"http://localhost:18080/cloud/api/virtualServers/203/storages/1313"
},{
"size":12,"id":"1314","name":"Nate","uri":"http://localhost:18080/cloud/api/virtualServers/203/storages/1314"
}]
}
GET /virtualServers/{id}/storages/{id}This service retrieves a storage volume from the list of all storage volumes attached to the virtual server.
Query Parameters
N/A
Sample Request
Get virtual servers for workload with ID 1.
GET http://host/cloud/api/virtualServers/203/storages/1314
Note: The “thinProvisioned” attribute is returned only for VMware cloud.
120 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
Sample Response
HTTP Status: 200
HTTP Response Body:{
"size":12,
"thinProvisioned":true,
"id":"1314",
"name":"Nate",
"uri":"http://localhost:18080/cloud/api/virtualServers/203/storages/1314"
}
POST /virtualServers/{id}/storagesThis service adds or attaches a storage volume to the virtual server.
Query Parameters
N/A
Sample Request 1
Add the thin provisioned storage volume 'MyDisk' of size 1024 MB (1 GB) to the virtual server. Specially,if the virtual machine belongs to VMware cloud, IBM Cloud Manager with OpenStack will choose thedatastore in which the main disk of the VM is located to create the storage volume. However, if thedatastore does not have enough free space to create it, IBM Cloud Manager with OpenStack will retrieveavailable datastores for this VM and choose the first available datastore to create a storage volume.
Note: The “thinProvisioned” attribute is valid only for VMware cloud).
POST http://host/cloud/api/virtualServers/101/storages
HTTP Request Body:{
"name":"MyDisk","size":1024,"thinProvisioned":"true",
}
Sample Response 1
HTTP Status: 201
Created HTTP Response Body:{empty}
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 121
Sample Request 2
Add the thin provisioned storage volume 'MyDisk' of size 1024 MB (1 GB) to the virtual Server withspecified datastore 'MyDataStore' (available only for VMware cloud). The storage volume is created in thedatastore specified by the user in the request.
POST http://host/cloud/api/virtualServers/101/storages
HTTP Request Body:{
"name":"MyDisk","size":1024,"thinProvisioned":"true","datastore":"MyDataStore"
}
Sample Response 2
HTTP Status: 201
Created HTTP Response Body:{empty}
Sample Request 3
Attach the storage volume 'MyDisk' to the virtual Server with specified datastore 'MyDataStore' and path'/mydisk.vmdk' (available only for VMware cloud).
POST http://host/cloud/api/virtualServers/101/storages
HTTP Request Body:{
"name": "MyDisk","datastore": "MyDataStore""Path": "/mydisk.vmdk"
}
Sample Response 3
HTTP Status: 201
Created HTTP Response Body:{empty}
DELETE /virtualServers/{id}/storages/{id}This service removes a storage volume from the virtual server.
Note: The parameter detachOnly can be used with this API. If it is set to true, the storage being detachedwill not be destroyed, otherwise, the storage being detached will be destroyed after detach action is done.
Query Parameters
N/A
Sample Request
122 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
Delete the storage volume with id '301' from the virtual Server.
DELETE http://host/cloud/api/virtualServers/101/storages/301
HTTP Request Body:
Sample Response
HTTP Status: 200
Deleted HTTP Response Body:{empty}
GET /virtualServers/{id}/networksThis service retrieves all the networks attached to the virtual server.
Query Parameters
N/A
Sample Request
Get networks for virtual servers with ID 101. GET http://host/cloud/api/virtualServers/101/networks
Sample Response
HTTP Status: 200
HTTP Response Body:{
"networks":[{
"name":"Default IP Address Pool","id":"1","dns1":{
"value":"9.5.17.11","label":"DNS 1"
},"dns2":{
"value":"9.5.17.12","label":"DNS 2"
},"gateway1":{
"value":"9.5.40.1","label":"Gateway address"
},"gateway2":{
"value":"9.5.40.2","label":"Alternative gateway address"
},"domain":{
"value":"rchland.ibm.com","label":"Domain name"
},"domainSuffixes":{
"value":"ibm.com,cn.ibm.com","label":"Domain suffix search list"
},"subnet":
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 123
{
"value":"255.255.252.0","label":"Subnet mask"
},"networkId":{
"value":"123","label":"Network ID"
},"useDHCP":{
"value":true,"label":"Use DHCP"
},"wins1":{
"value":"9.5.40.3","label":"Primary WINS address"
},"wins2":{
"value":"9.5.40.4","label":"Secondary WINS address"
},"ipAddress":{
"value":"9.1.2.125","label":"IP address"
},"hostName":{
"value":"hostname1","label":"Host name"
},"computerName":
{
"value":"skc",
"label":"Computer name"},
"workgroup":{
"value":"group","label":"Workgroup"
}},{
"name":"IP Address Pool1","id":"1","dns1":{
"value":"9.5.17.12","label":"DNS 1"
},"dns2":{
"value":"9.5.17.13","label":"DNS 2"
},"gateway1":{
"value":"9.5.40.1","label":"Gateway address"
},"gateway2":{
"value":"9.5.40.2","label":"Alternative gateway address"
},"domain":{
"value":"rchland.ibm.com","label":"Domain name"
},"domainSuffixes":{
124 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
"value":"ibm.com,cn.ibm.com","label":"Domain suffix search list"
},"subnet":{
"value":"255.255.252.0","label":"Subnet mask"
},"networkId":{
"value":"123","label":"Network ID"
},"useDHCP":{
"value":true,"label":"Use DHCP"
},"wins1":{
"value":"9.5.40.3","label":"Primary WINS address"
},"wins2":{
"value":"9.5.40.4","label":"Secondary WINS address"
},"ipAddress":{
"value":"9.1.2.126","label":"IP address"
},"hostName":{
"value":"hostname1","label":"Host name"
},"computerName":
{
"value":"skc1",
"label":"Computer name"},
"workgroup":{
"value":"group2","label":"Workgroup"
}}
]}
GET /virtualServers/{id}/networks/{id}This service retrieves a network attached to the virtual server.
Query Parameters
N/A
Sample Request
Get networks with ID 202 for virtual servers with ID 101.
GET http://host/cloud/api/virtualServers/101/networks/202
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 125
Sample Response
HTTP Status: 200
HTTP Response Body:{
"name":"Default IP Address Pool","id":"1","dns1":{
"value":"9.5.17.11","label":"DNS 1"
},"dns2":{
"value":"9.5.17.12","label":"DNS 2"
},"gateway1":{
"value":"9.5.40.1","label":"Gateway address"
},"gateway2":{
"value":"9.5.40.2","label":"Alternative gateway address"
},"domain":{
"value":"rchland.ibm.com","label":"Domain name"
},"domainSuffixes":{
"value":"ibm.com,cn.ibm.com","label":"Domain suffix search list"
},"subnet":{
"value":"255.255.252.0","label":"Subnet mask"
},"networkId":{
"value":"123","label":"Network ID"
},"useDHCP":{
"value":true,"label":"Use DHCP"
},"wins1":{
"value":"9.5.40.3","label":"Primary WINS address"
},"wins2":{
"value":"9.5.40.4","label":"Secondary WINS address"
},"ipAddress":{
"value":"9.1.2.125","label":"IP address"
},"hostName":{
"value":"hostname1","label":"Host name"
},"computerName":
{"value":"skc",
126 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
"label":"Computer name"},
"workgroup":{
"value":"group","label":"Workgroup"
}}
GET /virtualServers/{id}/backupsThis service retrieves all saved server images associated with a virtual server.
Query Parameters
N/A
Sample Request
Get saved server images for virtual server with the id 203.
GET http://host/cloud/api/virtualServers/203/backups
Sample Response
HTTP Status: 200
HTTP Response Body:{
"backups":[{
"id":"505","name":"os installed","description":"RHEL 5.5 installed, not configured","uri":"http://localhost:18080/cloud/api/virtualServers/203/backups/505","creationDate":1312298597963
},{
"id":"506","name":"after xyz was installed","description":"","uri":"http://localhost:18080/cloud/api/virtualServers/203/backups/506","creationDate":1312298895370
}]
}
GET /virtualServers/{id}/backups/{id}This service retrieves a specific saved server image associated with a virtual server.
Query Parameters
N/A
Sample Request
Get saved server image with the id 505 for virtual server with the id 203.
GET http://host/cloud/api/virtualServers/203/backups/505
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 127
Sample Response
HTTP Status: 200
HTTP Response Body:{
"id":"505","name":"os installed","description":"RHEL 5.5 installed, not configured","uri":"http://localhost:18080/cloud/api/virtualServers/203/backups/505","creationDate":1312298597963
}
POST /virtualServers/{id}/backupsThis service creates a new saved server image for the virtual server.
Note: This API cannot be used to backup an OpenStack PowerVM instance.
Query Parameters
N/A
Sample Request
Create a new saved server image for virtual server with the id 203.
POST http://host/cloud/api/virtualServers/203/backups{
"name" : "name for saved server image","description" : "description of image"
}
Sample Response
HTTP Status: 201 Created
Response Body: {empty}
PUT /virtualServers/{id}/backups/{id}This service restores the virtual server using the specified saved server image.
Note: If this API is called to restore an OpenStack PowerVM instance by using a saved server image, anerror message that this service is not supported appears.
Query Parameters
N/A
Sample Request
Restore the virtual server with the id 203 using the saved server image with the id 505.
PUT http://host/cloud/api/virtualServers/203/backups/505{
"state": "RESTORING"}
128 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
Sample Response
HTTP Status: 200 OK
Response Body: {empty}
DELETE /virtualServers/{id}/backups/{id}This service deletes the specified saved server image associated with a virtual server.
Query Parameters
N/A
Sample Request
Delete saved server image with the id 505 for virtual server with the ID 203.
DELETE http://host/cloud/api/virtualServers/203/backups/505
Sample Response
HTTP Status: 200 OK
Response Body: {empty}
GET /virtualServers/{id}/repositoriesThis service retrieves all valid repositories that can be used to capture the virtual server.
Query Parameters
N/A
Sample Request
Get valid image repositories for virtual server with ID 203.GEThttp://host/cloud/api/virtualServers/203/repositories
Sample Response
HTTP Status: 200
HTTP Response Body:{
"total": "1","repositories": [
{"cloudId": "11632","name": "image_repository"
}],"identifier": "cloudId"
}
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 129
GET /virtualServers/{id}/repositories/{id}/customizationThis service retrieves customization that is associated with the virtual server and the image repository.The customization includes the information that is needed to capture the virtual server to the imagerepository.
Query Parameters
N/A
Sample Request
Get customization for virtual server with ID 203 and image repository with ID 102.GEThttp://host/cloud/api/virtualServers/203/repositories/102/customization
Sample Response
HTTP Status: 200
HTTP Response Body:{
"properties": [{
"values": [ ],"type": "SINGLE_SELECTION","name": "ostypecapture","description": "Specify OS Type for capture","basic": false,"options": [
{"value": "Linux","id": "36"
},{
"value": "AIX","id": "9"
}],"required": false
}],"appliance": {
"name": "Unknown"},"instances": 1
}
Workload servicesIBM Cloud Manager with OpenStack provides the workload services listed here.Related information:“Code license and disclaimer information” on page 208
GET /multiWorkloads/{id}This service retrieves all the workloads within a multi-workload by ID.
130 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
While deploying a workload with instances number greater than one, self-service portal will generate amulti-workload and have sub-workloads associated with it. The API returns the sub-workloads for thespecified multi-workload. If a multi-workload by the given ID doesn't exist, the service will return a 404.
Query Parameters
N/A
Sample Request
To retrieve all workloads within multi-workload ID 1:
GET http://host/cloud/api/multiWorkloads/1
Sample Response
HTTP Status: 200
HTTP Response Body:{
"total": "2","workloads": [
{"cloudId": "cloud://351/2eaf0bfd-cc3f-4240-99ea-e2398a2ff421","executionDate": 1413868952245,"projectUri": "http://localhost:18080/cloud/api/projects/51","cloudGroupId": "351","cloudGroupName": "VMWARECLOUD","state": {
"id": "EXECUTING","label": "Deploying"
},"architecture": "x86","instances": 1,"uri": "http://localhost:18080/cloud/api/workloads/2652","id": "2652","isHidden": false,"hypervisor": "VMware","name": "MultipeDeployment-1","owner": {
"username": "admin","name": "Administrator"
},"projectName": "Public"
},{
"cloudId": "cloud://351/41b27a44-78b5-42a2-842f-1751a3a9e867","executionDate": 1413868966916,"projectUri": "http://localhost:18080/cloud/api/projects/51","cloudGroupId": "351","cloudGroupName": "VMWARECLOUD","state": {
"id": "EXECUTING","label": "Deploying"
},"architecture": "x86","instances": 1,"uri": "http://localhost:18080/cloud/api/workloads/2653","id": "2653","isHidden": false,"hypervisor": "VMware","name": "MultipeDeployment-2","owner": {
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 131
"username": "admin","name": "Administrator"
},"projectName": "Public"
}]
}
GET /workloadsThis service retrieves a list with the summary of all the known workloads available in the cloud.
Query Parameters
Name Description Default Required
user Gets the list of workloadsfor the specified user.
N/A No
includeHidden Specifies whether returnedworkloads should includehidden workloads.
false No
owner Filters the list of workloadsby the specified owner.
* No
start The index of the firstrecords to return.
0 No
count The number of records toreturn.
0 No
architecture Filters the list of workloadsby the specified platformarchitecture.
* No
cloudGroupId Filters the list of workloadsby the specifiedcloudGroupId.
* No
Sample Request
Get all known workloads:
GET http://host/cloud/api/workloads
Sample Response
HTTP Status: 200
HTTP Response Body:{
"total": "44","workloads": [
{"cloudName": "host122-win2k3_host_2_10","cloudGroupId": "352","name": "host122-win2k3_host_2_10","uri": "http://localhost:18080/cloud/api/workloads/60351","cloudId": "cloud://352/422ea1c0-d1ae-961e-095d-3b96ba3b1601","state": {
"label": "Unknown","id": "UNKNOWN"
},"projectUri": "http://localhost:18080/cloud/api/projects/151","architecture": "x86",
132 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
"isHidden": false,"cloudGroupName": "VMware-120","hypervisor": "VMware","id": "60351","description": "Workload could no longer be found in the Cloud.It could have been purposely deleted from the Cloud."
},{
"cloudName": "DHCP&DNS(inner)_RHEL61_64Bit_hgq(Not Delete)","cloudGroupId": "352","name": "DHCP&DNS(inner)_RHEL61_64Bit_hgq(Not Delete)","uri": "http://localhost:18080/cloud/api/workloads/37452","cloudId": "cloud://352/422ed793-b6cb-46a7-53e7-59d39d66d322","state": {"label": "OK","id": "OK"
},"projectUri": "http://localhost:18080/cloud/api/projects/151","architecture": "x86","isHidden": false,"cloudGroupName": "VMware-120","hypervisor": "VMware","id": "37452","description": "Workload could no longer be found in the Cloud.
It could have been purposely deleted from the Cloud."}]
}
POST /workloadsThis service creates a new workload. Creating a workload does not mean executing it. When a workloadis created it means that a workload is prepared for its eventual execution given the current resources inthe cloud.
A workload has name, description, a project it belongs to and specific workload properties specific to thebase appliance. The workload properties are contained in what we call a customization. Creating aworkload requires a base appliance and in that case the appliance ID is required; it is also possible tocreate a workload from an existing workload, or recreating a workload, in that case the base workload IDis required.
Important: After you create a workload, the workload will not automatically appear in the IBM CloudManager with OpenStack graphical user interface. The workload will also not appear in any workloadlists returned by APIs. In order for the workload to appear in the graphical user interface and in listsreturned by APIs, you must use the “PUT /workloads/{id}” on page 159 service to execute the workload.
All workloads created under IBM Cloud Manager with OpenStack need to be associated to a project.Workloads have a visibility attribute that determined whether the workload can only be seen by themembers of the project, or also by any IBM Cloud Manager with OpenStack user. The default visibility isPROJECT.
Query Parameters
N/A
Sample Requests1. Create a new workload for appliance ID 133.
POST http://host/cloud/api/workloads{
"appliance":133}
2. Create a new workload from an existing workload with ID 156.POST workload from an existing workload with ID 156.
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 133
"http://host/cloud/api/workloads">http://host/cloud/api/workloads{
"workload":156}
Sample Response
HTTP Status: 201
HTTP Location Header: The URI of the new workload
HTTP Body: The customization to avoid back and forth requests to the server. The returnedcustomization not only contains the customization properties from the managed clouds, but also the IBMCloud Manager with OpenStack core generated properties that are named storagemapping-N, whichstands for the storage mapping for each disk. The values field is the default value that is recommendedby the IBM Cloud Manager with OpenStack core. You can also complete the values field to specify amapping to a specific storage pool for this disk.{
"target": "cloud://352/host-875","properties": [
{"values": [
"{1}"],"classification": {
"label": "Network","id": "NETWORK"
},"valueOrigin": [
"{1}"],"subtype": "HOST_NAME","type": "STRING","valueFrom": "ipAddress","name": "linux.hostname","description": "Host name","category": "TCP/IP Network Settings ","basic": true,"required": false
},{
"values": ["{1}"
],"classification": {
"label": "Network","id": "NETWORK"
},"valueOrigin": [
"{1}"],"subtype": "DOMAIN_NAME","type": "STRING","valueFrom": "domain","name": "linux.domainname","description": "Domain name","category": "TCP/IP Network Settings ","basic": true,"required": true
},{
"values": ["{1}"
],"classification": {
"label": "Network","id": "NETWORK"
},"valueOrigin": [
"{1}"],"subtype": "IPV4_ADDRESS",
134 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
"type": "STRING","valueFrom": "dns1","name": "linux.dns1","description": "Primary DNS","category": "TCP/IP Network Settings ","basic": false,"required": false
},{
"values": ["{1}"
],"classification": {
"label": "Network","id": "NETWORK"
},"valueOrigin": [
"{1}"],"subtype": "IPV4_ADDRESS","type": "STRING","valueFrom": "dns2","name": "linux.dns2","description": "Backup DNS","category": "TCP/IP Network Settings ","basic": false,"required": false
},{
"values": ["{1}"
],"classification": {
"label": "Network","id": "NETWORK"
},"valueOrigin": [
"{1}"],"subtype": "DOMAIN_NAMES","type": "STRING","valueFrom": "domainSuffixes","name": "dnssuffixlist","description": "Domain name server suffix list (comma separated)","category": "TCP/IP Network Settings ","basic": false,"required": false
},{
"values": [4345
],"classification": {
"label": "Storage","id": "STORAGE"
},"rules": [
{"value": "1","id": "increment"
},{
"value": "LINEAR","id": "incrementType"
},{
"value": "2097151","id": "max"
},{
"value": "4345","id": "min"
}],"type": "LONG","name": "DiskSize.Hard disk 1","description": "Disk Size of Hard disk 1 (MB)","category": "Storage Settings","basic": false,
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 135
"required": false},{
"values": ["skc.default.storage"
],"classification": {
"label": "Storage","id": "STORAGE"
},"type": "SINGLE_SELECTION","name": "target.storage","description": "Target Storage","category": "Storage Settings","basic": false,"options": [
{"value": "Default","id": "skc.default.storage"
},{
"value": "xBLADE_Server_01_DS5020_DISK","id": "xBLADE_Server_01_DS5020_DISK"
}],"required": false
},{
"values": [1024
],"classification": {
"label": "Hardware","id": "HARDWARE"
},"rules": [
{"value": "4","id": "increment"
},{
"value": "LINEAR","id": "incrementType"
},{
"value": "128","id": "min"
}],"type": "LONG","name": "vmware.memory","description": "Memory (MB)","category": "Memory and CPU Settings","basic": true,"required": false
},{
"values": [1
],"classification": {
"label": "Hardware","id": "HARDWARE"
},"rules": [
{"value": "1","id": "increment"
},{
"value": "LINEAR","id": "incrementType"
},{
"value": "12","id": "max"
},{
"value": "1",
136 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
"id": "min"}
],"type": "LONG","name": "vmware.cpu","description": "Virtual CPUs","category": "Memory and CPU Settings","basic": true,"required": false
},{
"values": ["VM Network"
],"classification": {
"label": "Network","id": "NETWORK"
},"valueOrigin": [
"VM Network"],"type": "SINGLE_SELECTION","valueFrom": "networkId","name": "networkdevice.Network adapter 1.network","description": "Network associated with Network adapter 1","category": "Network adapter 1","basic": false,"options": [
{"value": "VM Network","id": "VM Network"
}],"group": "Adapter 1","required": true
},{
"values": [false
],"classification": {
"label": "Network","id": "NETWORK"
},"valueOrigin": [
false],"subtype": "DHCP_FLAG","type": "BOOLEAN","valueFrom": "useDHCP","name": "networkdevice.Network adapter 1.usedhcp","description": "Use DHCP for Network adapter 1","category": "Network adapter 1","basic": false,"group": "Adapter 1","required": false
},{
"values": ["{1}"
],"classification": {
"label": "Network","id": "NETWORK"
},"valueOrigin": [
"{1}"],"subtype": "IPV4_ADDRESS","type": "STRING","valueFrom": "ipAddress","name": "networkdevice.Network adapter 1.ipaddress","description": "IP address for Network adapter 1","category": "Network adapter 1","basic": false,"group": "Adapter 1","required": true
},{
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 137
"values": ["{1}"
],"classification": {
"label": "Network","id": "NETWORK"
},"valueOrigin": [
"{1}"],"subtype": "IPV4_SUBNET_MASK","type": "STRING","valueFrom": "subnet","name": "networkdevice.Network adapter 1.netmask","description": "Subnet mask for Network adapter 1","category": "Network adapter 1","basic": false,"group": "Adapter 1","required": true
},{
"values": ["{1}"
],"classification": {
"label": "Network","id": "NETWORK"
},"valueOrigin": [
"{1}"],"subtype": "IPV4_ADDRESS","type": "STRING","valueFrom": "gateway1","name": "networkdevice.Network adapter 1.gateway1","description": "Default gateway for Network adapter 1","category": "Network adapter 1","basic": false,"group": "Adapter 1","required": false
},{
"values": [true
],"classification": {
"label": "Network","id": "NETWORK"
},"valueOrigin": [
true],"subtype": "DNS_FLAG","type": "BOOLEAN","valueFrom": "obtainFromDNS","name": "obtainFromDNS.network1","description": "Obtain hostname and domain name from DNS server","category": "Network adapter 1","basic": false,"group": "Adapter 1","required": false
}],"id": "73512","appliance": {
"name": "RHEL6_Template121","uri": "http://localhost:18080/cloud/api/appliances/37701"
}}
You can view the customization details in the “GET /workloads/{id}/customization” on page 139 APIdescription.
GET /workloads/{id}This service retrieves a workload by ID.
138 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
If the workloads was created using IBM Cloud Manager with OpenStack, the returned workload willinclude a customization, otherwise it won't. Workloads may or may not include a virtual serverassociated with them, depending on whether the workload has already been attempted or is still in draftmode, and if the workload was attempted whether or not it was successful.
Query Parameters
N/A
Sample Request
Get workload with ID 1:
GET http://host/cloud/api/workloads/1
Sample Response
HTTP Status: 200
HTTP Response Body:{
"cloudName": "RHEL6_Template121 2012-07-03 12:41:05 test_ly_by_testUser","priority": 2,"cloudGroupId": "352","executionDate": 1341290499109,"virtualServersUri": "http://localhost:18080/cloud/api/workloads/73508/virtualServers","name": "RHEL6_Template121 2012-07-03 12:41:05 test_ly_by_testUser","uri": "http://localhost:18080/cloud/api/workloads/73508","timestampsUri": "http://localhost:18080/cloud/api/workloads/73508/timestamps","cloudId": "cloud://352/e7e213c5-4c6f-416b-9642-baa5ae6549cc","state": {
"label": "OK","id": "OK"
},"architecture": "x86","projectUri": "http://localhost:18080/cloud/api/projects/103001","isHidden": false,"cloudGroupName": "VMware-120","hypervisor": "VMware","customizationUri": "http://localhost:18080/cloud/api/workloads/73508/customization","targetUri": "http://localhost:18080/cloud/api/workloads/73508/target","id": "73508","description": "RHEL6_Template121 2012-07-03 12:41:05 test_ly_by_testUser","logsUri": "http://localhost:18080/cloud/api/workloads/73508/log"
}
GET /workloads/{id}/customizationThis service retrieves customization for a workload by ID.
A workload's customization includes the workload's virtualization properties used to execute thisparticular workload on the cloud. This service can also return the dynamic virtualization properties,which are the properties that can be used to modify this workload at runtime. You can, for example,change the allotted CPU.
Query Parameters
Name Description Default Required
dynamicProperties Return the dynamicvirtualization properties forthis workload.
false No
priority Return the priorityproperty of this workload.
false No
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 139
Sample Request
To retrieve the customization for workload with ID 1 GET http://host/cloud/api/workloads/1/customization
Sample Response{
"target":"cloud://default/6678","properties":[
{"values":[
"1"],"rules":[
{"value":"1","id":"increment"
},{
"value":"LINEAR","id":"incrementType"
},{
"value":"240.0","id":"max"
},{
"value":"1.0","id":"min"
}],"type":"LONG","name":"cpushared","description":"The desired number of dedicated orvirtual processors to be assigned to the virtual server.",
"basic":false,"required":true
},{
"values":["1"
],"rules":[
{"value":"1","id":"increment"
},{
"value":"LINEAR","id":"incrementType"
},{
"value":"128.0","id":"max"
},{
"value":"1.0","id":"min"
}],"type":"LONG","name":"cpudedicated","description":"The desired number of dedicated or virtual processors to beassigned to the virtual server.",
"basic":false,"required":true
},{
"values":["SHARED"
],"type":"SINGLE_SELECTION","name":"cpumode",
140 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
"description":"Indicates whether the virtual server will use physical orvirtual processors (dedicated or shared mode).",
"basic":false,"options":[
{"value":"Dedicated","id":"DEDICATED"
},{
"value":"Shared","id":"SHARED"
}],"required":true
},{
"values":["512"
],"rules":[
{"value":"256","id":"increment"
},{
"value":"LINEAR","id":"incrementType"
},{
"value":"160512.0","id":"max"
},{
"value":"256.0","id":"min"
}],"type":"LONG","name":"memsize","description":"The desired amount of memory (MB) to be assigned to the virtual server.","basic":false,"required":true
},{
"values":[false
],"type":"BOOLEAN","name":"suspendresume","description":"The virtual server can be suspended and resumed later.","basic":false,"required":false
},{
"values":["2048"
],"rules":[
{"value":"256","id":"increment"
},{
"value":"LINEAR","id":"incrementType"
},{
"value":"160512.0","id":"max"
},{
"value":"256.0","id":"min"
}],"type":"LONG","name":"memmax","description":"The maximum amount of memory (MB) that can be assigned to the virtual server.","basic":false,
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 141
"required":true},{
"values":["512"
],"rules":[
{"value":"256","id":"increment"
},{
"value":"LINEAR","id":"incrementType"
},{
"value":"160512.0","id":"max"
},{
"value":"256.0","id":"min"
}],"type":"LONG","name":"memmin","description":"The minimum amount of memory (MB) that can be assigned to the virtual server.","basic":false,"required":true
},{
"values":["1"
],"rules":[
{"value":"1","id":"increment"
},{
"value":"LINEAR","id":"incrementType"
},{
"value":"240.0","id":"max"
},{
"value":"1.0","id":"min"
}],"type":"LONG","name":"cpushmin","description":"The minimum number of dedicated or virtual processors that can be assigned to the virtual server.","basic":false,"required":false
},{
"values":["0.1"
],"rules":[
{"value":"0.1","id":"increment"
},{
"value":"24.0","id":"max"
},{
"value":"0.1","id":"min"
}],"type":"FLOAT","name":"cpushminu","description":"The minimum number of processing units that can be assigned to the virtual server.",
142 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
"basic":false,"required":false
},{
"values":["0.1"
],"rules":[
{"value":"0.1","id":"increment"
},{
"value":"24.0","id":"max"
},{
"value":"0.1","id":"min"
}],"type":"FLOAT","name":"cpushu","description":"The desired number of processing units to be assigned to the virtual server.","basic":false,"required":false
},{
"values":["1"
],"rules":[
{"value":"1","id":"increment"
},{
"value":"LINEAR","id":"incrementType"
},{
"value":"240.0","id":"max"
},{
"value":"1.0","id":"min"
}],"type":"LONG","name":"cpushmax","description":"The maximum number of dedicated or virtual processors that can be assigned to the virtual server.","basic":false,"required":false
},{
"values":["1"
],"rules":[
{"value":"0.1","id":"increment"
},{
"value":"24.0","id":"max"
},{
"value":"0.1","id":"min"
}],"type":"FLOAT","name":"cpushmaxu","description":"The maximum number of processing units that can be assigned to the virtual server.","basic":false,"required":false
},
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 143
{"values":[
"UNCAP"],"type":"SINGLE_SELECTION","name":"cpushmode","description":"The processing units sharing mode of the virtual server.","basic":false,"options":[
{"value":"Capped","id":"CAP"
},{
"value":"Uncapped","id":"UNCAP"
}],"required":false
},{
"values":["128"
],"rules":[
{"value":"1","id":"increment"
},{
"value":"LINEAR","id":"incrementType"
},{
"value":"255.0","id":"max"
},{
"value":"0.0","id":"min"
}],"type":"LONG","name":"cpushpri","description":"The priority of the virtual server to available processing units in the shared processor pool.","basic":false,"required":false
},{
"values":["1"
],"rules":[
{"value":"1","id":"increment"
},{
"value":"LINEAR","id":"incrementType"
},{
"value":"24.0","id":"max"
},{
"value":"1.0","id":"min"
}],"type":"LONG","name":"cpudedmin","description":"The minimum number of dedicated or virtual processors that can be assigned to the virtual server.","basic":false,"required":false
},{
"values":["1"
144 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
],"rules":[
{"value":"1","id":"increment"
},{
"value":"LINEAR","id":"incrementType"
},{
"value":"128.0","id":"max"
},{
"value":"1.0","id":"min"
}],"type":"LONG","name":"cpudedmax","description":"The maximum number of dedicated or virtual processors that can be assigned to the virtual server.","basic":false,"required":false
},{
"values": ["2"
],"type": "SINGLE_SELECTION","name": "priority","description": "Workload Priority","basic": false,"options": [
{"value": "1 (High)","id": "1"
},{"value": "2 (Normal)","id": "2"
},{"value": "3 (Low)","id": "3"
},{"value": "4 (Lowest)","id": "4"
}],"required": false
},{
"values":["192-168-2-183"
],"classification":{
"label":"Network","id":"NETWORK"
},"valueOrigin": ["{1}"],"subtype":"HOST_NAME","type":"STRING","valueFrom": "hostnamePrefix","name":"product.AIX1.com.ibm.ovf.vim.2.system.hostname","description":"Short hostname for the system.","category":"TCP/IP Network Settings","basic":false,"required":false
},{
"values":["icb.cloud.com"
],"valueOrigin": ["{1}"
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 145
],"classification":{
"label":"Network","id":"NETWORK"
},"subtype":"DOMAIN_NAME","type":"STRING","valueFrom": "domain","name":"product.AIX1.com.ibm.ovf.vim.2.system.domainname","description":"DNS domain name for the system.","category":"TCP/IP Network Settings","basic":false,"required":false
},{
"values":["192.168.1.17"
],"classification":{
"label":"Network","id":"NETWORK"
},"valueOrigin": ["{1}"],"subtype":"IPV4_ADDRESS","type":"STRING","valueFrom": "dns1","name":"product.AIX1.com.ibm.ovf.vim.2.system.dns1.ip","description":"IP address of primary DNS server for system.","category":"TCP/IP Network Settings","basic":false,"required":false
},{
"values":["192.168.1.17"
],"classification":{
"label":"Network","id":"NETWORK"
},"valueOrigin": ["{1}"],"subtype":"IPV4_ADDRESS","type":"STRING","valueFrom": "dns2","name":"product.AIX1.com.ibm.ovf.vim.2.system.dns2.ip","description":"IP address of secondary DNS server for system.","category":"TCP/IP Network Settings","basic":false,"required":false
},{
"values":["192.168.2.183"
],"classification":{
"label":"Network","id":"NETWORK"
},"valueOrigin": ["{1}"],"subtype":"IPV4_ADDRESS","type":"STRING","valueFrom": "ipAddress","name":"product.AIX1.com.ibm.ovf.vim.2.networkport.6.ip","description":"Static IP address for the network adapter on \"Network 1\".","category":"TCP/IP Network Settings","basic":false,"group":"Adapter 1","required":true
},{
"values":["false"
],
146 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
"type":"STRING","name":"product.AIX1.com.ibm.ovf.vim.2.networkport.6.ipv6autoconf","description":"Use IPv6 stateless address autoconfiguration on \"Network 1\".","category":"TCP/IP Network Settings","basic":false,"required":false
},{
"values":["192.168.1.17"
],"classification":{
"label":"Network","id":"NETWORK"
},"valueOrigin": ["{1}"],"subtype":"IPV4_ADDRESS","type":"STRING","name":"product.AIX1.com.ibm.ovf.vim.2.networkport.6.gateway","description":"Static default gateway for the network adapter on \"Network 1\".","category":"TCP/IP Network Settings","basic":false,"group":"Adapter 1","required":true
},{
"values":["255.255.0.0"
],"classification":{
"label":"Network","id":"NETWORK"
},"valueOrigin": ["{1}"],"subtype":"IPV4_SUBNET_MASK","type":"STRING","valueFrom": "subnet","name":"product.AIX1.com.ibm.ovf.vim.2.networkport.6.netmask","description":"Static network mask for the network adapter on \"Network 1\".","category":"TCP/IP Network Settings","basic":false,"group":"Adapter 1","required":true
},{
"values":["10.10.2.185"
],"classification":{
"label":"Network","id":"NETWORK"
},"valueOrigin": ["{2}"],"subtype":"IPV4_ADDRESS","type":"STRING","valueFrom": "ipAddress","name":"product.AIX1.com.ibm.ovf.vim.2.networkport.7.ip","description":"Static IP address for the network adapter on \"Network 2\".","category":"TCP/IP Network Settings","basic":false,"group":"Adapter 2","required":true
},{
"values":["false"
],"type":"STRING","name":"product.AIX1.com.ibm.ovf.vim.2.networkport.7.ipv6autoconf","description":"Use IPv6 stateless address autoconfiguration on \"Network 2\".","category":"TCP/IP Network Settings","basic":false,"required":false
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 147
},{
"values":["192.168.1.17"
],"classification":{
"label":"Network","id":"NETWORK"
},"valueOrigin": ["{2}"],"subtype":"IPV4_ADDRESS","type":"STRING","valueFrom": "gateway1","name":"product.AIX1.com.ibm.ovf.vim.2.networkport.7.gateway","description":"Static default gateway for the network adapter on \"Network 2\".","category":"TCP/IP Network Settings","basic":false,"group":"Adapter 2","required":true
},{
"values":["255.255.0.0"
],"classification":{
"label":"Network","id":"NETWORK"
},"valueOrigin": ["{2}"],"subtype":"IPV4_SUBNET_MASK","type":"STRING","valueFrom": "subnet","name":"product.AIX1.com.ibm.ovf.vim.2.networkport.7.netmask","description":"Static network mask for the network adapter on \"Network 2\".","category":"TCP/IP Network Settings","basic":false,"group":"Adapter 2","required":true
},{
"values":["[Network 1]=hostVnet:ETHERNET0/1"
],"classification":{
"label":"Network","id":"NETWORK"
},"valueOrigin": ["{1}"],"type":"SINGLE_SELECTION","valueFrom": "networkId","name":"virtualnetworks-1","description":" Network 1\"","basic":false,"options":[
{"values":[
{"value":"Network 1","description":"Network Name"
},{
"value":"Captured from virtual server 192-168-2-34 connected to VLAN 1 on host ICB-CPT1","description":"Description"
},{
"value":"VLAN 1, Bridged","description":"Virtual Networks on Host"
}],"id":"[Network1]=hostVnet:ETHERNET0/1"
},{
"values":[
148 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
{"value":"Network 1","description":"Network Name"
},{
"value":"Captured from virtual server 192-168-2-34 connected to VLAN 1 on host ICB-CPT1","description":"Description"
},{
"value":"VLAN 2, Bridged","description":"Virtual Networks on Host"
}],"id":"[Network1]=hostVnet:ETHERNET0/2"
},{
"values":[{
"value":"Network 1","description":"Network Name"
},{
"value":"Captured from virtual server 192-168-2-34 connected to VLAN 1 on host ICB-CPT1","description":"Description"
},{
"value":"VLAN 3, Bridged","description":"Virtual Networks on Host"
}],"id":"[Network1]=hostVnet:ETHERNET0/3"
},{
"values":[{
"value":"Network 1","description":"Network Name"
},{
"value":"Captured from virtual server 192-168-2-34 connected to VLAN 1 on host ICB-CPT1","description":"Description"
},{
"value":"VLAN 91, Not Bridged","description":"Virtual Networks on Host"
}],"id":"[Network1]=hostVnet:ETHERNET0/91"
},{
"values":[{
"value":"Network 1","description":"Network Name"
},{
"value":"Captured from virtual server 192-168-2-34 connected to VLAN 1 on host ICB-CPT1","description":"Description"
},{
"value":"VLAN 92, Not Bridged","description":"Virtual Networks on Host"
}],"id":"[Network1]=hostVnet:ETHERNET0/92"
},{
"values":[{
"value":"Network 1","description":"Network Name"
},{
"value":"Captured from virtual server 192-168-2-34 connected to VLAN 1 on host ICB-CPT1","description":"Description"
},{
"value":"VLAN 93, Not Bridged","description":"Virtual Networks on Host"
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 149
}],"id":"[Network1]=hostVnet:ETHERNET0/93"
}],"group":"Adapter 1","required":false
},{
"values":["[Network 2]=hostVnet:ETHERNET0/2"
],"classification":{
"label":"Network","id":"NETWORK"
},"valueOrigin": ["{2}"],"type":"SINGLE_SELECTION","valueFrom": "networkId","name":"virtualnetworks-2","description":" Network 2\"","basic":false,"options":[
{"values":[
{"value":"Network 2","description":"Network Name"
},{
"value":"Captured from virtual server 192-168-2-34 connected to VLAN 2 on host ICB-CPT1","description":"Description"
},{
"value":"VLAN 1, Bridged","description":"Virtual Networks on Host"
}],"id":"[Network2]=hostVnet:ETHERNET0/1"
},{
"values":[{
"value":"Network 2","description":"Network Name"
},{
"value":"Captured from virtual server 192-168-2-34 connected to VLAN 2 on host ICB-CPT1","description":"Description"
},{
"value":"VLAN 2, Bridged","description":"Virtual Networks on Host"
}],"id":"[Network2]=hostVnet:ETHERNET0/2"
},{
"values":[{
"value":"Network 2","description":"Network Name"
},{
"value":"Captured from virtual server 192-168-2-34 connected to VLAN 2 on host ICB-CPT1","description":"Description"
},{
"value":"VLAN 3, Bridged","description":"Virtual Networks on Host"
}],"id":"[Network2]=hostVnet:ETHERNET0/3"
},{
"values":[{
150 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
"value":"Network 2","description":"Network Name"
},{
"value":"Captured from virtual server 192-168-2-34 connected to VLAN 2 on host ICB-CPT1","description":"Description"
},{
"value":"VLAN 91, Not Bridged","description":"Virtual Networks on Host"
}],"id":"[Network2]=hostVnet:ETHERNET0/91"
},{
"values":[{
"value":"Network 2","description":"Network Name"
},{
"value":"Captured from virtual server 192-168-2-34 connected to VLAN 2 on host ICB-CPT1","description":"Description"
},{
"value":"VLAN 92, Not Bridged","description":"Virtual Networks on Host"
}],"id":"[Network 2]=hostVnet:ETHERNET0/92"
},{
"values":[{
"value":"Network 2","description":"Network Name"
},{
"value":"Captured from virtual server 192-168-2-34 connected to VLAN 2 on host ICB-CPT1","description":"Description"
},{
"value":"VLAN 93, Not Bridged","description":"Virtual Networks on Host"
}],"id":"[Network2]=hostVnet:ETHERNET0/93"
}],"group":"Adapter 2","required":false
},{
"values":["1"
],"rules":[
{"value":"1","id":"increment"
},{
"value":"LINEAR","id":"incrementType"
},{
"value":"240.0","id":"max"
},{
"value":"1.0","id":"min"
}],"type":"LONG","name":"cskCPU","description":"CPU","basic":true,"required":false
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 151
},{
"values":["512"
],"rules":[
{"value":"256","id":"increment"
},{
"value":"LINEAR","id":"incrementType"
},{
"value":"160512.0","id":"max"
},{
"value":"256.0","id":"min"
}],"type":"LONG","name":"cskRAM","description":"RAM","basic":true,"required":false
},{
"values":[true
],"classification":{
"label":"Network","id":"NETWORK"
},"valueOrigin": [true],"subtype":"DNS_FLAG","type":"BOOLEAN","valueFrom": "obtainFromDNS","name":"obtainFromDNS.network1","description":"Obtain hostname and domain name from DNS server","category":"TCP/IP Network Settings","basic":false,"group":"Adapter 1","required":false
},],"id":"402","appliance":{
"name":"NewSampleImageSCS","uri":"http://adminconsole.ppd.pok.ibm.com:18080/cloud/api/appliances/104"
}}
GET /workloads/{id}/targetThis service retrieves the a workload's target for a workload by ID.
A workload's target includes the id, name, and type of the target. Also, it contains any target metricspresent at the time of the request.
Query Parameters
N/A
Sample Request
To retrieve the workload target for workload with ID 1 GET http://host/cloud/api/workloads/1/target
152 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
Sample Response
HTTP Status: 200
HTTP Response Body:{
"id": 5416,"name": "Host 1 (Host)","metrics": [
{"id": "342abc","name": "CPU Utilization","type": "Percent","value": "30","timestamp": 1223456789"duration": "13245""status": "Valid""dataProperties": { ... }
}]
}
GET /workloads/{id}/logThis service retrieves a workload logs for a workload by ID.
The workload logs show the cloud log messages for a workload execution. It may provide some moreinformation about why a workload failed. We do not have control over these logs, they come directlyfrom the cloud.
Query Parameters
N/A
Sample Request
Get workload log for workload 1.
GET http://host/cloud/api/workloads/1/log
Sample Response
HTTP Status: 200
HTTP Response Body:{
"log":"Workload, AIX 5L for POWER Version 5.3 , was created.Start asynch work run for deploy of virtual appliance :8498Workload removed due to exception: 11738Workload, AIX 5L for POWER Version 5.3 , was deleted.Error performing asynch work run for deploy of virtual appliance :8498Error: DNZIMN878E Command LANG=C; nim -a verbose=5 -o bos_inst -asource=mksysb -a group=nimrf-0000000000000008-res_group -a accept_licenses=yes rdpnfse0 did not run properly.New workload removed: 11738"}
GET /workloads/{id}/virtualServersThis service retrieves all the virtual servers within a workload by ID.
Workloads that have been executed and were successful will have virtual servers associated with them.Draft or failed workloads will return an empty array.
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 153
Query Parameters
N/A
Sample Request
Get virtual servers for workload with ID 1:
GET http://host/cloud/api/workloads/1/virtualServers
Sample Response
HTTP Status: 200 HTTP Response Body:{
"virtualServers": [{
"cloudId": "cloud://352/e7e213c5-4c6f-416b-9642-baa5ae6549cc","credentialsUri": "http://localhost:18080/cloud/api/workloads/73508/virtualServers/73555/credentials","state": {
"label": "Running","id": "RUNNING"
},"backups": "http://localhost:18080/cloud/api/virtualServers/73555/backups","hostname": "testhost235","storagesUri": "http://localhost:18080/cloud/api/virtualServers/73555/storages","capabilities": [
{"isEnabled": true,"id": "CREATE_DISK"
},{
"isEnabled": false,"id": "ATTACH_DISK"
},{
"isEnabled": true,"id": "DETACH_DISK"
},{
"isEnabled": true,"id": "THIN_PROVISIONED"
},{
"isEnabled": true,"id": "POWER_MANAGEMENT"
},{
"isEnabled": true,"id": "CAPTURE"
},{
"isEnabled": true,"id": "BACKUP"
},{
"isEnabled": false,"id": "SUSPEND_CAPABLE"
},{
"isEnabled": true,"id": "RESIZE"
},{
"isEnabled": false,"id": "PIN"
},{
"isEnabled": false,"id": "UNPIN"
}],"ip": "10.10.2.235","id": "73555",
154 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
"uri": "http://localhost:18080/cloud/api/virtualServers/73555"}
]}
GET /workloads/{id}/virtualServers/{id}This service retrieves a virtual server from the virtual servers in a workload by ID.
If a virtual server by the given ID doesn't exist in the workload, the service will return a 404.
Query Parameters
N/A
Sample Request
Get virtual server with ID 2 from workload with ID 1:
GET http://host/cloud/api/workloads/1/virtualServers/2
Sample Response
HTTP Status: 200
HTTP Response Body:{
"cloudId": "cloud://352/e7e213c5-4c6f-416b-9642-baa5ae6549cc","credentialsUri": "http://localhost:18080/cloud/api/workloads/73508/virtualServers/73555/credentials","state": {
"label": "Running","id": "RUNNING"
},"backups": "http://localhost:18080/cloud/api/virtualServers/73555/backups","properties": [
{"value": "1024","description": "Memory (MB)","category": "General Information"
},{
"value": "RHEL6_Template121 2012-07-03 12:41:05 test_ly_by_testUser","description": "Name","category": "General Information"
},{
"value": "1","description": "CPUs","category": "General Information"
},{
"value": "1","description": "Number of Ethernet Cards","category": "General Information"
},{
"value": "e7e213c5-4c6f-416b-9642-baa5ae6549cc","description": "UUID","category": "General Information"
},{
"value": "linuxGuest","description": "Guest Operating System",
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 155
"category": "General Information"},{
"value": "rhel5_64Guest","description": "Guest ID","category": "General Information"
},{
"value": "testhost235","description": "Guest Hostname","category": "General Information"
},{
"value": "10.10.2.235","description": "Guest IP Addresses","category": "General Information"
},{
"value": "vm-2858","description": "ID","category": "General Information"
},{
"value": "Connected","description": "Connection State","category": "General Information"
},{
"value": "host-875","description": "Host","category": "General Information"
},{
"value": "Powered On","description": "Power State","category": "General Information"
}],"hostname": "testhost235","storagesUri": "http://localhost:18080/cloud/api/virtualServers/73555/storages","capabilities": [
{"isEnabled": true,"id": "CREATE_DISK"
},{
"isEnabled": false,"id": "ATTACH_DISK"
},{
"isEnabled": true,"id": "DETACH_DISK"
},{
"isEnabled": true,"id": "THIN_PROVISIONED"
},{
"isEnabled": true,"id": "POWER_MANAGEMENT"
},{
"isEnabled": true,"id": "CAPTURE"
},{
"isEnabled": true,
156 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
"id": "BACKUP"},{
"isEnabled": false,"id": "SUSPEND_CAPABLE"
},{
"isEnabled": true,"id": "RESIZE"
},{
"isEnabled": false,"id": "PIN"
},{
"isEnabled": false,"id": "UNPIN"
}],"ip": "10.10.2.235","id": "73555","uri": "http://localhost:18080/cloud/api/virtualServers/73555"
}
GET /workloads/{id}/virtualServers/{id}/credentialsThis service retrieves the credentials associated with the given Virtual Server ID. These credentials areused during the capture process to perform the required access to capture.
Note: The “authenticated” attribute is not used for this particular service and so can be ignored.
Query Parameters
N/A
Sample Request
Get the Virtual Server with ID 2 credentials from workload with ID 1.
GET http://host/cloud/api/workloads/1/virtualServers/2/credentials
Sample Response
HTTP Status: 200
HTTP Response Body:{
"uri":"https://myhost/cloud/api/workloads/1/virtualServers/2/credentials","user":"root","pass":"not2pass"
}
PUT /workloads/{id}/virtualServers/{id}/credentialsThis service updates the credentials associated with the given Virtual Server ID and workload ID. Thesecredentials are used during the capture process in order to perform the required access to capture.
This service does not update any credentials on the configured cloud.
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 157
Query Parameters
N/A
Sample Request
Update the Virtual Server with ID 2 credentials from workload with ID 1.
PUT http://host/cloud/api/workloads/1/virtualServers/2/credentials{
"user":"root","password":"not2pass"
}
Sample Response
HTTP Status: 200
GET /workloads/{id}/timestampsThis service retrieves a workload's timestamps.
All timestamps are measured in Unix time format (the number of milliseconds since January 1, 197000:00:00 GMT) and only apply to workloads created from IBM Cloud Manager with OpenStack. Fortimestamps that are unset of not applicable, their values will be set to -1 which indicate to the consumerthat the timestamp is not applicable.
The following table outlines the current timestamps returned by this service.
Name Description
started The timestamp (Date) indicating when the workload wassubmitted to the cloud.
completed The timestamp (Date) indicating when the workloadexecution completed as successful or failed.
deployTime The estimated duration (elapsed time) of the workload'sexecution as measured by completionDate -submissionDate.
uptime The total "uptime" (elapsed time) for a workload whichis measured as the current timestamp - completionDate.This value is only applicable to workloads in the 'OK'state. Note that uptime does not take into accountdurations for which the workload has been stopped sinceexecution completion.
For workloads in the “OK” state, the executionTime measures the amount of time the workload executiontook from submission to successful execution completion. For workloads in the “FAILED” state, theexecutionTime will estimate how long the workload executed before failing.
If the workload is a “multi-workload,” the response will contain a set of timestamps for each workload inthe multi-workload. In this case the consumer can correlate timestamps to workloads using the“workload” attribute of each timestamp element of the response which indicates the IBM Cloud Managerwith OpenStack workload's name the timestamp is associated with.
Query Parameters
N/A
158 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
Sample Request
Get the timestamps for a workload with ID 1. GET http://host/cloud/api/workloads/1/timestamps
Sample Response
HTTP Status: 200 HTTP Response Body:{
"uri": ody: "http://host/cloud/api/workloads/1/timestamps">http://host/cloud/api/workloads/1/timestamps,"timestamps":[
{"workload":"sampleDeployment-1","started":1276108020765,"completed":1276108020765,"deployTime":1276108020765,"uptime":1276108020765
},{
"workload":"sampleDeployment-2","started":1276108020765,"completed":1276108020765,"deployTime":1276108020765,"uptime":1276108020765
},{
"workload":"sampleDeployment-3","started":1276108020765,"completed":1276108020765,"deployTime":1276108020765,"uptime":1276108020765
},{
"deployment":"sampleDeployment-4","started":1276108020765,"completed":1276108020765,"deployTime":1276108020765,"uptime":1276108020765
}]
}
PUT /workloads/{id}This service updates a workload either by changing its properties or by running it.
This service can also be used to request that a workload be “started” or “stopped” in the cloud as shownin the following examples.
Query Parameters
Name Description Default Required
dry The workload is not sent tothe cloud although all IBMCloud Manager withOpenStack processing isapplied. The workload ismarked as failed.
False No
Sample Requests1. Run workload with ID 1 on the cloud.
PUT http://host/cloud/api/workloads/1{
"name":"test","instances":1,"project":"51",
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 159
"properties":[{"name":"openstack.flavors","basic":true,"value":"2"}
],"state": "executing"
}
2. Request that the workload with ID 1 be started in the cloud.PUT http://host/cloud/api/workloads/1{
"state":"OK"}
3. Request the workload with ID 1 be stopped in the cloud.PUT http://host/cloud/api/workloads/1{
"state":"Stopped"}
4. Request the "Hidden" workload with ID 1 be shown in IBM Cloud Manager with OpenStack.PUT http://host/cloud/api/workloads/1{
"state":"Show"}
Note: If this API is used to suspend or resume an OpenStack PowerVM instance, an error that thisservice is not supported is displayed.
5. Update the name that is assigned to a workload with ID 1.PUT http://host/cloud/api/workloads/1{
"name":"My updated deployment"}
6. Update the workload properties that are assigned to a workload draft with ID 1.v For PowerVM workloads, use this request:
PUT http://host/cloud/api/workloads/1{
"name":"myName","instances":"###","project":"###","properties":[
{"name":"cpushared","value":2
},{
"name":"memsize","value":2048
},{
"name":"cskCPU","value":2
},{
"name":"cskRAM","value":2048
}{"name":"vimRef1disk","basic":false,"value":5376}
],"state":"EXECUTING"
}
160 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
v For KVM workloads, use this request:PUT http://host/cloud/api/workloads/1
{"name":"myName","instances":"###","project":"###","properties":[
{"name":"cpu","value":3
},{"name":"memminvu",
"value":1027}
{"name":"vimRef1disk","basic":false,"value":5376
}],
"state":"EXECUTING"}
v For VMware workloads, use this request:PUT http://host/cloud/api/workloads/1
{"name":"myName","instances":"###","project":"###","properties":[
{"name":"vmware.memory","value":1032
},{
"name":"vmware.cpu","value":2
}],"state":"EXECUTING"
}
v For OpenStack workloads, you can set the Quantum network uuids that you want to use for theworkload with this request:PUT http://host/cloud/api/workloads/1
{"name":"myName","instances":"###","project":"###","properties":[{"name":"cpu","value":3},{"name":"memminvu","value":1027},{"name":"vimRef1disk","basic":false,"value":5376},{"name":"networkdevice.Network adapters.networks","values":[25ec1f24-8539-4ae9-af05-279c8d8bd132,fc9d435e-c575-462f-b517-6e6a19fb0de3]
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 161
}],"state":"EXECUTING"}
7. Update the project that this workload belongs to, to project with ID 45.PUT http://host/cloud/api/workloads/1{
"project": 45}
8. Run workload with ID 1 on the cloud, creating five instances of this workload.PUT http://host/cloud/api/workloads/1{
"state": "executing","instances":5
}
9. Resize a workload with ID 1 on the cloud. Increase its VMs, CPUs, and assigned memory.PUT http://host/cloud/api/workloads/1{
"state": "resizing","properties":[
{"name":"cpu","value":3
},{
"name":"memsize","value":1024
}]
}
If this is a KVM workload, the request should be:{
"state": "resizing","properties":[
{"name":"cpumin","value":3
},{
"name":"memminvu","value":[MB]=vmemsize:1024
}]
}
10. Check whether the specified target is compatible with the target of workload 1.PUT http://host/cloud/api/workloads/1?dry=true{
"target": "45"}
If not compatible, a JSON string returns as the HTTP response, which contains all the incompatibleproperties. The HTTP status is always 200 OK whether the specified target is compatible.
11. Update the priority of this workload with ID 1 to priority 3.PUT http://host/cloud/api/workloads/1{
"properties":[{
162 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
"name": "priority","basic": false,"value": "3"
}],"state": "UPDATE_PRIORITY"
}
12. Enable remote restart capability of a workload when creating it.{
"name":"myName","instances":"###","project":"###","properties":[
{"name":"remoterestartcapable","value":true},
]"state":"EXECUTING"
}
Note: This property is valid only when the target is a system pool and the hypervisor is Power®. ForLinux Kernel-based Virtual Machine (KVM), this feature is enabled by default and not configurable.If the hypervisor is a VMware Server, the feature is not supported and the property is not valid.
Sample Responsev HTTP Status: 200 OK - For property updatesv HTTP Status: 202 Accepted - For workload executions, power management and resizes.
DELETE /workloads/{id}This service is used to either 'soft delete' a workload from IBM Cloud Manager with OpenStack, or 'harddelete' it from the cloud.
In the case of 'soft delete' the workload resources are not removed from the cloud, but rather the IBMCloud Manager with OpenStack workload is marked as 'DELETED' and not returned in any service thatqueries workloads. In the case of 'hard delete' the workload resources (workload and virtual server) arealso removed from the cloud.
Query Parameters
Name Description Default Required
hard The workload resourceshould be removed fromthe Cloud if hard is set to'true'.
false No
Sample Request
To remove workload with ID 1:
DELETE http://host/cloud/api/workloads/1
Sample Response
HTTP Status: 200 (for a soft delete)
HTTP Status: 202 (for a hard delete)
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 163
GET /workloads/statsThis service retrieves statistics about workloads. The default statistic is the states of the variousworkloads.
Query Parameters
Name Description Default Required
user Gets the statistics forworkloads that thisusername can see.
N/A No
Sample Request
Get workloads statistics:
GET http://host/cloud/api/workloads/stats
Sample Response
HTTP Status: 200
HTTP Response Body:{"groupBy":"state",
"uri":"http://localhost:18080/cloud/api/workloads/stats","stats":[
{"value":{"label":"Draft","id":"DRAFT"},"count":1},{"value":{"label":"OK","id":"OK"},"count":1},{"value":{"label":"Pending","id":"PENDING"},"count":2}
]}
GET /workloads/ownersThis service retrieves all the owners of workloads from the IBM SmartCloud Entry user registry.
This API retrieves the list of owners of all the workloads. To retrieve only the owners of the workloadsthat you want, use the user parameter and specify a value. If you do not specify a value for theparameter, the owners of all the workloads in IBM Cloud Manager with OpenStack server are retrieved.
Query Parameters
Name Description Default Required
user Retrieves all the owners ofthe workloads for thespecified users.
false No
Sample Request
Retrieve a list of all owners in the IBM SmartCloud Entry user registry.
GET http://host/cloud/api/workloads/owners
No HTTP body required.
164 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
Sample Response
HTTP Status: 200
HTTP Response Body:{
"users": [{
"isLocked": false,"isAdmin": true,"role": {
"label": "Admin","id": "ADMIN"
},"username": "admin","name": "SmartCloud Entry Administrator","emailNotifications": false,"email": "","uri": "http://localhost:18080/cloud/api/workloads/owners/admin","isApprover": true
},{
"isLocked": false,"isAdmin": false,"role": {
"label": "User","id": "USER"
},"username": "user1","name": "user1","emailNotifications": false,"uri": "http://localhost:18080/cloud/api/workloads/owners/user1","isApprover": false
},{
"isLocked": false,"isAdmin": false,"role": {
"label": "User","id": "USER"
},"username": "user2","name": "user2","emailNotifications": false,"uri": "http://localhost:18080/cloud/api/workloads/owners/user2","isApprover": false
}]
}
Chapter 1. IBM Cloud Manager with OpenStack REST API reference 165
166 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
Chapter 2. IBM OpenStack REST API reference
IBM Cloud Manager with OpenStack provides a set of OpenStack APIs. IBM Cloud Manager withOpenStack also provides the ability for applications that are running outside of the IBM Cloud Managerwith OpenStack framework to access the OpenStack APIs. These APIs are based on the representationalstate transfer (REST) architecture and are accessed by using the HTTP protocol.
REST refers to an architecture used to create stateless web services that are typically accessed by usingthe HTTP protocol.
Overview of IBM OpenStack REST API referenceOpenStack is pre-configured by IBM Cloud Manager with OpenStack. You can use the IBM CloudManager with OpenStack user interface and REST APIs when you use OpenStack APIs.
IBM Cloud Manager with OpenStack for OpenStack Management
For an OpenStack management scenario in IBM Cloud Manager with OpenStack, direct mutableoperations through the OpenStack APIs bypass the following IBM Cloud Manager with OpenStackcontrol flows: Billing and Metering, Approvals, Expiration, and Image template. OpenStack resourcescreated in-band through IBM Cloud Manager with OpenStack must be managed by IBM Cloud Managerwith OpenStack. OpenStack resources that are created out-of-band by OpenStack APIs must be managedby OpenStack APIs.
For Identity Management, you can use the self-service portal to manage identity resources, such as users,projects, and domains. Therefore, only immutable OpenStack APIs and some OpenStack APIs, such asservices or endpoints of Keystone, are directly supported.
Access OpenStack APIsAll OpenStack API access that includes access to CLIs must flow through the IaaS gateway.
Access OpenStack APIs/CLIs through IaaS gateway
IaaS gateway is a part of the IBM OpenStack distribution. OpenStack is a lightweight proxy middlewarecontainer that provides pluggable adaptation to normalize interactions across multiple IaaS cloudprovider vendors. IaaS gateway has the following main features:
A lightweight stateless API proxy
A single uniform API entry point for users to work with multiple IaaS based Clouds on the backend.When users call the uniform API URL to IaaS gateway, which rewrites the URL or changes the requestbody to match the backend cloud format. IaaS gateway also changes the response from clouds to makethem uniform and return to users.
Pluggable adaptation and middleware
In IaaS gateway, the middleware and adaptation feature provides ways to integrate withnon-OpenStack-based backend IaaS providers. The federated IaaS Clouds might not supportOpenStack-based APIs, or data formats. Users cannot interface with an OpenStack-based REST API whilethose requests are serviced in a semantically equivalent manner. Therefore, IaaS gateway providessupport for only OpenStack integration. The adapters in IaaS gateway are pluggable and extendable. If
© Copyright IBM Corp. 2011, 2014 167
the gateway does not provide the features that are needed to adapt to new rules, adding an adapter intothe gateway is allowed.
URL rewriting
To make the URL uniform for federation clouds, URL rewriting is necessary. Gateway provides access toa virtual URI for each of the federated remote service endpoints in the federation. This “hides” the trueremote endpoint URLs from gateway REST users. The format of the virtual URIs is as follows:http[s]://<gateway_host>:<gateway_port>/<endpoint_id>/[admin|public|internal]/<api_uri>. TheURL format is based on OpenStack API style.
Connect to a Keystone service
The gateway requires a Keystone service, which is used for the service or endpoint catalog (does not usetenants or users). Gateway admin users register remote federated cloud services and their respectiveendpoints into the gateway of the master Keystone by using the actual endpoint URL to the remoteprovider.
A service that is running on Linux
IaaS gateway has its own service that is running on Linux, and is configured by using configuration files.Therefore, to access OpenStack APIs, use the IaaS gateway virtual URI through the IaaS gateway. Forexample, to authenticate with Keystone and obtain a Keystone token, call http://vs479:9973/770e010856b64d39bf7d622718c55156/public/v2.0/tokens. Using CLIs is similar to accessing APIs. Thefollowing is an example:# glance --os-username=admin --os-password=secrete --os-tenant-name=demo --os-auth-url=https://gweast.ibm.com:9973/ff241c64364043f99b83f928ec125e65/public/v2.0/image-list
# nova --os-username=admin --os-password=secrete --os-tenant-name=demo --os-auth-url=https://gweast.ibm.com:9973/ff241c64364043f99b83f928ec125e65/public/v2/ffa68a8682004e559a3d801222a59133/servers/detail# keystone --os-username=admin --os-password=secrete --os-tenant-name=demo --os-auth-url=https://gweast.ibm.com:9973/ff241c64364043f99b83f928ec125e65/public/v2.0/users
OpenStack REST APIsThe OpenStack APIs that are supported by IBM Cloud Manager with OpenStack are listed here.
Only the following OpenStack projects are supported by IBM Cloud Manager with OpenStack 4.2:v Heat (Orchestration)v Horizon (Dashboard)v Keystone (Identity)v Nova (Compute)v Glance (Image)v Neutron (Networking)v Cinder (Block storage)v Ceilometer (Telemetry)v Swift (Object storage)
The specification of each supported API is not included in this guide. Refer to http://api.openstack.org/api-ref.html for details of the specifications.
Note: For the supported APIs, any limitations or restrictions for the scenarios and hypervisors (KVM,Hyper-V, and IBM PowerVM/PowerVC) are noted. The stability of non-supported APIs or features, is not
168 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
guaranteed by IBM Cloud Manager with OpenStack. Non-supported features might not be functionallycomplete, and are not intended for production use. IBM does not attempt to resolve any issues thatcustomers experience when they use these features.
Explanation of table headers
Each supported OpenStack API is described by using a table.
API The REST API list.
DescriptionThe feature description of this API.
SmartCloud Entry for OpenStack ManagementWhether this API is supported when users use IBM Cloud Manager with OpenStack to managean OpenStack cloud API. Any limitations or notes about this API are marked. 'Y' means that thisAPI was tested and verified. 'N' means that this API is not supported by IBM Cloud Managerwith OpenStack.
HypervisorPoints out the API differences between KVM, Hyper-V, and IBM PowerVM/PowerVC.
KeystoneThe services that are provided by Keystone are described here.
Table 4. Keystone API services
API Description
IBM Cloud Managerwith OpenStack forOpenStackManagement
IBM Cloud Manager withOpenStack for BaseOpenStack IaaS Hypervisor
Identity Service API v2.0
Gets an authentication token that permits access to the Compute API for 24 hours.
GET v2.0 Gets detailedinformation about aspecified version ofthe Identity ServiceAPI.
Y Y
GET v2.0/extensions Lists availableextensions.
Y Y
GETv2.0/extensions/{alias}
Gets detailedinformation for aspecified extension.
Y Y
POST v2.0/tokens Authenticates andgenerates a token.
N Y
Identity Service Admin API v2.0
Gets an authentication token that permits access to the Compute API for 24 hours.
GET v2.0 Gets detailedinformation about aspecified version ofthe Identity ServiceAPI.
Y Y
GET v2.0/extensions Lists availableextensions.
Y Y
Chapter 2. IBM OpenStack REST API reference 169
Table 4. Keystone API services (continued)
API Description
IBM Cloud Managerwith OpenStack forOpenStackManagement
IBM Cloud Manager withOpenStack for BaseOpenStack IaaS Hypervisor
GETv2.0/extensions/{alias}
Gets detailedinformation for aspecified extension.
Y Y
POST v2.0/tokens Authenticates andgenerates a token.
N Y
GETv2.0/tokens/{tokenId}
Validates a tokenand confirms that itbelongs to aspecified tenant.
Y Y
HEADv2.0/tokens/{tokenId}
Validates a tokenand confirms that itbelongs to aspecified tenant, forperformance.
Y Y
GETv2.0/tokens/{tokenId}/endpoints
Lists the resourcesthat are associatedwith a specifiedtoken.
Y Y
GET v2.0/users Gets detailedinformation about aspecified user byuser name.
Y Y
GETv2.0/users/{user_id}
Gets detailedinformation about aspecified user byuser ID.
Y Y
GET v2.0/tenants Lists tenants towhich the specifiedtoken has access.
Y Y
GETv2.0/tenants/{tenantId}
Gets detailedinformation about aspecified tenant byID.
Y Y
GETv2.0/tenants/{tenantId}/users/{userId}/roles
Lists roles for aspecified user on aspecified tenant.Excludes globalroles.
Y Y
OS-KSADM Admin Extension
GET v2.0/users Lists users. Y Y
170 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
Table 4. Keystone API services (continued)
API Description
IBM Cloud Managerwith OpenStack forOpenStackManagement
IBM Cloud Manager withOpenStack for BaseOpenStack IaaS Hypervisor
POST v2.0/users Adds a user. N Y.
Limitation: When identitydriver is set to
ldap([identity]driver =keystone.identity.backends.ldap.Identity),the following four userattributes are ignored:enabled, email, tenants,tenantId
PUTv2.0/users/{userId}
Updates a user. N Y.
Limitation: When identitydriver is set to
ldap([identity]driver =keystone.identity.backends.ldap.Identity),the following four userattributes are ignored:enabled, email, tenants,tenantId
DELETEv2.0/users/{userId}
Deletes a user. N Y
PUTv2.0/users/{userId}/OS-KSADM/enabled
Enables a specifieduser.
N Y
POST v2.0/tenants Creates a tenant. N Y.
Limitation: When identitydriver is set to
ldap([identity]driver =keystone.identity.backends.ldap.Identity),the following four userattributes are ignored:enabled, email, tenants,tenantId
PUTv2.0/tenants/{tenantId}
Updates a tenant. N Y.
Limitation: When identitydriver is set to
ldap([identity]driver =keystone.identity.backends.ldap.Identity),the following four userattributes are ignored:enabled, email, tenants,tenantId
Chapter 2. IBM OpenStack REST API reference 171
Table 4. Keystone API services (continued)
API Description
IBM Cloud Managerwith OpenStack forOpenStackManagement
IBM Cloud Manager withOpenStack for BaseOpenStack IaaS Hypervisor
DELETEv2.0/tenants/{tenantId}
Deletes a tenant. N Y
GETv2.0/tenants/{tenantId}/users
Lists all the users fora tenant.
Y Y
PUTv2.0/tenants/{tenantId}/users/{userId}/roles/OS-KSADM/{roleId}
Adds a specified roleto a user for atenant.
N Y
DELETEv2.0/tenants/{tenantId}/users/{userId}/roles/OS-KSADM/{roleId}
Deletes a specifiedrole from a user on atenant.
N Y
GETv2.0/OS-KSADM/roles
Gets a role by name. Y Y
POSTv2.0/OS-KSADM/roles
Adds a role. N Y
GETv2.0/OS-KSADM/roles/{roleId}
Gets a role. Y Y
DELETEv2.0/OS-KSADM/roles/{roleId}
Deletes a role. N Y
GETv2.0/OS-KSADM/services
Lists services. Y Y
POSTv2.0/OS-KSADM/services
Adds a service. N Y
GETv2.0/OS-KSADM/services/{serviceId}
Gets a service. Y Y
DELETEv2.0/OS-KSADM/services/{serviceId}
Deletes a service. N Y
172 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
GlanceThe Glance API services that are supported by IBM Cloud Manager with OpenStack are described here.
Table 5. Glance API services
API Description
IBM Cloud Managerwith OpenStack forOpenStackManagement
IBM Cloud Managerwith OpenStack forBase OpenStack IaaS Hypervisor
V2.0
Creates, updates, and deletes image metadata records. Also, uploads and downloads raw image data.Note: The powervc_uuid image metadata is reserved by the PowerVC driver and must not be updated.
GET v2/schemas/images Gets a json-schemadocument thatrepresents an imagesentity
Y Y
GET v2/schemas/image Gets a json-schemadocument thatrepresents an imageentity.
Y Y
GET v2/images Lists public virtualmachine (VM)images.
Y Y
POST v2/images Creates a virtualmachine (VM) image.
Y.
Limitation: 'owner'attribute must be setto tenant id instead ofuser ID. If set to userID, IBM CloudManager withOpenStack cannotcategorize the user tocorrect tenant, andjust categorizes it tothe default project.
Y Not supported byPowerVC driver. Allimages must besynchronized fromPowerVC to thehosting OpenStack bythe PowerVC driver.
GETv2/images/{imageId}
Gets details for aspecified image.
Y Y Not supported byPowerVC driver.
PATCHv2/images/{imageId}
Updates a specifiedimage.
Y.
Limitation: 'owner'attribute must be setto tenant id instead ofuser ID. If set to userID, IBM CloudManager withOpenStack cannotcategorize the user tocorrect tenant, andjust categorizes it tothe default project.
Y
DELETEv2/images/{imageId}
Deletes a specifiedimage.
Y Y
Chapter 2. IBM OpenStack REST API reference 173
Table 5. Glance API services (continued)
API Description
IBM Cloud Managerwith OpenStack forOpenStackManagement
IBM Cloud Managerwith OpenStack forBase OpenStack IaaS Hypervisor
PUTv2/images/{imageId}/file
Uploads binary imagedata.
Y Y Not supported byPowerVC driver. Allimages must besynchronized fromPowerVC to thehosting OpenStack bythe PowerVC driver.
GETv2/images/{imageId}/file
Downloads binaryimage data.
Y Y
POSTv2/images/{image_id}/tags/{tag}
Adds a specified tagto a specified image.
Y Y Not supported byPowerVC driver.
DELETEv2/images/{image_id}/tags/{tag}
Deletes a specifiedtag from a specifiedimage.
Y Y Not supported byPowerVC driver.
NeutronProvides virtual networking services among devices that are managed by the OpenStack compute service.The Networking API v2.0 combines the API v1.1 function with some essential Internet Protocol AddressManagement (IPAM). Enables users to associate IP address blocks and other network configurationsettings with a neutron network. You can choose a specific IP address from the block or Neutron canchoose the first available IP address.
Note: The PowerVC driver supports only VLAN type networks with physical network equal to“default”. Also, IPv6 addresses are ignored by the PowerVC driver.
Table 6. Neutron API services
API Description
IBM Cloud Managerwith OpenStack forOpenStackManagement
IBM Cloud Managerwith OpenStack forBase OpenStack IaaS Hypervisor
Network
Lists, creates, deletes, and updates neutron networks, subnets, and ports.
GET /networks Lists a summary ofall networks that aredefined in neutronthat are accessible tothe tenant whosubmits the request.
Y Y
GET/networks/{network_id}
Lists detailedinformation for thespecified network ID.
Y Y
POST/networks/{network_id}
Creates a neutronnetwork.
Y Y
DELETE/networks/{network_id}
Lists detailedinformation for thespecified network ID.
Y Y
174 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
Table 6. Neutron API services (continued)
API Description
IBM Cloud Managerwith OpenStack forOpenStackManagement
IBM Cloud Managerwith OpenStack forBase OpenStack IaaS Hypervisor
PUT/networks/{network_id}
Updates the name ofthe specified network.
Y Y
GET /subnets Lists all subnets thatare accessible to thetenant who submitsthe request.
Y Y
POST /subnets Creates a subnet onthe specified network.
Y.
Limitation:
Under one specificnetwork, users cancreate only one IPv4subnet or two subnets(one IPv4 and oneIPv6)
Y
DELETE/subnets/{subnet-id}
Removes thespecified subnet.
Y Y
PUT/subnets/{subnet-id}
Updates the specifiedsubnet.
Y Y
GET /ports Lists all ports towhich the tenant hasaccess.
Y Y
GET /ports/{port-id} Shows informationfor the specified port.
Y Y
POST /ports Creates a port on thespecified network.
Y Y
PUT /ports/{port-id} Updates the specifiedport.
Y Y
DELETE/ports/{port-id}
Removes thespecified port.
Y Y
List available Extensions.
GET /2.0/extensions List availableextensions.
Y Y
The Layer-3 Network Extension
The Layer-3 networking extension enables OpenStack Networking API users to route packets between subnets,forward packets from internal networks to external ones, and access instances from external networks throughfloating IPs.
GET /routers Returns a list oflogical routersaccessible to thetenant that submitsthe request.
N Y
GET/routers/{router_id}
Returns details abouta specific logicalrouter.
N Y
Chapter 2. IBM OpenStack REST API reference 175
POST /routers Create a new logicalrouter.
N Y
PUT/routers/{router_id}
Updates a logicalrouter.
N Y
DELETE/routers/{router_id}
Removes a logicalrouter and itsexternal gatewayinterface, if it exists
N Y
PUT/routers/{router_id}/add_router_interface
Adds an internalinterface to a logicalrouter.
N Y
PUT/routers/{router_id}/remove_router_interface
Removes an internalinterface from alogical router.
N Y
GET /floatingips Returns a list offloating IPs accessibleto the tenant thatsubmits the request.
N Y
GET/floatingips/{floating_ip}
Returns details abouta specific floating IP.
N Y
POST/floatingips/{floating_ip}
Creates a floating IPand configures itsassociation with aninternal port, if therelevant informationis specified
N Y
PUT/floatingips/{floating_ip}
Updates a floating IPand its associationwith an internal port,if the relevantinformation isspecified in therequest body.
N Y
DELETE/floatingips/{floating_ip}
Removes a floating IPand its associationinformation.
N Y
Quotas
This extension enables an admin user to define quotas values on a per-tenant basis. For example, an admin user canprovide tenant A rights to create at most X networks, and provide rights to tenant B to create at most Y networks.
GET /quotas Lists quotas fortenants who havenon-default quotavalues.
N Y
GET /quotas/tenant_id Shows quotas for aspecified tenant.
N Y
PUT /quotas/tenant_id Updates quotas for aspecified tenant. Usewhen non-defaultquotas are wanted.
N Y
DELETE/quotas/tenant_id
Resets quotas todefault values for aspecified tenant.
N Y
176 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
Security Groups and Rules
Creates, modifies, and deletes OpenStack Networking security groups and rules.Note: Security Groups and Rules are not supported by PowerVC driver.
GET /security-groups Lists a summary ofall OpenStackNetworking securitygroups that thespecified tenant canaccess.
N Y
POST /security-groups Creates an OpenStackNetworking securitygroup.
N Y
GET/security-groups/{security_group_id}
Shows informationfor a specifiedsecurity group.
N Y
DELETE/security-groups/{security_group_id}
Deletes an OpenStackNetworking securitygroup.
N Y
GET/security-group-rules
Lists a summary ofallOpenStackNetworking securitygroup rules that thespecified tenant canaccess.
N Y
POST/security-group-rules
Creates an OpenStackNetworking securitygroup rule.
N Y
GET/security-group-rules/{rule_id}
Shows detailedinformation for aspecified securitygroup rule.
N Y
DELETE/security-group-rules/{rule_id}
Deletes a specifiedrule from anOpenStackNetworking securitygroup.
N Y
Agent Management
In a typical OpenStack Networking deployment, some agents run on network or compute nodes, such asneutron-dhcp-agent, neutron-ovs-agent, and neutron-l3-agent. This extension provides a way for administrators(enforced by the policy engine) to view their status and update their attributes. Updating agent management APIattributes affect operations of other components such as OpenStack Networking schedulers. For instance, whenadministrators disable a certain agent, OpenStack Networking schedulers do not schedule resources to it.
GET /agents List agents that reporttheir status toOpenStackNetworking server.
N Y
GET /agents/{agent_id} Show information ofthe specified agent.
N Y
PUT /agents/{agent_id} Update the agent'sadmin status anddescription.
N Y
DELETE/agents/{agent_id}
Delete the specifiedagent.
N Y
Chapter 2. IBM OpenStack REST API reference 177
The Load Balancer as a Service Extension
The LBaaS extension provides OpenStack tenants with a feature of balancing traffic to their VMs.
GET /lb/vips Lists vips. N Y
GET /lb/vips/{vip-id} Returns details abouta specific vip.
N Y
POST /lb/vips Create a loadbalancer vip.
N Y
PUT /lb/vips/{vip-id} Updates a loadbalancer vip.
N Y
DELETE/lb/vips/{vip-id}
Removes a loadbalancer vip.
N Y
GET /lb/pools Lists pools. N Y
GET /lb/pools/{pool-id} Returns details abouta specific pool.
N Y
POST /lb/pools Create a loadbalancer pool.
N Y
PUT /lb/pools/{pool-id} Updates a loadbalancer pool.
N Y
DELETE/lb/pools/{pool-id}
Removes a loadbalancer pool.
N Y
GET /lb/members Lists members. N Y
GET/lb/members/{member-id}
Returns details abouta specific member.
N Y
POST /lb/members Create a loadbalancer member.
N Y
PUT/lb/members/{member-id}
Updates a loadbalancer member.
N Y
DELETE/lb/members/{member-id}
Removes a loadbalancer member.
N Y
GET/lb/health_monitors
Lists health monitors. N Y
GET/lb/health_monitors/{monitor_id}
Returns details abouta specific healthmonitor.
N Y
POST/lb/health_monitors
Create a loadbalancer healthmonitor.
N Y
PUT/lb/health_monitors/{monitor_id}
Updates a loadbalancer healthmonitor.
N Y
DELETE/lb/health_monitors/{monitor_id}
Delete health monitor. N Y
POST/lb/pools/pool-id/health_monitors
Associate healthmonitor with thepool.
N Y
178 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
DELETE/lb/pools/pool-id/health_monitors/{monitor_id}
Disassociate healthmonitor from thepool.
N Y
The Agent Schedulers Extension
The agent schedulers extension schedules resources among agents on top of the agent management extension.
GET/agents/agent_id/dhcp-networks
List networks thespecified DHCP agentis hosting.
N Y
GET/networks/network_id/dhcp_agents
List DHCP agent thathosts the specifiednetwork.
N Y
POST/agents/agent_id/dhcp-networks
Schedule the networkto the DHCP agent.
N Y
DELETE/agents/agent_id/dhcp-networks/network_Id
Remove the networkfrom the DHCPagent.
N Y
GET/agents/agent_id/l3-routers
List routers the L3agent is hosting.
N Y
GET/agents/agent_id/l3-routers/{router_id}
List L3 agents thathosts the router.
N Y
POST/agents/agent_id/l3-routers
Schedule the router tothe L3 agent.
N Y
DELETE/agents/agent_id/l3-routers/{router_id}
Remove the routerfrom the L3 agent.
N Y
The Virtual Private Network As a Service Extension
The VPNaaS extension provides OpenStack tenants with the ability to extend private networks across the publictelecommunication infrastructure.
GET /vpn/vpnservices Lists VPN services. N Y
GET/vpn/vpnservices/{service-id}
Returns details abouta specific VPNservice.
N Y
POST /vpn/vpnservices Creates a VPNservice.
N Y
PUT/vpn/vpnservices/{service-id}
Updates a VPNservice, providedstatus is notindicating aPENDING_* state.
N Y
DELETE/vpn/vpnservices/{service-id}
Removes a VPNservice.
N Y
GET /vpn/ikepolicies Lists IKE policies. N Y
GET/vpn/ikepolicies/{ikepolicy-id}
Returns details abouta specific IKE policy.
N Y
Chapter 2. IBM OpenStack REST API reference 179
POST /vpn/ikepolicies Creates an IKE policy. N Y
PUT/vpn/ikepolicies/{ikepolicy-id}
Updates an IKEpolicy.
N Y
DELETE/vpn/ikepolicies/{ikepolicy-id}
Removes an IKEpolicy.
N Y
GET /vpn/ipsecpolicies Lists IPSec policies. N Y
GET/vpn/ipsecpolicies/{ipsecpolicy-id}
Returns details abouta specific IPSecpolicy.
N Y
POST /vpn/ipsecpolicies Creates an IPSecpolicy.
N Y
PUT/vpn/ipsecpolicies/{ipsecpolicy-id}
Updates a IPSecpolicy.
N Y
DELETE/vpn/ipsecpolicies/{ipsecpolicy-id}
Removes a IPSecpolicy.
N Y
GET/vpn/ipsec-site-connections
Lists the IPSecsite-to-siteconnections.
N Y
GET/vpn/ipsec-site-connections/{connection-id}
Returns details abouta specific IPSecsite-to-site connection.
N Y
POST/vpn/ipsec-site-connections
Creates an IPSec siteconnection.
N Y
PUT/vpn//ipsec-site-connections/{connection-id}
Updates an IPSecsite-to-site connection,provided status is notindicating aPENDING_* state.
N Y
DELETE/vpn//ipsec-site-connections/{connection-id}
Deletes a IPSecsite-to-site connection.
N Y
CinderThe Cinder API services that are supported by IBM Cloud Manager with OpenStack are described here.
Table 7. Cinder API services
API Description
IBM Cloud Managerwith OpenStack forOpenStackManagement
IBM Cloud Managerwith OpenStack forBase OpenStack IaaS Hypervisor
V2
Manages volumes and snapshots for use with the Block Storage Service API (cinder services).
POSTv2{tenant_id}/volumes
Creates a volume. Y Y
180 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
Table 7. Cinder API services (continued)
API Description
IBM Cloud Managerwith OpenStack forOpenStackManagement
IBM Cloud Managerwith OpenStack forBase OpenStack IaaS Hypervisor
GETv2{tenant_id}/volumes
Lists summaryinformation for allCinder volumes thatare accessible to thetenant who submitsthe request.
Y Y
GETv2{tenant_id}/volumes/detail
Lists detailedinformation for allCinder volumes thatare accessible to thetenant who submitsthe request.
Y Y
GETv2{tenant_id}/volumes/{volume_id}
Shows informationabout a specifiedvolume.
Y Y
PUTv2{tenant_id}/volumes/{volume_id}
Updates a volume. Y Y
DELETEv2{tenant_id}/volumes/{volume_id}
Deletes a specifiedvolume.
Y Y
GETv2{tenant_id}/volume_types
Lists volume types. Y Y
GETv2{tenant_id}/volume_types/{type_id}
Shows informationabout a specifiedvolume type.
Y Y
POSTv2{tenant_id}/snapshots
Creates a snapshot,which is apoint-in-time copy ofa volume. You cancreate a new volumefrom the snapshot.
Y Y Not supported byPowerVC driver.
GETv2{tenant_id}/snapshots
Lists summaryinformation for allCinder snapshots thatare accessible to thetenant who submitsthe request.
Y Y Not supported byPowerVC driver.
GETv2{tenant_id}/snapshots/detail
Lists detailedinformation for allCinder snapshots thatare accessible to thetenant who submitsthe request.
Y Y Not supported byPowerVC driver.
GETv2{tenant_id}/snapshots/{snapshot_id}
Shows informationfor a specifiedsnapshot.
Y Y Not supported byPowerVC driver.
Chapter 2. IBM OpenStack REST API reference 181
Table 7. Cinder API services (continued)
API Description
IBM Cloud Managerwith OpenStack forOpenStackManagement
IBM Cloud Managerwith OpenStack forBase OpenStack IaaS Hypervisor
PUTv2{tenant_id}/snapshots/{snapshot_id}
Updates a specifiedsnapshot.
Y Y Not supported byPowerVC driver.
DELETEv2{tenant_id}/snapshots/{snapshot_id}
Deletes a specifiedsnapshot.
Y Y Not supported byPowerVC driver.
NovaThe Nova API services that are supported by IBM Cloud Manager with OpenStack are described here.
Table 8. Nova API services
API Description
IBM Cloud Managerwith OpenStack forOpenStackManagement
IBM Cloud Managerwith OpenStack forBase OpenStack IaaS Hypervisor
Versions
GET v2 Gets details aboutthis specific versionof the API.
Y Y
Extensions
Note: The PowerVC driver added an “extended_powervm” server extension to the Nova './api/openstack/compute/contrib/' directory. This extension provides unique server attributes to PowerVM by using the“IBM-PVM” prefix.
GETv2/{tenant_id}/extensions
Lists all availableextensions.
Y Y
GETv2/{tenant_id}/extensions/{alias}
Gets details about thespecified extension.
Y Y
Limits
GETv2/{tenant_id}/limits
Returns current limitsfor the account.
Y Y
Servers
GETv2/{tenant_id}/servers
Lists IDs, names, andlinks for all servers.
Y Y
POSTv2/{tenant_id}/servers
Creates a server. Y Y
GETv2/{tenant_id}/servers/detail
Lists details for allservers.
Y Y
GETv2/{tenant_id}/servers/{server_id}
Gets details for aspecified server.
Y Y
PUTv2/{tenant_id}/servers/{server_id}
Updates the editableattributes of thespecified server.
Y Y Not supported byPowerVC driver.
182 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
Table 8. Nova API services (continued)
API Description
IBM Cloud Managerwith OpenStack forOpenStackManagement
IBM Cloud Managerwith OpenStack forBase OpenStack IaaS Hypervisor
DELETEv2/{tenant_id}/servers/{server_id}
Deletes a specifiedserver.
Y.
Limitation:
If users delete orforce-delete a serveron OpenStack Cloud,the server isdisplayed with"unknown" status atIBM Cloud Managerwith OpenStack side.
Y
Server Metadata
Sets, lists, gets details for, and deletes server metadata or metadata items.Note: The pvc_id server metadata is reserved by the PowerVC driver and must not be updated.
GETv2/{tenant_id}/servers/{server_id}/metadata
Lists metadata for thespecified resource.
Y Y
POSTv2/{tenant_id}/servers/{server_id}/metadata
Updates metadataitems by key for thespecified resource.
Y Y
PUTv2/{tenant_id}/servers/{server_id}/metadata
Sets metadata for thespecified resource.
Y.
Limitation: IBMCloud Manager withOpenStack sets onlythe server metadatawhen deploying avirtual server, andthen any changes tometadata inOpenStack will not besynchronized to IBMCloud Manager withOpenStack.
Y
GETv2/{tenant_id}/servers/{server_id}/metadata/{key}
Gets a metadata itemby key for thespecified resource.
Y Y
Chapter 2. IBM OpenStack REST API reference 183
Table 8. Nova API services (continued)
API Description
IBM Cloud Managerwith OpenStack forOpenStackManagement
IBM Cloud Managerwith OpenStack forBase OpenStack IaaS Hypervisor
PUTv2/{tenant_id}/servers/{server_id}/metadata/{key}
Sets a metadata itemby key for thespecified resource.
Y.
Limitation: IBMCloud Manager withOpenStack sets onlythe server metadatawhen deploying avirtual server, andthen any changes tometadata inOpenStack will not besynchronized to IBMCloud Manager withOpenStack.
Y
DELETEv2/{tenant_id}/servers/{server_id}/metadata/{key}
Deletes a metadataitem by key for thespecified resource.
Y Y
Server Addresses
GETv2/{tenant_id}/ips/{network_id}
Lists addresses for aspecified server IDand network label.
Y Y
GET v2/{tenant_id}/ips Lists addresses for aspecified server ID.
Y Y
Server Actions
Performs actions for a specified server, including changing administrator password, rebooting, rebuilding, resizing,and creating image from server.
POSTv2/{tenant_id}/servers/action
Changes thepassword for a server.Specify thechangePasswordaction in the requestbody.
N.
All change serverpassword REST APIsare invalid to IBMCloud Manager withOpenStack. Thesechanges cannot besynchronized to IBMCloud Manager withOpenStack, as IBMCloud Manager withOpenStack does notcollect theadministrativepassword from thecloud side.
Y Not supported byPowerVC driver.
POSTv2/{tenant_id}/servers/action
Reboots the specifiedserver. Specify thereboot action in therequest body.
Y Y Not supported byPowerVC driver.
184 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
Table 8. Nova API services (continued)
API Description
IBM Cloud Managerwith OpenStack forOpenStackManagement
IBM Cloud Managerwith OpenStack forBase OpenStack IaaS Hypervisor
POSTv2/{tenant_id}/servers/action
Rebuilds the specifiedserver. Specify therebuild action in therequest body.
Y.
Limitation: Thefollowing propertiescannot besynchronized to IBMCloud Manager withOpenStack: Metadata,adminPass,personality.
Y
POSTv2/{tenant_id}/servers/action
Resizes the specifiedserver. Specify theresize action in therequest body.
Y Y
POSTv2/{tenant_id}/servers/action
Confirms a pendingresize action. Specifythe confirmResizeaction in the requestbody.
Y Y
POSTv2/{tenant_id}/servers/action
Cancels and reverts apending resize action.Specify therevertResize action inthe request body.
N.
The "resize" and"confirm resize"actions in IBM CloudManager withOpenStack are atomicoperations.
Y Not supported byPowerVC driver.
POSTv2/{tenant_id}/servers/action
Creates a new image.Specify thecreateImage action inthe request body.
Y Y
Flavors
Lists available flavors and gets details for a specified flavor. A flavor is a hardware configuration for a server. Eachflavor is a unique combination of disk space and memory capacity.
GET v2/flavors Lists IDs, names, andlinks for availableflavors.
Y Y
GETv2/flavors/detail
Lists all details foravailable flavors.
Y Y
GETv2/flavors/{flavor_id}
Gets details for aspecified flavor.
Y Y.Note: A deletedflavor still might beshown.
(https://bugs.launchpad.net/nova/+bug/1168260 )
Chapter 2. IBM OpenStack REST API reference 185
Table 8. Nova API services (continued)
API Description
IBM Cloud Managerwith OpenStack forOpenStackManagement
IBM Cloud Managerwith OpenStack forBase OpenStack IaaS Hypervisor
Images
Lists available images, gets details for a specified image, and deletes an image. Also, sets, lists, gets details for, anddeletes image metadata.
An image is a collection of files that you use to create or rebuild a server. By default, operators provide prebuiltoperating system images. You can also create custom images.
GET v2/images Lists IDs, names, andlinks for availableimages.
Y Y
GET v2/images/detail Lists all details foravailable images.
Y Y
GETv2/images/{image_id}
Gets details for aspecified image.
Y Y
DELETEv2/images/{image_id}
Deletes a specifiedimage.
Y Y
Image Metadata
Sets, lists, gets details for, and deletes image metadata or metadata items.Note: The powervc_uuid image metadata is reserved by the PowerVC driver and must not be updated.
GETv2/images/{image_id}/metadata
Lists metadata for thespecified resource.
Y Y
POSTv2/images/{image_id}/metadata
Updates metadataitems by key for thespecified resource.
Y Y
PUTv2/images/{image_id}/metadata
Sets metadata for thespecified resource.
Y Y
GETv2/images/{image_id}/metadata/{key}
Gets a metadata itemby key for thespecified resource.
Y Y
PUTv2/images/{image_id}/metadata/{key}
Sets a metadata itemby key for thespecified resource.
Y Y
DELETEv2/images/{image_id}/metadata/{key}
Deletes a metadataitem by key for thespecified resource.
Y Y
Server Admin Actions
Permits administrators to perform actions on a server.
186 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
Table 8. Nova API services (continued)
API Description
IBM Cloud Managerwith OpenStack forOpenStackManagement
IBM Cloud Managerwith OpenStack forBase OpenStack IaaS Hypervisor
POSTv2/{tenant_id}/servers/{server_id}/action
Pauses a server andchanges its status toPAUSED. Specify thepause action in therequest body.
Y
When the specifiedserver is in"PAUSED" state onOpenStack side, thestate of the server inIBM Cloud Managerwith OpenStack sideis "SUSPENDED".This is the same stateafter the server wassuspended.
Y Not supported byPowerVC driver.
POSTv2/{tenant_id}/servers/{server_id}/action
Unpauses a PAUSEDserver and changesits status to ACTIVE.Specify the unpauseaction in the requestbody.
Y Not supported byPowerVC driver.
POSTv2/{tenant_id}/servers/{server_id}/action
Suspends a serverand changes its statusto SUSPENDED.Specify the suspendaction in the requestbody.
Y Y Not supported byPowerVC driver.
POSTv2/{tenant_id}/servers/{server_id}/action
Resumes aSUSPENDED serverand changes its statusto ACTIVE. Specifythe resume action inthe request body.
Y Y Not supported byPowerVC driver.
POSTv2/{tenant_id}/servers/{server_id}/action
Locks a server.Specify the lockaction in the requestbody.
Y Y
POSTv2/{tenant_id}/servers/{server_id}/action
Unlocks a server.Specify the unlockaction in the requestbody.
Y Y
POSTv2/{tenant_id}/servers/{server_id}/action
Backs up a serverinstance. Specify thecreateBackup actionin the request body.
Y.
Limitation: Directlybacking up aninstancefromOpenStack sidecreates an image oftype backup. Butfrom IBM CloudManager withOpenStack side, itwill be an image aftersynchronization.
Y Not supported byPowerVC driver.
Chapter 2. IBM OpenStack REST API reference 187
Table 8. Nova API services (continued)
API Description
IBM Cloud Managerwith OpenStack forOpenStackManagement
IBM Cloud Managerwith OpenStack forBase OpenStack IaaS Hypervisor
POSTv2/{tenant_id}/servers/{server_id}/action
Live-migrates aserver to a new hostwithout rebooting.Specify theos-migrateLive actionin the request body.
Y Y Hyper-V andPowerVC drivers donot support thisfunction.
POSTv2/{tenant_id}/servers/{server_id}/action
Resets the state of aserver to a specifiedstate. Specify theos-resetState action inthe request body.
Y Hyper-V andPowerVC drivers donot support thisfunction.
POSTv2/{tenant_id}/servers/{server_id}/action
Evacuates a serverfrom failed host.Specify the evacuateaction in the requestbody.
Y Y Hyper-V andPowerVC drivers donot support"evacuate" function.
Host Aggregates
Creates and manages host aggregates. An aggregate assigns metadata to groups of compute nodes. Aggregates areonly visible to the cloud provider.
GETv2/{tenant_id}/os-aggregates
Lists all aggregates. Y Y
POSTv2/{tenant_id}/os-aggregates
Creates an aggregate. Y Y
DELETEv2/{tenant_id}/os-aggregates/{aggregate_id}
Deletes an aggregate. Y Y
GETv2/{tenant_id}/os-aggregates/{aggregate_id}
Gets details about aspecified aggregate.
Y Y
PUTv2/{tenant_id}/os-aggregates/{aggregate_id}
Updates the name,and optionally theavailability zone, fora specified aggregate.
Y Y
POSTv2/{tenant_id}/os-aggregates/{aggregate_id}/action
Sets metadata for anaggregate.
N N Both Hyper-V andLibvirt drivers inOpenStack do notimplement thisfunction.
POSTv2/{tenant_id}/os-aggregates/{aggregate_id}/action
Adds a host to anaggregate.
N N Both Hyper-V andLibvirt drivers inOpenStack do notimplement thisfunction.
188 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
Table 8. Nova API services (continued)
API Description
IBM Cloud Managerwith OpenStack forOpenStackManagement
IBM Cloud Managerwith OpenStack forBase OpenStack IaaS Hypervisor
POSTv2/{tenant_id}/os-aggregates/{aggregate_id}/action
Removes a host froman aggregate.
N N Both Hyper-V andLibvirt drivers inOpenStack do notimplement thisfunction.
Attach Interfaces (os-interface)
Create, list, get details for, and delete port interfaces.
POST/v2/�{tenant_id}�/servers/�{server_id}�/os-interface
Creates and uses aport interface toattach the port to aserver instance.
YNote:
v You cannot setnet-id or fixed-idoptions when theport-id isspecified.
v Ensure that thevirtual machine,network, and thenewly created portare placed underthe same tenant. Ifnot, the interfaceattach operationfails.
DELETE/v2/�{tenant_id}�/servers/�{server_id}�/os-interface/�{attachment_id}�
Detaches a specifiedport interface.
Y
Server Console Output
Gets the output from the console log for a server.
POSTv2/{tenant_id}/servers/{server_id}/action
Gets console output. Y Y Not supported byPowerVC driver.
Server Extended Create
Shows extra information when you create a server.
POSTv2/{tenant_id}/servers
Creates a server withthe config_driveextended attribute.
Y Y Config drive is notsupported byPowerVC driver.
GETv2/{tenant_id}/servers/{server_id}
Shows informationfor a specified server,including theconfig_drive extendedattribute.
Y Y Config drive is notsupported byPowerVC driver.
GETv2/{tenant_id}/servers/detail
Lists details for allservers, including theconfig_drive extendedattribute.
Y Y Config drive is notsupported byPowerVC driver.
Chapter 2. IBM OpenStack REST API reference 189
Table 8. Nova API services (continued)
API Description
IBM Cloud Managerwith OpenStack forOpenStackManagement
IBM Cloud Managerwith OpenStack forBase OpenStack IaaS Hypervisor
Server Force Delete or Restore
Restores or force-deletes a server when you deploy nova with deferred delete on.Note: Soft delete (that is deferred delete) is not supported by PowerVC driver.
POSTv2/{tenant_id}/servers/{server_id}/action
Force-deletes a server. Y Y
POSTv2/{tenant_id}/servers/{server_id}/action
Reverses the deletionof a server.
Y Y
Disk Config
Extends servers and images with a diskConfig attribute.Note: Automatic disk configuration is not supported byPowerVC driver.
POSTv2/{tenant_id}/servers
Creates a server. Y Y
GETv2/{tenant_id}/servers/{server_id}
Shows informationfor a specified server.
Y Y
PUTv2/{tenant_id}/servers/{server_id}
Updates a specifiedserver.
Y Y
POSTv2/{tenant_id}/servers/{server_id}/action
Resizes a server. Y Y
POSTv2/{tenant_id}/servers/{server_id}/action
Rebuilds a specifiedserver.
Y Y
GETv2/{tenant_id}/servers/detail
Lists servers. Y Y
GETv2/{tenant_id}/images/{image_id}
Describes a specificimage.
Y Y
GETv2/{tenant_id}/images/detail
Lists images. Y Y
Extended Availability Zones
Shows the instance availability zone for compute nodes (nova-compute). Internal services appear in their ownavailability zone.
GETv2/{tenant_id}/servers/{server_id}
Gets the availabilityzone for the specifiedinstance.
Y Y Y
GETv2/{tenant_id}/servers/detail
Lists the details forall servers. Includestheir currentavailability zone.
Y Y Y
190 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
Table 8. Nova API services (continued)
API Description
IBM Cloud Managerwith OpenStack forOpenStackManagement
IBM Cloud Managerwith OpenStack forBase OpenStack IaaS Hypervisor
Image Size
Lists details for available images or gets details for a specified image. Includes the OS-EXT-IMG-SIZE:size extendedattribute, which shows the image size.
GETv2/{tenant_id}/v2/images/detail
Lists details foravailable images.Includes the imagesize.
Y Y
GETv2/{tenant_id}/v2/image/{image_id}
Gets details for aspecified image.Includes the imagesize.
Y Y
Server IP Type
Shows the type of the IP addresses assigned to an instance. Type is either fixed or floating.
GETv2/{tenant_id}/servers/{server_id}/action
Shows the type of IPassigned to aspecified server,either fixed orfloating.
Y Y
GETv2/{tenant_id}/servers/detail
Lists all servers andshow their IPs bytype, either fixed orfloating.
Y Y
Server Extended Attributes
Shows metadata for servers.
GET v2/servers Shows detailedextended serverattribute informationfor all servers.
Y Y
GETv2/servers/{server_id}
Shows extendedserver attributes for aspecified server.
Y Y
Server Extended Status
Shows extended status information, vm_state, task_state, and power_state, in detailed server responses.
GETv2/{tenant_id}/servers/{server_id}
Shows the extendedstatus attributes -–vm_state,power_state, andtask_state -– in theresponse for aspecified server.
Y Y
Chapter 2. IBM OpenStack REST API reference 191
Table 8. Nova API services (continued)
API Description
IBM Cloud Managerwith OpenStack forOpenStackManagement
IBM Cloud Managerwith OpenStack forBase OpenStack IaaS Hypervisor
GETv2/{tenant_id}/servers/detail
Shows the extendedstatus attributes -–vm_state,power_state, andtask_state -– in thedetailed response forall servers.
Y Y
Fixed IPs
Shows data for a specified fixed IP, such as host name, CIDR, and address. Also, reserves or frees a fixed IP.
GETv2/{tenant_id}/os-fixed-ips/{fixed-ip}
Gets data about aspecified fixed IPaddress.
N.
This API is onlysupported byNova-Network.Neutron does notsupport it.
N.
This API is onlysupported byNova-Network.Neutron does notsupport it.
POSTv2/{tenant_id}/os-fixed-ips/{fixed-ip}/action
Reserves a fixed IP. N.
This API is onlysupported byNova-Network.Neutron does notsupport it.
N.
This API is onlysupported byNova-Network.Neutron does notsupport it.
POSTv2/{tenant_id}/os-fixed-ips/{fixed-ip}/action
Unreserves a fixed IP. N.
This API is onlysupported byNova-Network.Neutron does notsupport it.
N.
This API is onlysupported byNova-Network.Neutron does notsupport it.
Flavor Access
Creates and gets details for private flavors. Also, lists, adds, and removes tenant access to private flavors.
GETv2/{tenant_id}/flavors
Lists all flavors.Includes the accesstype, which is publicor private.
Y Y
POSTv2/{tenant_id}/flavors
Creates a privateflavor.
Y Y
GETv2/{tenant_id}/flavors/{flavor_id}
Gets the flavor accesstype, which is eitherpublic or private.
Y Y
GETv2/{tenant_id}/flavors/{flavor_id}/os-flavor-access
Lists tenants withaccess to the specifiedprivate flavor.
Y Y
POSTv2/{tenant_id}/flavors/{flavor_id}/action
Gives the specifiedtenant access to thespecified privateflavor.
Y Y
192 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
Table 8. Nova API services (continued)
API Description
IBM Cloud Managerwith OpenStack forOpenStackManagement
IBM Cloud Managerwith OpenStack forBase OpenStack IaaS Hypervisor
POSTv2/{tenant_id}/flavors/{flavor_id}/action
Revokes access fromthe specified tenantfor the specifiedprivate flavor.
Y Y
Flavor Extra-Specs
Lists, creates, and updates the extra-specs or keys for a flavor.
GETv2/{tenant_id}/flavors/{flavor_id}/os-extra_specs
Lists the extra-specsor keys for thespecified flavor.
Y Y
POSTv2/{tenant_id}/flavors/{flavor_id}/os-extra_specs
Creates extra-specs orkeys for the specifiedflavor.
Y Y
PUTv2/{tenant_id}/flavors/{flavor_id}/os-extra_specs
Updates the value ofthe specifiedextra-spec or key.
Y Y
GETv2/{tenant_id}/flavors/{flavor_id}/os-extra_specs/{key}
Gets the value of thespecified key.
Y Y
Flavors with rxtx_factor Extended Attribute
Creates a flavor, gets details for a specified flavor, and lists details for available flavors. Includes the extendedattribute, which is related to configured bandwidth cap values.
POSTv2/{tenant_id}/flavors
Creates a flavor.Includes therxtx_factor extendedattribute.
Y Y
GETv2/{tenant_id}/flavors/{flavor_id}
Gets details for aspecified flavor.Includes therxtx_factor extendedattribute.
Y Y
GETv2/{tenant_id}/flavors/detail
Lists details foravailable flavors.Includes therxtx_factor extendedattribute.
Y Y
Flavors with Extended Attributes
Creates a flavor, gets details for a flavor, and lists details for available flavors. Includes the rxrx_factor,OS-FLV-EXT-DATA:ephemeral, and swap extended attributes.
Chapter 2. IBM OpenStack REST API reference 193
Table 8. Nova API services (continued)
API Description
IBM Cloud Managerwith OpenStack forOpenStackManagement
IBM Cloud Managerwith OpenStack forBase OpenStack IaaS Hypervisor
POSTv2/{tenant_id}/flavors
Creates a flavor.Includes therxtx_factor,OS-FLV-EXT-DATA:ephemeral, andswap extendedattributes.
Y Y
GETv2/{tenant_id}/flavors/{flavor_id}
Gets details for aspecified flavor.Includes therxtx_factor,OS-FLV-EXT-DATA:ephemeral, andswap extendedattributes.
Y Y
GETv2/{tenant_id}/flavors/detail
Lists details foravailable flavors.Includes therxtx_factor,OS-FLV-EXT-DATA:ephemeral, andswap extendedattributes.
Y Y
Flavors Create or Delete
Creates or deletes flavors.
POSTv2/{tenant_id}/flavors
Creates a flavor. Y Y
DELETEv2/{tenant_id}/flavors/{flavor_id}
Deletes a flavor. Y Y
Hosts
Manages physical hosts.
GETv2/{tenant_id}/os-hosts
Lists all hosts. Y Y
GETv2/{tenant_id}/{host-name}
Shows informationfor a specified host.
Y Y
PUTv2/{tenant_id}/{host-name}
Enables a host orputs it inmaintenance mode.
N N Both Hyper-V andKVM drivers do notimplement thisfunction onOpenStack
POSTv2/{tenant_id}/{host-name}
Starts a host. N N Both Hyper-V andKVM drivers do notimplement thisfunction onOpenStack
194 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
Table 8. Nova API services (continued)
API Description
IBM Cloud Managerwith OpenStack forOpenStackManagement
IBM Cloud Managerwith OpenStack forBase OpenStack IaaS Hypervisor
POSTv2/{tenant_id}/{host-name}
Shuts down a host. N N Both Hyper-V andKVM drivers do notimplement thisfunction onOpenStack
POSTv2/{tenant_id}/{host-name}
Reboots a host. N N Both Hyper-V andKVM drivers do notimplement thisfunction onOpenStack
Hypervisors
Displays extra statistical information from the system that hosts the hypervisor through the API for the hypervisor(XenAPI or KVM/libvirt).
GETv2/{tenant_id}/os-hypervisors
Lists hypervisorsinformation for eachserver that isobtained through thehypervisor-specificAPI, such as libvirt orXenAPI.
Y Y
GETv2/{tenant_id}/os-hypervisors/{host-name}/servers
Shows detailedhypervisors APIinformation for eachserver. Typicallyconfigured as anadmin-only extensionby using policy.jsonsettings.
Y Y
Server List Actions or Get Action Details
Provides rights to all users to list available actions for a specified server. Provides permissions for administrators toget details for a specified action for a specified server.
GETv2/{tenant_id}/servers/{server_id}/os-instance-actions
Lists available actionsfor a specified server.Deployers setpermissions for thisrequest in the file. Bydefault, all users canlist actions.
Y Y
GETv2/{tenant_id}/servers/{server_id}/os-instance-actions/{action_id}
Gets details for aspecified action for aspecified serverinstance. Deployersset permissions forthis request in thefile. By default, onlyadministrators canget details for anaction.
Y Y
Chapter 2. IBM OpenStack REST API reference 195
Table 8. Nova API services (continued)
API Description
IBM Cloud Managerwith OpenStack forOpenStackManagement
IBM Cloud Managerwith OpenStack forBase OpenStack IaaS Hypervisor
Keypairs
Generates, imports, and deletes SSH keys.
GETv2/{tenant_id}/os-keypairs
Lists keypairsassociated with theaccount.
Y Y Not supported byPowerVC driver.
POSTv2/{tenant_id}/os-keypairs
Generates or importsa keypair.
Y Y Not supported byPowerVC driver.
DELETEv2/{tenant_id}/os-keypairs/{keypair_name}
Deletes a keypair. Y Y Not supported byPowerVC driver.
GETv2/{tenant_id}/os-keypairs/{keypair_name}
Shows a keypair thatis associated with theaccount.
Y Y Not supported byPowerVC driver.
Server Multiple Create
Creates one or more servers with an optional reservation ID. The request and response examples show how tocreate multiple servers with or without a reservation ID.
POSTv2/{tenant_id}/servers
Creates one or moreservers with anoptional reservationID.
Y Y
Quota Sets
Permits administrators, depending on policy settings, to view quotas for a tenant and view and update defaultquotas.
To use quotas, The quota_driver has to be set to nova.quota.DbQuotaDriver.
GETv2/{tenant_id}/os-quota-sets/{tenant_id}
Shows quotas for atenant.
Y Y
POSTv2/{tenant_id}/os-quota-sets/{tenant_id}
Updates quotas for atenant.
Y Y
GETv2/{tenant_id}/os-quota-sets/{tenant_id}/defaults
Gets default quotasfor a tenant.
Y Y
Server Rescue
Rescues or unrescues a server.
POSTv2/{tenant_id}/servers/{server_id}/action
Puts a server inrescue mode.Changes status toRESCUE.
Y Y Not supported byPowerVC driver.
POSTv2/{tenant_id}/servers/{server_id}/action
Returns a server to itsstate before it wasrescued.
Y Y Not supported byPowerVC driver.
196 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
Table 8. Nova API services (continued)
API Description
IBM Cloud Managerwith OpenStack forOpenStackManagement
IBM Cloud Managerwith OpenStack forBase OpenStack IaaS Hypervisor
Scheduler Hints
Provides information directly to the scheduler when you create a server.
POSTv2/{tenant_id}/servers
Creates a server byusing scheduler hints.
Y Y
Security Groups
Creates, modifies, and deletes security groups and rules.Note: The PowerVC driver does not support adding or removing security groups to and from an instance. Ingeneral, security groups and security group rules are not supported by PowerVC driver currently.
GETv2/{tenant_id}/os-security-groups
Lists security groups. Y Y
POSTv2/{tenant_id}/os-security-groups
Creates a securitygroup.
Y Y
GETv2/{tenant_id}/os-security-groups/{security_group_id}
Gets information fora specified securitygroup.
Y Y
DELETEv2/{tenant_id}/os-security-groups/{security_group_id}
Deletes a specifiedsecurity group.
Y Y
POSTv2/{tenant_id}/os-security-group-rules
Creates a securitygroup rule.
Y Y
POSTv2/{tenant_id}/os-security-group-rules/{rule_id}
Deletes a securitygroup rule.
Y Y
GETv2/{tenant_id}/servers/{server_id}/os-security-groups
Lists security groupsfor a specified server.
Y Y
Server Start or Stop
Starts or stops a server.
POSTv2/{tenant_id}/servers/{server_id}/action
Halts a runningserver. Changes statusto STOPPED.
Y Y
POSTv2/{tenant_id}/servers/{server_id}/action
Returns a STOPPEDserver to ACTIVEstatus.
Y Y
Manage Services
Lists, enables, and disables Nova services in all hosts.
Chapter 2. IBM OpenStack REST API reference 197
Table 8. Nova API services (continued)
API Description
IBM Cloud Managerwith OpenStack forOpenStackManagement
IBM Cloud Managerwith OpenStack forBase OpenStack IaaS Hypervisor
GETv2/{tenant_id}/os-services
Lists all runningservices.
Y Y
PUTv2/{tenant_id}/os-services
Enables schedulingfor a service.
Y Y
PUTv2/{tenant_id}/os-services
Disables schedulingfor a service.
Y Y
Usage Reports
Reports usage statistics on compute and storage resources.
GETv2/{tenant_id}/os-simple-tenant-usage
Lists usageinformation for alltenants.
Y Y
GETv2/{tenant_id}/os-simple-tenant-usage/{tenant_id}
Gets usageinformation for atenant.
Y Y
Virtual Interfaces
Lists the virtual interfaces for a specified server instance.
GETv2/{tenant_id}/servers/{server_id}/os-vertual-interfaces
Lists the virtualinterfaces for aspecified instance.
Y Y
Volume Attachments
Attaches volumes created through the volume API to server instances. Also, lists volume attachments for a serverinstance, gets volume details for a volume attachment, and deletes a volume attachment.
POSTv2/servers/{server_id}/os-volume_attachments
Attaches a volume tothe specified server.
Y Y
GETv2/servers/{server_id}/os-volume_attachments
Lists the volumeattachments for thespecified server.
Y Y
GETv2/servers/{server_id}/os-volume_attachments/{attachment_id}
Lists volume detailsfor the specifiedvolume attachmentID.
Y Y
DELETEv2/servers/{server_id}/os-volume_attachments/{attachment_id}
Deletes the specifiedvolume attachmentfrom the specifiedserver.
Y Y
Host maintenance modeUse maintenance mode to enable or disable a host system for maintenance.
198 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
The PowerVC driver provides an API to enable (with or without evacuation) or disable host maintenancemode.
Table 9. Overall host maintenance mode options
Method URI Description
GET /v2/{tenant-id}/os-host-maintenance-mode/{host_name}
Gets the host maintenance mode of specified host name.
PUT /v2/{tenant-id}/os-host-maintenance-mode/{host_name}
Enables or disables the host maintenance mode for the specified hostname.
GET host maintenance mode
Table 10. GET host maintenance mode options
Method URI Description
GET /v2/{tenant-id}/os-host-maintenance-mode/{host_name}
Gets the host maintenance mode of specified host name.
Request parameters:
1. tenant-id: The tenant ID in a multi-tenancy cloud.2. host_name: The name of a host.
Request body:No request body.
Response body:{"maintenance_status": "ok"/"entering"/"on"/"error", "maintenance_migration_action":"none"/"active"/"all"}
Set host maintenance mode
Table 11. Put host maintenance mode options
Method URI Description
PUT /v2/{tenant-id}/os-host-maintenance-mode/{host_name}
Enables or disables the host maintenance mode for the specified hostname.
Request parameters:
1. tenant-id: The tenant ID in a multi-tenancy cloud.2. host_name: The name of a host.
Request body:
Table 12. Request body options
Parameter Option Description
status enable or disable Set enable to enter the hostmaintenance mode. Set disable to exitthe host maintenance mode. No otherparameters must be set.
Chapter 2. IBM OpenStack REST API reference 199
Table 12. Request body options (continued)
Parameter Option Description
migrate active-only or none If you set status to enable, setmigrate to active-only to migrate allactive virtual machines to anotherhost. If you set migrate to none ordid not specify a value, then thevirtual machines are not migrated toanother host.
target_host none or #host-name Applicable only when enablingmaintenance mode and specifying amigration action other than none. Ifspecified, describes the target host towhich the virtual machines aremigrated.
Response body:{"hypervisor_maintenance": {"status": "enable"/"disable", "migrate": "none"/"active","hypervisor_hostname": "{host-name}"}}
200 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
Related information
Find information related to this publication.
IBM Knowledge CenterIBM Cloud Manager with OpenStack
© Copyright IBM Corp. 2011, 2014 201
202 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
Accessibility
IBM Cloud Manager with OpenStack does not interfere with the accessibility features for supportedbrowsers. For a comprehensive list of accessibility features please visit the accessibility support page forthe supported browser that you are using. For a list of supported browsers, see Supported web browsers.
No hardcopy publications are shipped with this program. The IBM Knowledge Center is a worldwidecentral repository of IBM technical publications hosted in a single application, located at a single URL:
http://www-01.ibm.com/support/knowledgecenter/
Find and navigate technical content more efficiently and easily with improved search, filtering and userexperience. Create your own collections of IBM documents with PDF output on-demand.
Note: You can find the IBM Cloud OpenStack Platform product collection here:
http://www-01.ibm.com/support/knowledgecenter/SSUTA8/welcome
When you send information to IBM, you grant IBM a nonexclusive right to use or distribute theinformation in any way it believes appropriate without incurring any obligation to you.
© Copyright IBM Corp. 2011, 2014 203
204 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
Notices
This information was developed for products and services offered in the U.S.A. This material may beavailable from IBM in other languages. However, you may be required to own a copy of the product orproduct version in that language in order to access it.
IBM may not offer the products, services, or features discussed in this document in other countries.Consult your local IBM representative for information on the products and services currently available inyour area. Any reference to an IBM product, program, or service is not intended to state or imply thatonly that IBM product, program, or service may be used. Any functionally equivalent product, program,or service that does not infringe any IBM intellectual property right may be used instead. However, it isthe user's responsibility to evaluate and verify the operation of any non-IBM product, program, orservice.
IBM may have patents or pending patent applications covering subject matter described in thisdocument. The furnishing of this document does not grant you any license to these patents. You can sendlicense inquiries, in writing, to:
IBM Director of LicensingIBM CorporationNorth Castle DriveArmonk, NY 10504-1785U.S.A.
For license inquiries regarding double-byte character set (DBCS) information, contact the IBM IntellectualProperty Department in your country or send inquiries, in writing, to:
Intellectual Property LicensingLegal and Intellectual Property LawIBM Japan Ltd.1623-14, Shimotsuruma, Yamato-shiKanagawa 242-8502 Japan
The following paragraph does not apply to the United Kingdom or any other country where suchprovisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATIONPROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS ORIMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OFNON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Somestates do not allow disclaimer of express or implied warranties in certain transactions, therefore, thisstatement may not apply to you.
This information could include technical inaccuracies or typographical errors. Changes are periodicallymade to the information herein; these changes will be incorporated in new editions of the publication.IBM may make improvements and/or changes in the product(s) and/or the program(s) described in thispublication at any time without notice.
Any references in this information to non-IBM Web sites are provided for convenience only and do not inany manner serve as an endorsement of those Web sites. The materials at those Web sites are not part ofthe materials for this IBM product and use of those Web sites is at your own risk.
IBM may use or distribute any of the information you supply in any way it believes appropriate withoutincurring any obligation to you.
© Copyright IBM Corp. 2011, 2014 205
Licensees of this program who wish to have information about it for the purpose of enabling: (i) theexchange of information between independently created programs and other programs (including thisone) and (ii) the mutual use of the information which has been exchanged, should contact:
IBM CorporationDept. LRAS/Bldg. 90311501 Burnet RoadAustin, TX 78758-3400U.S.A.
Such information may be available, subject to appropriate terms and conditions, including in some cases,payment of a fee.
The licensed program described in this document and all licensed material available for it are providedby IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement,IBM License Agreement for Machine Code, or any equivalent agreement between us.
Any performance data contained herein was determined in a controlled environment. Therefore, theresults obtained in other operating environments may vary significantly. Some measurements may havebeen made on development-level systems and there is no guarantee that these measurements will be thesame on generally available systems. Furthermore, some measurements may have been estimated throughextrapolation. Actual results may vary. Users of this document should verify the applicable data for theirspecific environment.
Information concerning non-IBM products was obtained from the suppliers of those products, theirpublished announcements or other publicly available sources. IBM has not tested those products andcannot confirm the accuracy of performance, compatibility or any other claims related to non-IBMproducts. Questions on the capabilities of non-IBM products should be addressed to the suppliers ofthose products.
All statements regarding IBM's future direction or intent are subject to change or withdrawal withoutnotice, and represent goals and objectives only.
All IBM prices shown are IBM's suggested retail prices, are current and are subject to change withoutnotice. Dealer prices may vary.
This information is for planning purposes only. The information herein is subject to change before theproducts described become available.
This information contains examples of data and reports used in daily business operations. To illustratethem as completely as possible, the examples include the names of individuals, companies, brands, andproducts. All of these names are fictitious and any similarity to the names and addresses used by anactual business enterprise is entirely coincidental.
COPYRIGHT LICENSE:
This information contains sample application programs in source language, which illustrate programmingtechniques on various operating platforms. You may copy, modify, and distribute these sample programsin any form without payment to IBM, for the purposes of developing, using, marketing or distributingapplication programs conforming to the application programming interface for the operating platform forwhich the sample programs are written. These examples have not been thoroughly tested under allconditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of theseprograms. The sample programs are provided "AS IS", without warranty of any kind. IBM shall not beliable for any damages arising out of your use of the sample programs.
206 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
Each copy or any portion of these sample programs or any derivative work, must include a copyrightnotice as follows:
© IBM Corp. 2014. Portions of this code are derived from IBM Corp. Sample Programs. © Copyright IBMCorp. 2012, 2014.
If you are viewing this information in softcopy, the photographs and color illustrations may not appear.
TrademarksIBM, the IBM logo, and ibm.com® are trademarks or registered trademarks of International BusinessMachines Corporation in the United States, other countries, or both. If these and other IBM trademarkedterms are marked on their first occurrence in this information with a trademark symbol (® and ™), thesesymbols indicate U.S. registered or common law trademarks owned by IBM at the time this informationwas published. Such trademarks may also be registered or common law trademarks in other countries. Acurrent list of IBM trademarks is available on the Web at Copyright and trademark information atwww.ibm.com/legal/copytrade.shtml
Adobe, the Adobe logo, PostScript, and the PostScript logo are either registered trademarks or trademarksof Adobe Systems Incorporated in the United States, and/or other countries.
Intel, Intel logo, Intel Inside, Intel Inside logo, Intel Centrino, Intel Centrino logo, Celeron, Intel Xeon,Intel SpeedStep, Itanium, and Pentium are trademarks or registered trademarks of Intel Corporation or itssubsidiaries in the United States and other countries.
Java and all Java-based trademarks and logos are trademarks or registered trademarks of Oracleand/or its affiliates.
Linux is a trademark of Linus Torvalds in the United States, other countries, or both.
Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in theUnited States, other countries, or both.
UNIX is a registered trademark of The Open Group in the United States and other countries.
Other company, product, or service names may be trademarks or service marks of others.
Privacy policy considerationsIBM Software products, including software as a service solutions, (“Software Offerings”) may use cookiesor other technologies to collect product usage information, to help improve the end user experience, totailor interactions with the end user or for other purposes. In many cases no personally identifiableinformation is collected by the Software Offerings. Some of our Software Offerings can help enable you tocollect personally identifiable information. If this Software Offering uses cookies to collect personallyidentifiable information, specific information about this offering’s use of cookies is set forth below.
Depending upon the configurations deployed, this Software Offering may use session and persistentcookies that collect each user’s user name and password for purposes of session management,authentication, and enhanced user usability. These cookies cannot be disabled.
Notices 207
If the configurations deployed for this Software Offering provide you as customer the ability to collectpersonally identifiable information from end users via cookies and other technologies, you should seekyour own legal advice about any laws applicable to such data collection, including any requirements fornotice and consent.
For more information about the use of various technologies, including cookies, for these purposes, SeeIBM’s Privacy Policy at http://www.ibm.com/privacy and IBM’s Online Privacy Statement athttp://www.ibm.com/privacy/details the section entitled “Cookies, Web Beacons and OtherTechnologies” and the “IBM Software Products and Software-as-a-Service Privacy Statement” athttp://www.ibm.com/software/info/product-privacy.
Code license and disclaimer informationIBM grants you a nonexclusive copyright license to use all programming code examples from which youcan generate similar function tailored to your own specific needs.
SUBJECT TO ANY STATUTORY WARRANTIES WHICH CANNOT BE EXCLUDED, IBM, ITSPROGRAM DEVELOPERS AND SUPPLIERS MAKE NO WARRANTIES OR CONDITIONS EITHEREXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES ORCONDITIONS OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, ANDNON-INFRINGEMENT, REGARDING THE PROGRAM OR TECHNICAL SUPPORT, IF ANY.
UNDER NO CIRCUMSTANCES IS IBM, ITS PROGRAM DEVELOPERS OR SUPPLIERS LIABLE FORANY OF THE FOLLOWING, EVEN IF INFORMED OF THEIR POSSIBILITY:1. LOSS OF, OR DAMAGE TO, DATA;2. DIRECT, SPECIAL, INCIDENTAL, OR INDIRECT DAMAGES, OR FOR ANY ECONOMIC
CONSEQUENTIAL DAMAGES; OR3. LOST PROFITS, BUSINESS, REVENUE, GOODWILL, OR ANTICIPATED SAVINGS.
SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OR LIMITATION OF DIRECT,INCIDENTAL, OR CONSEQUENTIAL DAMAGES, SO SOME OR ALL OF THE ABOVE LIMITATIONSOR EXCLUSIONS MAY NOT APPLY TO YOU.
208 IBM Cloud Manager with OpenStack: REST API Reference, version 4.2
����
Printed in USA