IaaS REST APIs

The Infrastructure as a Service (IaaS) API layer is an implementation of the IaaS specification Version 3.0.

Some implementation choices are listed as follows:

• The only supported data format is JavaScript Object Notation (JSON).
• All resources define their IaaS ID as a type-4 Universal Unique Identifier (UUID).
• The API implements some optional features for HTTP GET operations for maximum flexibility when querying system data. Features include paging and filtering capabilities.
• Relationships in resources are resolved in a single HTTP GET operation by using the ?resolvechildren=ALL query parameter. Using this parameter enables clients to get a more complete resource model without multiple requests.
• All GET requests against every resource always interact with the local database and never trigger a job.
• This implementation does not use the tags construct that is described in the specification.

IaaS resources, along with a brief description of implementation, are included in the following list:

Address

The address resource is handled through local operations by the database. It enables the user to supply an IP address for linking to a subnet. The address and subnet information can be used later for deployments. The address table must handle both IPv6 and IPv4 addresses.

Capability

The capability resource is not used at this time.

Credential

The credential resource is handled through local operations by the database. To define the actual content of this resource, use the username and password fields, not the options field.

Group

The group resource is used as a grouping mechanism for the instances. The group information should exist as long as the instances that are bound by the group exist. Other objects such as volumes, address, and so on, can also be part of the group but do not impact placement. Groups can also be used to start multiple deployment operations in one POST operation.

Image

As with the other resources, GET operations are against the database. A POST operation creates a JOB that saves a copy of the Open Virtualization Format (OVF) and a copy of the binaries in the storage controller. It also drives against FRM to store the image against VIOS. A DELETE operation creates a JOB that removes the image from the LUN and VIOS. This implementation only supports OVF images.

Images are considered to be immutable, according to the IaaS specifications. After an image has been imported into the system, any associated files and configuration cannot be updated. In addition, a periodic job runs in the background to synchronize the images that are stored in the Cloud Pak System database with the ones that are available in VMControl or VMware. So if someone imports or deletes any image directly using hypervisor, the change gets automatically synchronized into Cloud Pak System after a few minutes.

Instance

As with the other resources, GET operations are against the database. However, there is a background task that queries the back-end system to ensure that new virtual machines have not appeared unexpectedly.

The POST operation returns a JOB that tracks the creation of the instance.

PUT operations that change the state of a virtual machine also result in a JOB.

A periodic job runs in the background to synchronize the state of the instances that are stored in the Cloud Pak System database with the ones that are available in VMControl or VMware. If an instance gets stopped or started directly from hypervisor, the change gets automatically synchronized into Cloud Pak System after a few minutes. The frequency of how often the job runs is specified through the /config/recurring/jobs property that is defined in the Cloud Pak System.hardware/config/events.config file.

The section that contains the configuration of the image sync job is the following:

{
        "action": "query_compute_nodes", 
        "type": "nodes", 
        "interval": 120000

}

By default, this job runs every two minutes. After the configuration has been modified, the job manager must be restarted to apply the changes.

Instance snapshot

As with the other resources, GET operations are against the database.

The POST operation returns a JOB that tracks the creation of the snapshot that is related to an instance.

PUT operation that change the state of the snapshot also result in a JOB. The revert replaces the instance with the snapshot.

During the synchronization of the images, the snapshots that are associated to the instances are synchronized as well.

Location

The location resource is not used at this time for the IaaS interactions. It is used for Rack and Cluster location, however.

Job

The job resource monitors the operations that are triggered in the context of other resources, such as images or instances. A job resource cannot be directly created or updated from a REST invocation. A job is created only as a consequence of another interactions, such as the deployment of an image.

Subnet

The subnet resource is handled through local operations by the database. The table stores a subnet definition for later deployment by the user.

Virtual data center

The virtual data center resource is handled through local operations by the database. This resource scopes the reach of the cloud groups.

Virtual machine configuration

The virtual machine configuration resource is handled through local operations by the database. This resource defines the various virtual machine shapes, sometimes called T-Shirt sizes, that are supported.

Volume

The volume resource table interacts with the database for GET requests. A POST operation results in a JOB that drives against the storage controller to create the given volume against the chosen VM. PUT and DELETE operations also result JOBs after a database creation.

Volume configuration

The volume configuration resource is handled through local operations by the database. This table holds different configurations of Volumes. The client can define different volume types. Cloud Pak System provides sample volume types and enables others to be posted and queried.

Volume snapshot

The volume snapshot resource is not used at this time

All IaaS REST APIs use application/json for the data format.