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

��

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

http://docs.jboss.org/resteasy/docs/1.0.0.GA/javadocs/javax/ws/rs/core/Response.Status.html

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",


"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


Sample Response

HTTP Status: 200

Localized values: "state"

HTTP Response Body:


{

"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": {


},"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


Sample Response

HTTP Status: 200


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


cpu The desired CPU size 0 No



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


"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


Sample Request

To retrieve the default customization for appliance with ID 347:

GET http://host/cloud/api/appliances/1/customization

Sample Response


"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",


"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": {


},"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": {


},"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": {


},"name": "openstack.server.personality.source.1","required": false,"type": "STRING",


"rules": [{

"id": "maxlen","value": "65536"

}]

},{


""],"basic": false,"description": "Enter the target path and file name for personality file 1","classification": {


},"name": "openstack.server.personality.target.1","required": false,"type": "STRING"

},{




},"name": "openstack.server.personality.source.2","required": false,"type": "STRING","rules": [


}]

},{





},{






}]

},


{"category": "Virtual Machine Personality Files","values": [




},{






}]

},{





},{






}]

},{


""],"basic": false,"description": "Enter the target path and file name for personality file 5",


"classification": {"id": "SOFTWARE","label": "Software"


}],"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.


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


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.


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


"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


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.


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"


],"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.


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


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]


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.


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


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


"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"

}]

}


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.


Sample Request

GET http://host/cloud/api/accounts/1


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":{


},"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


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


Sample Response

HTTP Status: 200


"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]"

}]

}


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",


"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": [{



},"username": "test","name": "test","emailNotifications": false,"isApprover": false

}]

}

Sample Response 1

HTTP Status: 201


"users":[{

"isAdmin":true,"username":"admin","name":"Admin","emailNotifications":false,"isApprover":true

}]

}


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


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


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"

}]

}


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


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."

}


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


Sample Response

HTTP Status: 200



"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"


},{

"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


Sample Response

HTTP Status: 200



"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

}


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


Sample Response

HTTP Status: 200


"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


Sample Response

HTTP Status: 200


"name":"Administrator","id":"admin","uri":"http://localhost:18080/cloud/api/billing/paymentAuthorizers/admin"

}


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


"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",


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.


Query Parameters

N/A

Sample Request

Get the ldap.xml file

GET http://host/cloud/api/configuration/ldap.xml


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.


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>


<step><authDN>{PERSON_DN}</authDN>

</step></config>

Sample Response

HTTP Status: 200

GET /configuration/ldapCertThis service retrieves the LDAP certificates from the keystore file.


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

- - - - - -- - -

- - - - - - - -

]


PUT /configuration/ldapCertThis service updates the LDAP keystore file with the certificate provided.


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:


{-"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”

}


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"

}


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":[{


"timeout":600,"state":{


},"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


"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?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


"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



{"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


Sample Request 2

Untrust the current cloud connection and certificate.PUT http://host/cloud/api/clouds/{id}?trust=false

Sample Response 2



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


Sample Response

HTTP Status: 200


"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


Sample Response

HTTP Status: 200


"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"

}


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


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.


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


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


null No


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


Sample Response

HTTP Status: 200


"events":[{

"resources":[{


"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":{


}},{

"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":{


}},{

"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":{



}}

],"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


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


null No


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


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.


Query Parameters

N/A

Sample Request

GET http://host/cloud/api/events/105


Sample Response

HTTP Status: 200


"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



Sample Response

HTTP Status: 200


"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"

},{


}]

}

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

}


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


Sample Response

HTTP Status: 200



}

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,


"maxExpirationPeriodWithoutSetting": 1825,"workloadExpirationSettingAppliable": true

}

Sample Response

HTTP Status: 200


"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


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"}


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


Sample Response

HTTP Status: 200


"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"


}]

}

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


Sample Response

HTTP Status: 200


"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"

}


Sample Response 1

HTTP Status: 201


{"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


{"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"}

}


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


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"}


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


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.


Sample Request

GET http://host/cloud/api/udrfiles/{directoryName}


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}


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


Query Parameters


userId Gets the UDRs that can beviewed by this userId.

N/A No

globalObjectId Gets the UDRs for thespecified globalObjectId.

N/A No



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,


"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}



Sample Response

HTTP Status: 200


"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.


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.


Sample Request

GET http://localhost:18080/cloud/api/networkConfigurations


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,


"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",


"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"},


"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.


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",


"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",


"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,


"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.


Query Parameters

N/A

Sample Request

GET http://host/cloud/api/networkConfigurations/304_6c72f74b-f335-4aef-bb23-9afcd89341a44


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"},


"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


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.


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.


Query Parameters

N/A

Sample Request

Remove the network configuration with ID 2053

DELETE http://host/cloud/api/networkConfigurations/2053


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.


Query Parameters


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.


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


Sample Response

HTTP Status: 200


"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.


Query Parameters

N/A


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"

},{


}]

}


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.


Query Parameters

N/A

Sample Request

GET http://host/cloud/api/networkConfigurations/2053/ipAddresses/192.168.1.221


Sample Response

HTTP Status: 200



}

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.


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


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.


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


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


"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"

}]

}



{"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:


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



{"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"

}]

}


"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


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


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


Sample Response

SmartCloud Entry

GET /productInfo/nameThis service retrieves the product's name.


Query Parameters

N/A

Sample Request

GET http://host/cloud/api/productInfo/name


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


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



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


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


Sample Response

HTTP Status: 200


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


Sample Request

GET http://host/cloud/api/productInfo/icon{type}


Sample Response

HTTP Status: 200


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


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



Sample Response

HTTP Status: 200


"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


"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",


"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


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:


{"useCloudExpirationPolicy":false

}

Sample Response

HTTP Status: 200


GET /projects/{id}This service retrieves the attributes of the project identified by id.

Sample Request

GET http://host/cloud/api/projects/1234


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


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



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


Sample Response

HTTP Status: 200


"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": {


},"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": {


},"projectUri": "http://localhost:18080/cloud/api/projects/103001","architecture": "x86","isHidden": false,"cloudGroupName": "VMware-120","hypervisor": "VMware","id": "73508",


"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


Sample Response

HTTP Status: 200



"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": {


},"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": {


},"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)"

}]

}


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


Sample Response

HTTP Status: 200


"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



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


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


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.


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


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


Sample Response

HTTP Status: 200



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


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'.



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


"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


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'.


Sample Response

HTTP Status: 200


"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:


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'.


Sample Response

HTTP Status: 200

HTTP Response Body:


{"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


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


HTTP Request Body: None

Sample Response

HTTP Status: 200


"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


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.


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"

}},{


"label": "Virtual server attach storage request","id": "STORAGE_ATTACH_REQUEST"

}},{


"label": "Virtual server restore","id": "VIRTUAL_SERVER_RESTORE_BACKUP"

}},{


"label": "Virtual server save image","id": "VIRTUAL_SERVER_CREATE_BACKUP"

}},{


"label": "Workload resize","id": "DEPLOYMENT_RESIZE"


}},{


"label": "Workload initiation","id": "DEPLOYMENT_EXECUTION"

}},{


"label": "Workload capture","id": "DEPLOYMENT_SNAPSHOT"

}}

],"uri": "http://localhost:18080/cloud/api/requests/handlers?ownerType=CLOUDGROUP&ownerId=551","ownerType": "CLOUDGROUP","ownerId": "551"

},{

"requestHandlers": [{


"label": "Workload expiration extend","id": "DEPLOYMENT_EXPIRATION_EXTEND"

}},{


"label": "Virtual server detach storage request","id": "STORAGE_DETACH_REQUEST"

}},{


"label": "Virtual server attach storage request","id": "STORAGE_ATTACH_REQUEST"

}},{


"label": "Virtual server restore","id": "VIRTUAL_SERVER_RESTORE_BACKUP"

}},{


"label": "Virtual server save image","id": "VIRTUAL_SERVER_CREATE_BACKUP"

}},{


"label": "Workload resize","id": "DEPLOYMENT_RESIZE"

}},{


"label": "Workload initiation","id": "DEPLOYMENT_EXECUTION"

}},{


"label": "Workload capture","id": "DEPLOYMENT_SNAPSHOT"

}}


],"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


GET /requests/requestcsvExports requests, that are filtered by parameters, to file and saves it on a server architecture directory.


Query Parameters


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


DELETE /requests/requstcsvDeletes requests that are filtered by parameters.


Query Parameters


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


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.


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


Sample Response

HTTP Status: 200


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"

}


]}

]}

GET /stats/totalsThis service retrieves the statistics of all resources in the cloud, such as CPU, memory, and storage.


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


Sample Response

HTTP Status: 200


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"


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.


Query Parameters


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


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"}{


value:"236304.0"label:"Memory"id:"usageMemory"

}{

value:"13645"label:"Storage"id:"usageDisk"

}}{

architecture:"x86"resources: [

{value:"24.0"label:"Processors"id:"usageCPU"

}{


}{


}]

}]}

Sample Request 2

Retrieve resources usage by admin

GET http://host/cloud/api/stats/usage?user=admin


Sample Response 2

HTTP Status: 200

HTTP Response Body:{uri:http://localhost:18080/cloud/api/stats/usage

stats: [{

architecture:"Power"resources: [


}{


}{


}


}{

architecture:"x86"resources: [


}{


}{


}]

}]}

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


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


Sample Response

HTTP Status: 200


"users": [{

"emailNotifications": false,


"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": {


},"isAdmin": false,"uri": "http://9.123.152.202:18080/cloud/api/users/xinzhan","isLocked": false

},{

"emailNotifications": false,"username": "zxx","isApprover": false,"name": "zxx","role": {


},"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]



Sample Response 1

HTTP Status: 200


"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).


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"},


"locale": {"id": "en-US"

}}

Sample Response

HTTP Status: 201


"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"},


"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


Sample Request

Get virtual servers for workload with ID 1:

GET http://host/cloud/api/workloads/1/virtualServers

Sample Response

HTTP Status: 200


"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",


"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




},"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"

},


{"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": [


},{


},{


},{


},{


},{


},{


},{


},{


},{


},{


}],


"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


"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


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 http://host/cloud/api/virtualServers

Sample Response

HTTP Status: 200



"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": "DETACH_DISK"

},{

"isEnabled": false,"id": "THIN_PROVISIONED"

},{

"isEnabled": false,"id": "POWER_MANAGEMENT"

},{

"isEnabled": false,"id": "CAPTURE"

},{

"isEnabled": false,"id": "BACKUP"

},{


},{

"isEnabled": false,"id": "RESIZE"

},{


},


{"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": {


},"backups": "http://localhost:18080/cloud/api/virtualServers/3959/backups","hostname": "CCS-hgq","storagesUri": "http://localhost:18080/cloud/api/virtualServers/3959/storages","capabilities": [


},{


},{


},{


},{


},{


},{


},{


},{


},{


},{


}],"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.


Query Parameters

N/A

Sample Request


GET http://host/cloud/api/virtualServers/203

Sample Response

HTTP Status: 200


"cloudId": "cloud://551/40052","credentialsUri": "http://localhost:18080/cloud/api/workloads/601/virtualServers/651/credentials","state": {



{"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"

},


{"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"

}],


"hostname": "kaiqiang-no-delete","storagesUri": "http://localhost:18080/cloud/api/virtualServers/651/storages","capabilities": [


},{


},{

"isEnabled": false,"id": "DETACH_DISK"

},{

"isEnabled": false,"id": "THIN_PROVISIONED"

},{


},{


},{


},{


},{


},{


},{


}],"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:


{’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


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)


[ 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


"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.


Sample Response

HTTP Status: 200


"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



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.


HTTP Request Body:{

"name":"MyDisk","size":1024,"thinProvisioned":"true","datastore":"MyDataStore"

}

Sample Response 2

HTTP Status: 201


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).


HTTP Request Body:{

"name": "MyDisk","datastore": "MyDataStore""Path": "/mydisk.vmdk"

}

Sample Response 3

HTTP Status: 201


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


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


"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":


{

"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":{


},"gateway2":{


},"domain":{





},"subnet":{


},"networkId":{


},"useDHCP":{


},"wins1":{


},"wins2":{


},"ipAddress":{


},"hostName":{


},"computerName":

{

"value":"skc1",


"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


Sample Response

HTTP Status: 200


"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":{


},"gateway2":{


},"domain":{




},"subnet":{


},"networkId":{


},"useDHCP":{


},"wins1":{


},"wins2":{


},"ipAddress":{


},"hostName":{


},"computerName":

{"value":"skc",



"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


"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


Sample Response

HTTP Status: 200


"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"}


Sample Response

HTTP Status: 200 OK


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


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


"total": "1","repositories": [

{"cloudId": "11632","name": "image_repository"

}],"identifier": "cloudId"

}


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


"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.


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



{"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": {


"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


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



{"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",


"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.


"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": {


},"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}"



},"valueOrigin": [

"{1}"],"subtype": "IPV4_ADDRESS",


"type": "STRING","valueFrom": "dns1","name": "linux.dns1","description": "Primary DNS","category": "TCP/IP Network Settings ","basic": false,"required": false

},{

"values": ["{1}"



},"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}"



},"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


"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,


"required": false},{

"values": ["skc.default.storage"


"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"


},{

"values": [1024


"label": "Hardware","id": "HARDWARE"

},"rules": [


},{


},{

"value": "128","id": "min"

}],"type": "LONG","name": "vmware.memory","description": "Memory (MB)","category": "Memory and CPU Settings","basic": true,"required": false

},{

"values": [1


"label": "Hardware","id": "HARDWARE"

},"rules": [


},{


},{

"value": "12","id": "max"

},{

"value": "1",


"id": "min"}

],"type": "LONG","name": "vmware.cpu","description": "Virtual CPUs","category": "Memory and CPU Settings","basic": true,"required": false

},{

"values": ["VM 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



},"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}"



},"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

},{


"values": ["{1}"



},"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}"



},"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



},"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.


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


"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": {


},"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


dynamicProperties Return the dynamicvirtualization properties forthis workload.

false No

priority Return the priorityproperty of this workload.

false No


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":"128.0","id":"max"

},{


}],"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",


"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":"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":"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,


"required":true},{

"values":["512"

],"rules":[


},{


},{

"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":"240.0","id":"max"

},{


}],"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"

},{


}],"type":"FLOAT","name":"cpushminu","description":"The minimum number of processing units that can be assigned to the virtual server.",


"basic":false,"required":false

},{

"values":["0.1"

],"rules":[


},{


},{


}],"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":"240.0","id":"max"

},{


}],"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":[


},{


},{


}],"type":"FLOAT","name":"cpushmaxu","description":"The maximum number of processing units that can be assigned to the virtual server.","basic":false,"required":false

},


{"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":"255.0","id":"max"

},{


}],"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":[


},{


},{


},{


}],"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"


],"rules":[


},{


},{

"value":"128.0","id":"max"

},{


}],"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"


},{

"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}"




},"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"



},"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"



},"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"



},"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"

],


"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"



},"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"



},"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"



},"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


},{

"values":["192.168.1.17"



},"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"



},"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"



},"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":[



},{


},{



},{

"values":[{

"value":"Network 1","description":"Network Name"

},{


},{



},{

"values":[{


},{


},{

"value":"VLAN 91, Not Bridged","description":"Virtual Networks on Host"


},{

"values":[{


},{


},{



},{

"values":[{


},{


},{




}],"group":"Adapter 1","required":false

},{

"values":["[Network 2]=hostVnet:ETHERNET0/2"



},"valueOrigin": ["{2}"],"type":"SINGLE_SELECTION","valueFrom": "networkId","name":"virtualnetworks-2","description":" Network 2\"","basic":false,"options":[

{"values":[


},{


},{



},{

"values":[{


},{


},{



},{

"values":[{


},{


},{



},{

"values":[{



},{


},{



},{

"values":[{


},{


},{


}],"id":"[Network 2]=hostVnet:ETHERNET0/92"

},{

"values":[{


},{


},{



}],"group":"Adapter 2","required":false

},{

"values":["1"

],"rules":[


},{


},{

"value":"240.0","id":"max"

},{


}],"type":"LONG","name":"cskCPU","description":"CPU","basic":true,"required":false


},{

"values":["512"

],"rules":[


},{


},{

"value":"160512.0","id":"max"

},{

"value":"256.0","id":"min"

}],"type":"LONG","name":"cskRAM","description":"RAM","basic":true,"required":false

},{

"values":[true



},"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


Sample Response

HTTP Status: 200


"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


"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.


Query Parameters

N/A

Sample Request


GET http://host/cloud/api/workloads/1/virtualServers

Sample Response

HTTP Status: 200 HTTP Response Body:{




},"backups": "http://localhost:18080/cloud/api/virtualServers/73555/backups","hostname": "testhost235","storagesUri": "http://localhost:18080/cloud/api/virtualServers/73555/storages","capabilities": [


},{


},{


},{


},{


},{


},{


},{


},{


},{


},{


}],"ip": "10.10.2.235","id": "73555",


"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





{"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"

},{

"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": "BACKUP"},{


},{


},{


},{


}],"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


"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.


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


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


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",


"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"

}


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]


}],"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":[{


"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


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)


GET /workloads/statsThis service retrieves statistics about workloads. The default statistic is the states of the variousworkloads.

Query Parameters


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


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



Sample Response

HTTP Status: 200


"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

},{



},"username": "user1","name": "user1","emailNotifications": false,"uri": "http://localhost:18080/cloud/api/workloads/owners/user1","isApprover": false

},{



},"username": "user2","name": "user2","emailNotifications": false,"uri": "http://localhost:18080/cloud/api/workloads/owners/user2","isApprover": false

}]

}


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


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


http://vs479:9973/770e010856b64d39bf7d622718c55156/public/v2.0/tokens

http://vs479:9973/770e010856b64d39bf7d622718c55156/public/v2.0/tokens

http://api.openstack.org/api-ref.html

http://api.openstack.org/api-ref.html

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



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



API Description



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.



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.



PUTv2.0/tenants/{tenantId}

Updates a tenant. N Y.





API Description



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


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 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


Table 5. Glance API services (continued)

API Description



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.


DELETEv2/images/{image_id}/tags/{tag}

Deletes a specifiedtag from a specifiedimage.


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



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


Table 6. Neutron API services (continued)

API Description



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


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


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


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


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


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



V2

Manages volumes and snapshots for use with the Block Storage Service API (cinder services).

POSTv2{tenant_id}/volumes

Creates a volume. Y Y


Table 7. Cinder API services (continued)

API Description



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.


GETv2{tenant_id}/snapshots

Lists summaryinformation for allCinder snapshots thatare accessible to thetenant who submitsthe request.


GETv2{tenant_id}/snapshots/detail

Lists detailedinformation for allCinder snapshots thatare accessible to thetenant who submitsthe request.


GETv2{tenant_id}/snapshots/{snapshot_id}

Shows informationfor a specifiedsnapshot.



Table 7. Cinder API services (continued)

API Description



PUTv2{tenant_id}/snapshots/{snapshot_id}

Updates a specifiedsnapshot.


DELETEv2{tenant_id}/snapshots/{snapshot_id}

Deletes a specifiedsnapshot.


NovaThe Nova API services that are supported by IBM Cloud Manager with OpenStack are described here.

Table 8. Nova API services

API Description



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.



Table 8. Nova API services (continued)

API Description



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



API Description



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.


Reboots the specifiedserver. Specify thereboot action in therequest body.




API Description




Rebuilds the specifiedserver. Specify therebuild action in therequest body.

Y.

Limitation: Thefollowing propertiescannot besynchronized to IBMCloud Manager withOpenStack: Metadata,adminPass,personality.

Y


Resizes the specifiedserver. Specify theresize action in therequest body.

Y Y


Confirms a pendingresize action. Specifythe confirmResizeaction in the requestbody.

Y Y


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.



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 )


https://bugs.launchpad.net/nova/+bug/1168260




API Description



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.



API Description



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.



Unpauses a PAUSEDserver and changesits status to ACTIVE.Specify the unpauseaction in the requestbody.



Suspends a serverand changes its statusto SUSPENDED.Specify the suspendaction in the requestbody.



Resumes aSUSPENDED serverand changes its statusto ACTIVE. Specifythe resume action inthe request body.



Locks a server.Specify the lockaction in the requestbody.

Y Y


Unlocks a server.Specify the unlockaction in the requestbody.

Y Y


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.




API Description




Live-migrates aserver to a new hostwithout rebooting.Specify theos-migrateLive actionin the request body.

Y Y Hyper-V andPowerVC drivers donot support thisfunction.


Resets the state of aserver to a specifiedstate. Specify theos-resetState action inthe request body.

Y Hyper-V andPowerVC drivers donot support thisfunction.


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.


Adds a host to anaggregate.




API Description




Removes a host froman aggregate.


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.


Gets console output. Y Y Not supported byPowerVC driver.

Server Extended Create

Shows extra information when you create a server.


Creates a server withthe config_driveextended attribute.

Y Y Config drive is notsupported byPowerVC driver.


Shows informationfor a specified server,including theconfig_drive extendedattribute.



Lists details for allservers, including theconfig_drive extendedattribute.




API Description



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.


Force-deletes a server. Y Y


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.


Creates a server. Y Y


Shows informationfor a specified server.

Y Y

PUTv2/{tenant_id}/servers/{server_id}

Updates a specifiedserver.

Y Y


Resizes a server. Y Y


Rebuilds a specifiedserver.

Y Y


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.


Gets the availabilityzone for the specifiedinstance.

Y Y Y


Lists the details forall servers. Includestheir currentavailability zone.

Y Y Y



API Description



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


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.


Shows the extendedstatus attributes -–vm_state,power_state, andtask_state -– in theresponse for aspecified server.

Y Y



API Description




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.


POSTv2/{tenant_id}/os-fixed-ips/{fixed-ip}/action

Reserves a fixed IP. N.


N.


POSTv2/{tenant_id}/os-fixed-ips/{fixed-ip}/action

Unreserves a fixed IP. N.


N.


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



API Description



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.


Creates a flavor.Includes therxtx_factor extendedattribute.

Y Y


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.



API Description




Creates a flavor.Includes therxtx_factor,OS-FLV-EXT-DATA:ephemeral, andswap extendedattributes.

Y Y


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.


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



API Description




Shuts down a host. N N Both Hyper-V andKVM drivers do notimplement thisfunction onOpenStack


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



API Description



Keypairs

Generates, imports, and deletes SSH keys.

GETv2/{tenant_id}/os-keypairs

Lists keypairsassociated with theaccount.


POSTv2/{tenant_id}/os-keypairs

Generates or importsa keypair.


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.


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.


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.


Puts a server inrescue mode.Changes status toRESCUE.



Returns a server to itsstate before it wasrescued.




API Description



Scheduler Hints

Provides information directly to the scheduler when you create a server.


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.


Halts a runningserver. Changes statusto STOPPED.

Y Y


Returns a STOPPEDserver to ACTIVEstatus.

Y Y

Manage Services

Lists, enables, and disables Nova services in all hosts.



API Description



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.


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


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


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.


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}"}}


Related information

Find information related to this publication.

IBM Knowledge CenterIBM Cloud Manager with OpenStack


http://www.ibm.com/support/knowledgecenter/SST55W/welcome

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.


http://www-01.ibm.com/support/knowledgecenter/SSUTA8_4.1.0/liaca/liacasupportedbrowsers.html

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.


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.


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.


http://www.ibm.com/privacy

http://www.ibm.com/privacy/details

http://www.ibm.com/software/info/product-privacy

��

Printed in USA