Supported OpenStack Compute (Nova) APIs

Edit online

These OpenStack APIs are supported in PowerVC.

For usage instructions, see the OpenStack compute API documentation.

General APIs

Table 1. OpenStack compute general APIs that are used with PowerVC.
Method URI Description
GET /v2.1/ Returns detailed information about this specific version of the API.
GET /v2.1/{tenant_id}/extensions Lists all available extensions.
GET /v2.1/{tenant_id}/extensions/{alias} Gets details about a specific extension. Extensions enable the introduction of new features in the API without requiring a version change, and they allow the introduction of vendor-specific functions.

Flavors APIs

Use flavors APIs to work with PowerVC compute templates. PowerVC uses the term compute template instead of flavor.

Table 2. OpenStack compute flavors APIs that are used with PowerVC.
Method URI Description
POST /v2.1/{tenant_id}/flavors Creates a flavor.
GET /v2.1/{tenant_id}/flavors Lists IDs, names, and links for available flavors.
GET /v2.1/{tenant_id}/flavors/detail Lists all details for available flavors.
GET /v2.1/{tenant_id}/flavors/{flavor_id} Lists details for the specified flavor.
DELETE /v2.1/{tenant_id}/flavors/{flavor_id} Deletes a flavor.
GET /v2.1/{tenant_id}/flavors/{flavor_id}/os-extra_specs Lists the extra-specs or keys for the specified flavor.
POST /v2.1/{tenant_id}/flavors/{flavor_id}/os-extra_specs Creates extra-specs or keys for the specified flavor.
GET /v2.1/{tenant_id}/flavors/{flavor_id}/os-extra_specs/{key_id} Gets the value of the specified key.
DELETE /v2.1/{tenant_id}/flavors/{flavor_id}/os-extra_specs/{key_id} Delete a specified extra-spec by key.

Host aggregates (host groups) APIs

Note: The PowerVC user interface uses the term host groups instead of host aggregates.
Table 3. OpenStack compute host aggregates (host groups) APIs that are used with PowerVC.
Method URI Description
GET /v2.1/​{tenant_id}​/os-aggregates Lists all aggregates.
POST /v2.1/​{tenant_id}​/os-aggregates Creates an aggregate.
DELETE /v2.1/{tenant_id}/os-aggregates/​{aggregate_id} Deletes an aggregate.
GET /v2.1/{tenant_id}/os-aggregates/​{aggregate_id} Gets details about a specified aggregate.
PUT /v2.1/{tenant_id}/os-aggregates/​{aggregate_id} Updates the name, and optionally the availability zone, for a specified aggregate.
PUT /v2.1/{tenant_id}/os-aggregates/​{aggregate_id} Sets and updates the DRO schedules for the specified aggregate.
POST /v2.1/{tenant_id}/os-aggregates/​{aggregate_id}​/action Sets metadata for an aggregate.
POST /v2.1/{tenant_id}/os-aggregates/​{aggregate_id}​/action Adds a host to an aggregate.
POST /v2.1/{tenant_id}/os-aggregates/​{aggregate_id}​/action Removes a host from an aggregate.

Hypervisors APIs

Table 4. OpenStack compute hypervisors APIs that are used with PowerVC.
Method URI Description
GET /v2.1/{tenant_id}/os-hypervisors Lists hypervisor information per server that is obtained through the API that is specific to the hypervisor, such as libvirt or XenAPI.
GET /v2.1/{tenant_id}/os-hypervisors/detail Lists details of the hypervisors that are managed by the OpenStack installation.
GET /v2.1/{tenant_id}/os-hypervisors/{hypervisor_hostname} Gets detailed information for the specified hypervisor. Supported parameters:

include_cpu_utilization: Specifies whether to include the CPU utilization in the response. Possible values are True (default) and False.

include_remote_restart_enabled: Specifies whether to include the value for Remote restart enabled in the response. Possible values are True (default) and False.

include_memory_utilization: Specifies whether to include the current memory utilization of the host. Possible values are True (default) and False.

Note: HMC currently does not support the memory utilization metric and reports "0."
GET /v2.1/{tenant_id}/os-hypervisors/{hypervisor_hostname}/servers Retrieves a list of servers and virtual machines that are hosted by the specified hypervisor.

GET

 v2.1/{tenant_id}/os-hypervisors/{hypervisor_hostname}?include_virtual_serial_numbers Gets detailed information for the specified hypervisor with virtual serial numbers (VSNs) included. For the supported available parameter,
  • When set to True, only free and available VSNs from the hypervisor host are included. This option excludes the VSNs in-use.
  • When set to False or no value is provided, all VSNs (in-use or free) in the specified hypervisor host are included.

Image APIs

Table 5. OpenStack compute image APIs that are used with PowerVC.
Method URI Description
GET /v2.1/{tenant_id}/images Lists all images.
GET /v2.1/{tenant_id}/images/detail Lists all details for available images.
GET /v2.1/{tenant_id}/images/{image_id} Lists details of the specified image.
DELETE /v2.1/{tenant_id}/images/{image_id} Deletes the specified image.

Interface APIs

Table 6. OpenStack compute interface APIs that are used with PowerVC.
Method URI Description
POST /v2/{tenant_id}/servers/{server_id}/os-interface Creates a port interface and uses it to attach the port to a server instance. If you pre-create a port, try to attach a virtual machine to it, and the attach fails, you must manually delete or reuse the port.
DELETE /v2/{tenant_id}/servers/{server_id}/os-interface/{attachment_id} Detaches the specified port interface from the virtual machine and then deletes the port.

Key Pair APIs

Table 7. OpenStack compute key pairs APIs that are used with PowerVC.
Method URI Description
GET /v2.1/​{tenant_id}​/os-keypairs Lists keypairs that are associated with the account.
POST /v2.1/​{tenant_id}​/os-keypairs Generates or imports a keypair.
DELETE /v2.1/​{tenant_id}​/os-keypairs/​{keypair_name}​ Deletes a keypair.
GET /v2.1/​{tenant_id}​/os-keypairs/​{keypair_name}​ Shows a keypair that is associated with the account.

Limits, quotas, and usage APIs

Table 8. OpenStack compute limits, quotas, and usage APIs that are used with PowerVC.
Method URI Description
GET /v2.1/{tenant_id}/limits Returns current limits for the account.
GET /v2.1/{tenant_id}/os-quota-sets/{tenant_id} Shows quotas for a tenant.
PUT /v2.1/{tenant_id}/os-quota-sets/{tenant_id} Update quotas for a tenant.
DELETE /v2.1/{tenant_id}/os-quota-sets/{tenant_id} Deletes quotas for a tenant.
GET /v2.1/{tenant_id}/os-quota-sets/{tenant_id}/defaults Retrieves default quotas.
GET /v2.1/{tenant_id}/os-quota-sets/{tenant_id}/detail Retrieves the details about the quotas.
GET /v2.1/{tenant_id}/os-simple-tenant-usage Gets usage for all tenants.
GET /v2.1/{tenant_id}/os-simple-tenant-usage/{tenant_id} Retrieves usage for a tenant.
GET /v2.1/{tenant_id}/os-simple-tenant-usage/{tenant_id}/detail Retrieves details about quotas.

Server groups APIs

Table 9. OpenStack compute server groups APIs that are used with PowerVC. PowerVC uses the term collocation rule instead of server group.
Method URI Description
GET /v2.1/{tenant_id}/os-server-groups Lists server groups.
POST /v2.1/{tenant_id}/os-server-groups Creates a server group.
GET /v2.1/{tenant_id}/os-server-groups/{ServerGroup_id} Shows details for a specified server group.
DELETE /v2.1/{tenant_id}/os-server-groups/{ServerGroup_id} Deletes a specified server group.

Servers APIs

Table 10. OpenStack compute servers APIs that are used with PowerVC.
Method URI Description
POST /v2.1/{tenant_id}/servers Creates a new virtual machine.
POST /v2.1/{tenant_id}/servers Creates a new virtual machine. Specify availability_zone for targeting virtual machine deployment to host group identified by value of availability_zone in the request body.

Example format: "availability_zone":":<host-name>" or "availability_zone":"<host-group-name>"

For more details, see Availability Zones.
GET /v2.1/{tenant_id}/servers Lists IDs, names, and links for all servers.
GET /v2.1/{tenant_id}/servers/detail Lists details for all servers.
GET /v2.1/{tenant_id}/servers/{server_id} Lists details for the specified server.
DELETE /v2.1/{tenant_id}/servers/{server_id} Deletes the specified server.
POST /v2.1/{tenant_id}/servers/{server_id}/action Creates an image that is based on the specified server. Specify the createImage action in the request body. Prepare the server by using the AE script and shutdown it down before you initiate the action.

PowerVC captures the volumes in the boot set, and maintains the boot_index order. To capture more volumes, specify them in the metadata dictionary in the format "powervc_capture_disk_n":"<cinder_volumeID>"

You must use one property for each volume, rather than one property that contains a list of volumes.
POST /v2.1/{tenant_id}/servers/{server_id}/action Migrates a specified server to a new host without restarting the specified server. Specify the os-migrateLive action in the request body.
POST /v2.1/{tenant_id}/servers/{server_id}/action Stops a specified server if it is running and changes status to STOPPED. Specify the os-stop action in the request body.
POST /v2.1/{tenant_id}/servers/{server_id}/action Returns a specified server to ACTIVE status if it was in the STOPPED status. Specify the os-start action in the request body.
POST /v2.1/{tenant_id}/servers/{server_id}/action Restarts the specified server. Specify the reboot action in the request body.
POST /v2.1/{tenant_id}/servers/{server_id}/action Resizes the specified server. Specify the resize action in the request body.
POST /v2.1/{tenant_id}/servers/{server_id}/action Confirms a pending resize action. Specify the confirmResize action in the request body.
POST /v2.1/{tenant_id}/servers/{server_id}/action Starts a virtual network computing (VNC) session and retrieves the console URL. Specify the os-getVNCConsole action in the request body. Specify "novnc" as the payload type.

Only supported for NovaLink managed servers.
POST /v2.1/{tenant_id}/servers/{server_id}/action Locks the specified server. Specify the lock action in the request body.

Only supported for NovaLink managed servers.
POST /v2.1/{tenant_id}/servers/{server_id}/action Unlocks the specified server. Specify the unlock action in the request body.

Only supported for NovaLink managed servers.
POST /v2.1/{tenant_id}/servers/{server_id}/action Rebuilds the specified server. Specify the rebuild action in the request body.

Only supported for NovaLink managed servers.
POST /v2.1/{tenant_id}/servers/{server_id}/action Evacuates a server from a failed host to a different one. Specify the evacuate action in the request body with the onSharedStorage parameter set to True. PowerVC calls this function remote restart.

For a targeted evacuation, use the host parameter to specify the host name. This value should be the name shown on the host's Name attribute.

For information about remote restart of all virtual machines on a host, see Remote restart all virtual machines from a failed host.
POST /v2.1/{tenant_id}/servers/{server_id}/action Creates or attaches bulk volumes to a virtual machine. Specify the bulkVolumeAttach action in the request body. For details, see Bulk attach and detach volume APIs.
POST /v2.1/{tenant_id}/servers/{server_id}/action When a user sets immediate parameter to True, the virtual machine is shut down immediately without waiting for OS or other process to shut down.
POST /v2.1/{tenant_id}/servers/{server_id}/action When a user specifies the type as DUMPRESTART in the request body, the VM can be restarted with core dump. For example, {"reboot":{"type":"DUMPRESTART“}}.

Optical device attachment and detachment of VM APIs

Table 11. Optical device attachment and detachment to VM API options
Method URI Description
POST /v2.1/<project_id>/servers/<instance_id>/action Attaches an optical device to a specific virtual machine instance and triggers related actions.
POST /v2.1/<project_id>/servers/<instance_id>/action Detaches an optical device from a specific virtual machine instance.

For example, { "optical_device_detach": {} }

Optical device attachment API

Depending on the specific platform or system that you work with, the response body may contain information about the success of the operation, error messages, or details about the attached optical device.

Response codes
  • Normal response code: OK (200)
Table 12. Parameters in the request body for optical device attachment
Name Style Type Description

network_cfg

body

boolean

Indicates if the network configuration is required (true or false). Currently, there is no false value for this parameter. This is a mandatory parameter.
reboot_vm body string

Indicates if the virtual machine should be rebooted (True" or "False"). If no value is provided, the VM is not rebooted. This is an optional parameter.

Request parameters

Request body example
{ "optical_device_attach": { "network_cfg": true, "reboot_vm": "True" } }

Optical device detachment API

Response codes
  • Response code: No Content (204)
Request body example
{ "optical_device_detach": {} }

Server interface APIs

Table 13. Add virtual network interface API command
Method URI Description
POST /v2.1/{tenant_id}/servers/{server_id}/os-interface Creates a port interface and uses it to attach the port to a server instance.
DELETE /v2.1/{tenant_id}/servers/{server_id}/os-interface/{attachment_id} Detaches the specified port interface from the virtual machine and then deletes the port.

Server volume attachment APIs

Table 14. OpenStack compute server (volume attachments) APIs that are used with PowerVC.
Method URI Description
POST /v2.1/{tenant_id}/servers/{server_id}/os-volume_attachments Attaches a volume to the specified server.
GET /v2.1/{tenant_id}/servers/{server_id}/os-volume_attachments Lists the volume attachments for the specified server.
GET /v2.1/{tenant_id}/servers/{server_id}/os-volume_attachments/{attachment_id} Lists volume details for the specified volume attachment ID.
DELETE /v2.1/{tenant_id}/servers/{server_id}/os-volume_attachments/{attachment_id} Deletes the specified volume attachment from the specified server.
PUT /v2.1/{tenant_id}/servers/{server_id}/os-volume_attachments/{attachment_id} A PowerVC extension to this API allows you to set whether the specified volume is deleted when the associated virtual machine is deleted. For details, see Update volume attachment.

Availability zone APIs

Table 15. OpenStack compute availability zone APIs that are used with PowerVC.
Method URI Description
GET /v2.1/{tenant_id}/os-availability-zone Lists all availability zones. For more information, see Availability zones (os-availability-zone).
GET /v2.1/{tenant_id}/os-availability-zone/detail Provides detailed availability zone information.

Migration of VMs to a different host group APIs

Live migration of VMs to a different host group API

Table 16. Live migration of VMs to a different host group API option
Method URI Description
POST /v2.1/{tenant_id}/servers/{server_id}/action Migrates the specified server to a new host without restarting the server. Specify the os-migrateLive action in the request body.
Response codes
  • Normal response code: Accepted (202)
  • Error response code: Bad Request (400), Unauthorized (401), Forbidden (403) Not Found (404), Conflict (409)
Table 17. Parameters in the request body for live migration of VMs to a different host group API
Name Style Type Description

os-migrateLive

body

string

The action.
host body string

The host in which the server is migrated. This is a mandatory parameter if ignore_az is True.
block_migration body boolean Set to True to migrate local disks by using block migration. If the source or destination host uses shared storage and you set this value to True, the live migration fails.
disk_over_commit body boolean Set to True to enable over commit when the destination host is checked for available disk space. Set to False to disable over commit. This setting only impacts the libvirt virt driver.
force body boolean Force a live migration by not verifying the provided destination host by the scheduler. This is an optional parameter.
ignore_az body boolean Set to True if the server has to be migrated to a host that is not a member of the same host group as the source host.

Cold migration of VMs to a different host group API

Table 18. Cold migration of VMs to a different host group API option
Method URI Description
POST /v2.1/{tenant_id}/servers/{server_id}/action Migrates the specified server to a new host if the server is powered-off. Specify the migrate action in the request body.
Response codes
  • Normal response code: Accepted (202)
  • Error response code: Bad Request (400), Unauthorized (401), Forbidden (403) Not Found (404), Conflict (409)
Table 19. Parameters in the request body for cold migration of VMs to a different host group API
Name Style Type Description

migrate

body

string

The action.
host body string

The host in which the server is migrated. This is a mandatory parameter if ignore_az is True.
ignore_az body boolean Set to True if the server has to be migrated to a host that is not a member of the same host group as the source host.