7. RESTful APIs

This is a reference for the z/VM Cloud Connector RESTful API.

7.1. Response Data Definition

The following table gives a reference of general response data definition of each z/VM Cloud Connector RESTful API. In case of encountering an error, those information will be helpful to report bug/issue.

Name In Type Description
overallRC body integer The overall return code for API request.
rc body integer The return code for API request.
rs body integer The reason code for API request.
errmsg body string The error message returned for API request. It can be empty if no error occur.
modID body integer The module ID that causes the error to occur.
output body dict The return data from API request.

The following detail API description will only cover output part as it’s different for each API. (This document is a beta version now)

7.2. Version

Lists version of this API.

7.2.1. Get zvm cloud connector version

GET /

  • Request:

    No parameters needed.

  • Response code:

    HTTP status code 200 on success.

  • Response contents:

    Return the version of the zvm cloud connect API.

Name In Type Description
output body dict The return data from API request.
api_version header string API version of zvm cloud connector.
min_version header string Min version of zvm cloud connector.
max_version header string Max version of zvm cloud connector.
version header string Version of zvm cloud connector.
  • Response sample:
{
    "rs": 0,
    "overallRC": 0,
    "modID": null,
    "rc": 0,
    "errmsg": "",
    "output":
    {
        "api_version": "1.0.",
        "min_version": "1.0",
        "max_version": "1.0",
        "version": "1.0.0"
    }
}

7.3. Token

7.3.1. Create token

POST /token

Get a valid token to perform further request by using user and password.

  • Request:
Name In Type Description
X-Admin-Token header string Admin-token, which is stored in /etc/zvmsdk/token.dat. You need put this into header to request for a auth-token. Then you can send a request with this auth-token.

  • Response code:

    HTTP status code 200 on success.

  • Response contents:

Name In Type Description
X-Auth-Token header string The token returned to client if authorized.

7.4. Guest(s)

Lists, creates, shows details for, updates, and deletes guests.

7.4.1. List Guests

GET /guests

List names of all the guests created by z/VM Cloud Connector.

  • Request:

    None

  • Response code:

    HTTP status code 200 on success.

  • Response contents:

Name In Type Description
output body list Guests list
  • Response sample:
{
    "rs": 0,
    "overallRC": 0,
    "modID": null,
    "rc": 0,
    "errmsg": "",
    "output": ["v1", "v2"]
}

7.4.2. Create Guest

POST /guests

Create a vm in z/VM

  • Request:
Name In Type Description
guest body dict Guest dict
userid body string The userid of the guest to be created
vcpus body integer vcpus count.
memory body integer Memory size of the guest, in MBytes.
user_profile (Optional) body string Profile of guest.
disk_list (Optional) body list A list of disks info for the guest It has one dictionary that contain some of the below keys for each disk, the root disk should be the first element in the list.
size body string size of disk, case insensitive, the unit can be in Megabytes (M), Gigabytes (G), or number of cylinders/blocks, for example, please use 512M, 1g or just 2000.
format (Optional) body string Format of disk, can be ext2, ext3, ext4, xfs.
is_boot_disk (Optional) body bool is boot disk or not. For the root disk, this key must be set to indicate the image that will be deployed on this disk.
disk_pool (Optional) body string disk pool, if not specified, the disk will be created by using the value from configure file, the format is ECKD:eckdpoolname or FBA:fbapoolname.
max_cpu (Optional) body integer The maximum number of virtual cpus this user can define. The value should be a decimal value between 1 and 64.
max_mem (Optional) body string The maximum size of memory the user can define. The value should be specified by 1-4 bits of number suffixed by either M (Megabytes) or G (Gigabytes). And the number should be a whole number, eg. 512M, 4G.
  • Request sample:
{
  "guest":
  {
      "userid": "id001",
      "vcpus": 1,
      "memory": 1024,
      "user_profile": "",
      "disk_list":[
      {
          "size": "1g",
          "is_boot_disk": True,
          "disk_pool": "ECKD:eckdpool1"
      },
      {
          "size": "200000",
          "disk_pool": "FBA:fbapool1",
          "format": "ext3"
      }],
      "max_cpu": 10,
      "max_mem": "32G"
  }
}

  • Response code:

    HTTP status code 200 on success.

  • Response contents:

    No Response

7.4.3. Guest add disks

POST /guests/{userid}/disks

Add disks for a guest

  • Request:
Name In Type Description
userid path string Guest userid
disk_info body dict A dict to describe disk info.
disk_list (Optional) body list A list of disks info for the guest It has one dictionary that contain some of the below keys for each disk, the root disk should be the first element in the list.
size body string size of disk, case insensitive, the unit can be in Megabytes (M), Gigabytes (G), or number of cylinders/blocks, for example, please use 512M, 1g or just 2000.
format (Optional) body string Format of disk, can be ext2, ext3, ext4, xfs.
is_boot_disk (Optional) body bool is boot disk or not. For the root disk, this key must be set to indicate the image that will be deployed on this disk.
disk_pool (Optional) body string disk pool, if not specified, the disk will be created by using the value from configure file, the format is ECKD:eckdpoolname or FBA:fbapoolname.
  • Request sample:
{
  "disk_info":
  {
      "disk_list":[
      {
          "size": "1g",
          "is_boot_disk": True,
          "disk_pool": "ECKD:eckdpool1"
      },
      {
          "size": "200000",
          "disk_pool": "FBA:fbapool1",
          "format": "ext3"
      }]
  }
}

  • Response code:

    HTTP status code 200 on success.

  • Response contents:

    No Response

7.4.4. Guest configure disks

PUT /guests/{userid}/disks

Configure additional disks for a guest

  • Request:
Name In Type Description
userid path string Guest userid
disk_info body dict A dict to describe disk info.
disk_list body list A list of additional disks info for the guest It has one dictionary that contain some of the below keys for each disk
vdev (Optional) body string The device number of the disk, if not specified, zvmsdk will use the next vdev of CONF.zvm.user_root_vdev as the additional disk’s vdev, eg. if CONF.zvm.user_root_vdev is 0100, zvmsdk will use 0101 as the vdev for first additional disk in disk_info, 0102 as the second additional disk’s vdev
format body string Format of disk, can be ext2, ext3, ext4, xfs.
mntdir (Optional) body string The directory on guest to which the additional disk will be mounted, if not specified, zvmsdk will use /mnt/ephemeral0 as the mount point of first additional disk, /mnt/ephemeral1 as the mount point of second additional disk
  • Request sample:
{
  "disk_info":
  {
      "disk_list":[
      {
          "vdev": "0101",
          "format": "ext3",
          "mntdir": "/mnt/0101"
      },
      {
          "vdev": "0102",
          "format": "ext4",
          "mntdir": "/mnt/0102"
      }]
  }
}

  • Response code:

    HTTP status code 200 on success.

  • Response contents:

    No Response

7.4.5. Guest delete disks

DELETE /guests/{userid}/disks

Delete disks form a guest

  • Request:
Name In Type Description
userid path string Guest userid
vdev_info body dict A dict to describe vdev list to be deleted.
vdev_list body list Disk vdev list of guest It has one list contains the vdev for delete, for example, ['0101','0102']
  • Request sample:
{
  "vdev_info":
  {
      "vdev_list":['0101', '0102']
  }
}

  • Response code:

    HTTP status code 200 on success.

  • Response contents:

    No Response

7.4.6. Get Guests stats including cpu and memory

GET /guests/stats

Get guests cpu, memory information.

  • Request:
Name In Type Description
userid path string A string that contains single userid or userids delimited by comma, like id1, id2, id3

  • Response code:

    HTTP status code 200 on success.

  • Response contents:

Name In Type Description
output body dict cpu and memory statics of guest
  • Response sample:
{
    "rs": 0,
    "overallRC": 0,
    "modID": null,
    "rc": 0,
    "errmsg": "",
    "output": {}
}

7.4.7. Get Guests interface stats

GET /guests/interfacestats

Get guests network interface statistics.

  • Request:
Name In Type Description
userid path string A string that contains single userid or userids delimited by comma, like id1, id2, id3

  • Response code:

    HTTP status code 200 on success.

  • Response contents:

Name In Type Description
output body dict vNICs statistics of one guest.
  • Response sample:
{
    "rs": 0,
    "overallRC": 0,
    "modID": null,
    "rc": 0,
    "errmsg": "",
    "output": {}
}

7.4.8. Get Guests nic info

GET /guests/nics

Get guests nic information, including userid, nic number, vswitch, nic id and comments.

  • Request:
Name In Type Description
userid (Optional) path string Guest userid.
nic_id (Optional) path string nic identifier.
vswitch (Optional) path string vswitch name.

  • Response code:

    HTTP status code 200 on success.

  • Response contents:

Name In Type Description
output body list List describing nic information, each nic has one dict to indicate its info, including userid, interface, switch, port id and comments.
userid body string the userid of the nic.
interface body string the device number of the nic.
switch body string vswitch name.
port body string nic identyifier.
comments body string the comments for the nic.
  • Response sample:
{
    "rs": 0,
    "overallRC": 0,
    "modID": null,
    "rc": 0,
    "output": [{"userid": "id0001",
                "interface": "1000",
                "switch": "vsw01",
                "port": "1111-2222",
                "comments": null}],
    "errmsg": ""
}

7.4.9. Show Guest definition

GET /guests/{userid}

Display the user direct by the given userid.

  • Request:
Name In Type Description
userid path string Guest userid

  • Response code:

    HTTP status code 200 on success.

  • Response contents:

Name In Type Description
output body dict Dictionary describing user direct and check info result
  • Response sample:
{
    "rs": 0,
    "overallRC": 0,
    "modID": null,
    "rc": 0,
    "errmsg": "",
    "output": {"user_direct": ["USER1", "INCLUDE PROFILE"]}
}

7.4.10. Delete Guest

DELETE /guests/{userid}

Delete a guest.

  • Request:
Name In Type Description
userid path string Guest userid

  • Response code:

    HTTP status code 200 on success.

  • Response contents:

    No Response

7.4.11. Get Guest info

GET /guests/{userid}/info

Get running information of guest.

  • Request:
Name In Type Description
userid path string Guest userid

  • Response code:

    HTTP status code 200 on success.

  • Response contents:

Name In Type Description
output body dict Status of guest.
max_mem_kb body integer The maximum memory in KBytes can be allocated for this guest.
num_cpu body integer The count of virtual CPUs for the guest.
cpu_time_us body integer The CPU time used in microseconds.
power_state body string Power status of guest, can be either on or off.
mem_kb body integer Meemory size used by the guest, in KBytes.
  • Response sample:
{
    "rs": 0,
    "overallRC": 0,
    "modID": null,
    "rc": 0,
    "errmsg": "",
    "output":
    {
        "max_mem_kb": 1,
        "num_cpu": 1,
        "cpu_time_us": 0,
        "power_state": "off",
        "mem_kb": 0
    }
}

7.4.12. Create Guest nic

POST /guests/{userid}/nic

Create a virtual nic on giving guest.

  • Request:
Name In Type Description
userid path string Guest userid
nic body dict The information which is used to set nic device number
vdev (Optional) body string nic device number, 1- to 4- hexadecimal digits.
nic_id (Optional) body string nic identifier
mac_addr (Optional) body string Mac address, it is only used when changing the guest’s user direct. Format should be xx:xx:xx:xx:xx:xx, and x is a hexadecimal digit.
active (Optional) body bool Whether the change will apply to the active guest.
  • Request sample:
{
  "nic":
  {
      "vdev": "1000",
      "nic_id": "1111-2222-3333",
      "mac_addr": "12:34:56:AA:BB:CC",
      "active": True
  }
}

  • Response code:

    HTTP status code 200 on success.

  • Response contents:

7.4.13. Create network interface

POST /guests/{userid}/interface

Create one or more network interfaces on giving guest.

  • Request:
Name In Type Description
userid path string Guest userid
interface body dict The information which is used to describe network interface.
os_version body string Operating system version, the valid os_version values are: rhel6.x, rhel7.x, sles11.x, sles12.x, ubuntu16.x, all case insensitive, please contact with your cloud administrator if you don’t know the guest’s os version
guest_networks body list

Network info list of guest. It has one dictionary that contain some of the below keys for each interface. All the keys are optional :

  • ip_addr: the IP address of the interface, cidr is required if ip address is set
  • dns_addr: dns addresses list
  • gateway_addr: gateway address
  • cidr: cidr format
  • nic_vdev: nic device number, 1- to 4- hexadecimal digits
  • mac_addr: mac address
  • nic_id: nic identifier
  • osa_device: OSA device number, 1- to 4- hexadecimal digits
active (Optional) body bool Whether the change will apply to the active guest.
  • Request sample:
{
  "interface":
  {
      "os_version": "rhel7.2",
      "guest_networks": [
      {   
          "ip_addr": "192.168.95.10",
          "dns_addr": ["9.0.2.1", "9.0.3.1"],
          "gateway_addr": "192.168.95.1",
          "cidr": "192.168.95.0/24",
          "nic_vdev": "1000",
          "mac_addr": "02:00:00:12:34:56",
          "nic_id": "111-222-333",
          "osa_device": "8080"
      },
      {
          "ip_addr": "192.168.95.11",
          "gateway_addr": "192.168.95.1",
          "cidr": "192.168.95.0/24",
          "nic_vdev": "2000",
          "mac_addr": "02:00:00:12:34:78",
          "nic_id": "444-555-666"
      }],
      "active": "True"
  }
}

  • Response code:

    HTTP status code 200 on success.

  • Response contents:

7.4.14. Delete network interface

DELETE /guests/{userid}/interface

Delete one network interface on giving guest.

  • Request:
Name In Type Description
userid path string Guest userid
interface body dict The information which is used to describe network interface.
os_version body string Operating system version, the valid os_version values are: rhel6.x, rhel7.x, sles11.x, sles12.x, ubuntu16.x, all case insensitive, please contact with your cloud administrator if you don’t know the guest’s os version
vdev body string the device number of the nic.
active (Optional) body bool Whether the change will apply to the active guest.
  • Request sample:
{
  "interface":
  {
      "os_version": "rhel7.2",
      "vdev": "1000",
      "active": True
  }
}

  • Response code:

    HTTP status code 200 on success.

  • Response contents:

7.4.15. Start guest

Start a guest.

POST /guests/{userid}/action

  • Request:
Name In Type Description
userid path string Guest userid
action body string Take start action on guest.
  • Request sample:
{
   "action": "start"
}

  • Response code:

    HTTP status code 200 on success.

  • Response contents:

7.4.16. Stop guest

Stop a guest.

POST /guests/{userid}/action

  • Request:
Name In Type Description
userid path string Guest userid
action body string Take stop action on guest.
  • Request sample:
{
   "action": "stop"
}

  • Response code:

    HTTP status code 200 on success.

  • Response contents:

7.4.17. Softstop guest

Stop a guest gracefully, it will firstly shutdown the os on vm, then stop the vm.

POST /guests/{userid}/action

  • Request:
Name In Type Description
userid path string Guest userid
action body string Take softstop action on guest.
  • Request sample:
{
   "action": "softstop"
}

  • Response code:

    HTTP status code 200 on success.

  • Response contents:

7.4.18. Pause guest

Pause a guest.

POST /guests/{userid}/action

  • Request:
Name In Type Description
userid path string Guest userid
action body string Take pause action on guest.
  • Request sample:
{
   "action": "pause"
}

  • Response code:

    HTTP status code 200 on success.

  • Response contents:

7.4.19. Unpause guest

Unpause a guest.

POST /guests/{userid}/action

  • Request:
Name In Type Description
userid path string Guest userid
action body string Take unpause action on guest.
  • Request sample:
{
   "action": "unpause"
}

  • Response code:

    HTTP status code 200 on success.

  • Response contents:

7.4.20. Reboot guest

Reboot a guest, this will use ‘reboot’ command on the given guest.

POST /guests/{userid}/action

  • Request:
Name In Type Description
userid path string Guest userid
action body string Take reboot action on guest.
  • Request sample:
{
   "action": "reboot"
}

  • Response code:

    HTTP status code 200 on success.

  • Response contents:

7.4.21. Reset guest

Reset a guest, this will first gracefully logoff the guest from z/VM it is running on, then log on the guest and IPL.

POST /guests/{userid}/action

  • Request:
Name In Type Description
userid path string Guest userid
action body string Take reset action on guest.
  • Request sample:
{
   "action": "reset"
}

  • Response code:

    HTTP status code 200 on success.

  • Response contents:

7.4.22. Get guest console output

POST /guests/{userid}/action

Get console output of the guest.

  • Request:
Name In Type Description
userid path string Guest userid
action body string Take get_console_output action on guest.
  • Request sample:
{
   "action": "get_console_output"
}

  • Response code:

    HTTP status code 200 on success.

  • Response contents:

    • output: console_output

Note

In order to retrieve the console log from guest vm, you must add user direct statment “COMMAND SP CONS * START” to the profile that used to deploy guest vm, otherwise no console log collected for the guest vm.

7.4.23. Live resize CPUs of guest

POST /guests/{userid}/action

Live resize CPUs of the guest.

  • Request:
Name In Type Description
userid path string Guest userid
action body string Take live_resize_cpus action on guest.
cpu_cnt body integer The number of virtual cpus that the guest should have after resize. The value should be an positive integer between 1 and 64.
  • Request sample:
{
   "action": "live_resize_cpus",
   "cpu_cnt": 4
}

  • Response code:

    HTTP status code 200 on success.

  • Response contents:

Note

  • Currently only increasing CPU count is supported, decreasing is not supported.

  • The guest to be live resized must be active and managed by z/VM Cloud Connector.

  • If live resize finished successfully, both the active CPU number and the number of defined CPUs in user directory would be updated to the requested so that the CPU count would persist even after the guest is restarted.

  • If requested CPU count is smaller than the current active CPU count, then the API would return error immediately since lively decrease CPU count is not supported.

  • If requested CPU count is larger than the defined CPU number in user directory, this API would increase the CPU number in user directory to requested count. Otherwise, this API would decrease the CPU number in user directory to the requested count.

  • To live resize a guest, the guest must have maximum CPU count defined in user directory entry with “MACHINE ESA xx” where ‘xx’ is the maximum CPU count. The resize CPU count can’t exceed the maximum CPU count.

  • For guests created by z/VM Cloud Connector after version 1.2.0, the maximum CPU count is defined when the guest is created. The maximum CPU count is set by the configuration “user_default_max_cpu” in [zvm] section and can be overriden by the parameter “max_cpu” when creating the guest. eg, the following configuration would define the default maximum CPU count as 64.

    [zvm]
user_default_max_cpu=64

7.4.24. Resize CPUs of guest

POST /guests/{userid}/action

Resize CPUs of the guest.

  • Request:
Name In Type Description
userid path string Guest userid
action body string Take resize_cpus action on guest.
cpu_cnt body integer The number of virtual cpus that the guest should have after resize. The value should be an positive integer between 1 and 64.
  • Request sample:
{
   "action": "resize_cpus",
   "cpu_cnt": 4
}

  • Response code:

    HTTP status code 200 on success.

  • Response contents:

Note

  • Both increasing and decreasing CPU count are supported.
  • The target guest can be in either ‘on’ or ‘off’ status, the definition change would take into effects after logoff and re-logon (reset).

7.4.25. Deploy guest

POST /guests/{userid}/action

After guest created, deploy image onto the guest.

  • Request:
Name In Type Description
userid path string Guest userid
action body string Take deploy action on guest.
image body string Image name that can be uniquely identify an image.
transportfiles (Optional) body string The files path that used to customize the vm.
remotehost (Optional) body string The server that the transportfiles located, if remotehost is not specified, will deploy with the transport file in local server, otherwise, the format is username@ip, for example, nova@9.x.x.x or username@hostname eg.``test@test.ibm.com``
vdev (Optional) body string Device number to which the image will be deployed, 1- to 4- hexadecimal digits.
  • Request sample:
{
  "action": "deploy",
  "image": "image1",
  "transportfiles": "/data/openstack/nova/instances/opnstk1/fp1t001d/cfgdrive.tgz",
  "remotehost": "nova@192.168.99.1"
  "vdev": "0100"
}

  • Response code:

    HTTP status code 200 on success.

  • Response contents:

7.4.26. Capture guest

POST /guests/{userid}/action

  • Request:
Name In Type Description
userid path string Guest userid
action body string Take capture action on guest.
image body string Image name that can be uniquely identify an image.
capture_type (Optional) body string

The type of capture:

  • rootonly: indicate just root device will be captured, this is the default one
  • alldisks: indicate all the devices of the userid will be captured
compress_level (Optional) body integer The compression level of the image, default value is 6
  • Request sample:
{
  "action": "capture",
  "image": "capturedimage",
  "capture_type": "rootonly",
  "compress_level": 6
}

  • Response code:

    HTTP status code 200 on success.

  • Response contents:

7.4.27. Get Guest power state

GET /guests/{userid}/power_state

Get power state of the guest.

  • Request:
Name In Type Description
userid path string Guest userid

  • Response code:

    HTTP status code 200 on success.

  • Response contents:

Name In Type Description
output body string Power status of guest, can be either on or off.
  • Response sample:
{
    "rs": 0,
    "overallRC": 0,
    "modID": null,
    "rc": 0,
    "errmsg": "",
    "output": "off"
}

7.4.28. Update Guest nic

PUT /guests/{userid}/nic/{vdev}

Couple or uncouple nic with vswitch on the guest.

  • Request:
Name In Type Description
userid path string Guest userid
vdev path string nic device number, 1- to 4- hexadecimal digits.
info body dict The info used to describe the couple/uncouple action.
couple body bool couple or uncouple action.
active (Optional) body bool Whether the change will apply to the active guest.
vswitch (Optional) body string vswitch name.
  • Request sample:
{
  "info":
  {
      "couple": True,
      "active": False,
      "vswitch": "vs_name"
  }
}

  • Response code:

    HTTP status code 200 on success.

  • Response contents:

    No response.

7.4.29. Delete Guest nic

DELETE /guests/{userid}/nic/{vdev}

  • Request:
Name In Type Description
userid path string Guest userid
vdev path string nic device number, 1- to 4- hexadecimal digits.
active (Optional) body bool Whether the change will apply to the active guest.

  • Response code:

    HTTP status code 200 on success.

  • Response contents:

    No response.

7.5. Host

Get info from host (hypervisor) running on.

7.5.1. Get Host Info

GET /host

Get host information.

  • Request:

    No parameters needed.

  • Response code:

    HTTP status code 200 on success.

  • Response contents:

Name In Type Description
output body dict The dict of host information.
  • Response sample:
{
    "rs": 0,
    "overallRC": 0,
    "modID": null,
    "rc": 0,
    "errmsg": "",
    "output": 
    {
         "disk_available": 3057,
         "ipl_time": "IPL at 06/02/17 11:07:10 EDT",
         "vcpus_used": 6,
         "hypervisor_type": "zvm",
         "vcpus": 6,
         "zvm_host": "OPNSTK2",
         "memory_mb": 51200.0,
         "cpu_info": {
              "cec_model": "2817",
              "architecture": "s390x"
         },
         "disk_total": 3623,
         "hypervisor_hostname": "OPNSTK2",
         "hypervisor_version": 640,
         "disk_used": 566,
         "memory_mb_used": 0.0
    }
}

7.5.2. Get Host disk pool info

GET /host/diskpool

Get disk pool information on the host.

  • Request:
Name In Type Description
poolname body string The pool name to get pool information from

  • Response code:

    HTTP status code 200 on success.

  • Response contents:

Name In Type Description
disk_available body int The total available size of the disks in the pool in Gigabytes(G).
disk_total body int The total size of the pool in Gigabytes (G).
disk_used body int The size of used disks in the pool in Gigabytes(G).
  • Response sample:
{
    "rs": 0,
    "overallRC": 0,
    "modID": null,
    "rc": 0,
    "output":
    {
         "disk_available": 3060,
         "disk_total": 3623,
         "disk_used": 563
    },
    "errmsg": ""
}

7.6. Image(s)

Lists, creates, shows details for, updates, and deletes images.

7.6.1. List images

GET /images

Get the list of image info in image repository.

  • Request:
Name In Type Description
imagename (Optional) path string Retrieve the specified image information, if not specified, when list image, all images information will be returned.

  • Response code:

    HTTP status code 200 on success.

  • Response contents:

Name In Type Description
output body list The image info for specific image or all images, each image has one dict to indicate its info
imagename body string Image name that can be uniquely identify an image.
imageosdistro body string Operating system version, the valid os_version values are: rhel6.x, rhel7.x, sles11.x, sles12.x, ubuntu16.x, all case insensitive, please contact with your cloud administrator if you don’t know the guest’s os version
md5sum body string md5sum for the specific image.
disk_size_units body string The image’s root disk size in units CYL or BLK, eg 3338:CYL or 614200:BLK.
image_size_in_bytes body string Physical image size in bytes eg 5120000
type body string How the image is generated, if it captured from root disk the type is netboot.
comments body string the comments for the image
  • Response sample:
{
    "rs": 0,
    "overallRC": 0,
    "modID": null,
    "rc": 0,
    "output": [{"imagename": "image1",
                "imageosdistro": "rhel7.2",
                "md5sum": "52014cd658cea6ed4005fb25885e30e2",
                "disk_size_units": "0:CYL",
                "image_size_in_bytes": "55",
                "type": "netboot",
                "comments": null}],
    "errmsg": ""
}

7.6.2. Create image

POST /images

Import an image into image repository

  • Request:
Name In Type Description
image body dict The image info dict.
image_name body string Image name that can be uniquely identify an image.
url body string The location of the image to be imported, support import image from 3 types location, local file system: eg. file:///opt/images/import.img. http server: eg. http://192.168.2.1/path/to/import.img file system on remote host: in this case both url and remote_host parameter should be specified
image_meta body dict The metadata which describes image, the valid keys are os_version and md5sum, os_version is required key, the valid os_version values are: rhel6.x, rhel7.x, sles11.x, sles12.x, ubuntu16.x, all case insensitive, please contact with your cloud administrator if you don’t know the image’s os version
remote_host (Optional) body string The server from where the image will be import, if remote_host is None, the image will be import from the url in local server, otherwise, the format is username@ip, for example, nova@9.x.x.x or username@hostname, for example, test@test.ibm.com
  • Request sample:
{
  "image": 
  {
     "image_name": "image1",
     "url": "file:///image1",
     "image_meta": {"os_version": "rhel6.2"},
     "remote_host": "nova@9.x.x.x"
  }
}

  • Response code:

    HTTP status code 200 on success.

  • Response contents:

    No response.

7.6.3. Export image

PUT /images/{name}

Export the image to the specified location.

  • Request:
Name In Type Description
name path string Image name that can be uniquely identify an image.
location body dict The dictionary to indicate the location info of image to be exported
dest_url body string The location of the exported image, support export to 2 types location, local file system: eg. file:///opt/images/export.img file system on remote host: in this case both dest_url and remote_host parameter should be specified
remote_host (Optional) body string The server that the image will be export to, if remote_host is None, the image will be stored in the dest_path in local server, otherwise, the format is username@ip, for example, nova@9.x.x.x or username@hostname eg.``test@test.ibm.com``.
  • Request sample:
{
  "location": 
  {
     "dest_url": "file:///export/to/image1",
     "remote_host": "test@test.ibm.com"
  }
}

  • Response code:

    HTTP status code 200 on success.

  • Response contents:

Name In Type Description
output body dict The dict contains image info after export.
  • Response sample:
{
    "rs": 0,
    "overallRC": 0,
    "modID": null,
    "rc": 0,
    "errmsg": "",
    "output": {"image_name": "name1",
               "image_path": "/tmp/images/name1",
               "os_version": "rhel6",
               "md5sum": "121212314231"}
}

7.6.4. Get root disk size of image

GET /images/{name}/root_disk_size

Get the root disk size of the image.

  • Request:
Name In Type Description
name path string Image name that can be uniquely identify an image.

  • Response code:

    HTTP status code 200 on success.

  • Response contents:

Name In Type Description
output body string The image’s root disk size in units CYL or BLK, eg 3338:CYL or 614200:BLK.
  • Response sample:
{
    "rs": 0,
    "overallRC": 0,
    "modID": null,
    "rc": 0,
    "output": "3338:CYL",
    "errmsg": ""
}

7.6.5. Delete image

DELETE /images/{name}

Delete an image.

  • Request:
Name In Type Description
name path string Image name that can be uniquely identify an image.

  • Response code:

    HTTP status code 200 on success.

  • Response contents:

    No response.

7.7. VSwitch

Lists, creates, updates, and deletes vswitch.

7.7.1. Create vswitch

POST /vswitches

Create a new vswitch.

  • Request:
Name In Type Description
name body string vswitch name.
rdev (Optional) body string The real device number, a maximum of three devices. null is also allowed.
controller (Optional) body string The vswitch’s controller. It could be userid or “*” to specifies any available controller.
connection (Optional) body string

Connection type option :

  • CONnect: Activate the real device connection.
  • DISCONnect: Do not active the real device connection.
  • NOUPLINK: the vswitch will never have connectivity through.
network_type (Optional) body string Specifies the transport mechanism to be used for switch, as follow:IP, ETHERNET, default is ETHERNET.
router (Optional) body string

Connection type option :

  • NONROUTER: The OSA-Express device identified in real_device_address= will not act as a router to the vswitch.
  • PRIROUTER: The OSA-Express device identified in real_device_address= will act as a primary router to the vswitch.
  • Note: If the network_type is ETHERNET, this value must be unspecified, otherwise, if this value is unspecified, default is NONROUTER
vid (Optional) body string, integer The VLAN ID. This can be any of the following values: UNAWARE, AWARE or 1-4094.
port_type (Optional) body string

Port type :

  • ACCESS: The default porttype attribute for guests authorized for the virtual switch. The guest is unaware of VLAN IDs and sends and receives only untagged traffic
  • TRUNK: The default porttype attribute for guests authorized for the virtual switch. The guest is VLAN aware and sends and receives tagged traffic for those VLANs to which the guest is authorized. If the guest is also authorized to the natvid, untagged traffic sent or received by the guest is associated with the native VLAN ID (natvid) of the virtual switch.
gvrp (Optional) body string

gvrp :

  • GVRP: Indicates that the VLAN IDs in use on the virtual switch should be registered with GVRP-aware switches on the LAN. This provides dynamic VLAN registration and VLAN registration removal for networking switches. This eliminates the need to manually configure the individual port VLAN assignments.
  • NOGVRP: Do not register VLAN IDs with GVRP-aware switches on the LAN. When NOGVRP is specified VLAN port assignments must be configured manually
queue_mem (Optional) body integer A number between 1 and 8, specifying the QDIO buffer size in megabytes
native_vid (Optional) body integer The native vlan id, 1-4094 or null.
persist (Optional) body boolean Whether create the vswitch in the permanent configuration for the system.
  • Request sample:
{
  "vswitch":
  {
      "name": "vs_name",
      "rdev": "FF00",
      "controller": "*",
      "connection": "CONnect",
      "network_type": "ETHERNET",
      "router": "NONROUTER",
      "vid": "UNAWARE",
      "port_type": "ACCESS",
      "gvrp": "GVRP",
      "queue_mem": 8,
      "native_vid": 1,
      "persist": True
  }
}

  • Response code:

    HTTP status code 200 on success.

  • Response contents:

    No response.

7.7.2. List vswitches

GET /vswitches

Get the list of vswitch name on the host

  • Request:

    No parameter needed.

  • Response code:

    HTTP status code 200 on success.

  • Response contents:

Name In Type Description
output body list List of vswitches.
  • Response sample:
{
    "rs": 0,
    "overallRC": 0,
    "modID": null,
    "rc": 0,
    "errmsg": "",
    "output": ["v1", "v2"]
}

7.7.3. GET vswitch details

GET /vswitches/{name}

Get the details of a vswitch

  • Request:
Name In Type Description
name path string vswitch name.

  • Response code:

    HTTP status code 200 on success.

  • Response contents:

Name In Type Description
output body dict The vswitch info for specific vswitch
  • Response sample:
{
    "rs": 0,
    "overallRC": 0,
    "modID": null,
    "rc": 0,
    "output": {
              "switch_name": "TESTVSW",
              "lag_group": "(NOGRP)",
              "port_type": "NONE",
              "vlan_id": "0000",
              "queue_memory_limit": "8",
              "gvrp_request_attribute": "NOGVRP",
              "MAC_protect": "UNSPECIFIED",
              "mac_address": "02-00-0C-00-00-09",
              "gvrp_enabled_attribute": "NOGVRP",
              "lag_interval": "0",
              "IP_timeout": "5",
              "vlan_awareness": "UNAWARE",
              "isolation_status": "NOISOLATION",
              "native_vlan_id": "0000",
              "user_port_based": "USERBASED",
              "transport_type": "ETHERNET",
              "link_ag": "LAG",
              "switch_type": "QDIO",
              "switch_status": "OSA device ready.",
              "routing_value": "NA",
              "VLAN_counters": "E)",
              "real_devices": {"8070":
                                     {"dev_status": "Device is active.",
                                      "controller": "DTCVSW1",
                                      "port_name": "NONE",
                                      "dev_err": "No error.",
                                      "vdev": "0600"}},
              "authorized_users":
                     {"UB160120":
                             {"vlan_ids": [], "prom_mode": "NOPROM",
                              "port_num": "0000", "osd_sim": "NOOSDSIM",
                              "vlan_count": 0},
                      "OPNCLOUD":
                             {"vlan_ids": [], "prom_mode": "NOPROM",
                              "port_num": "0000", "osd_sim": "NOOSDSIM",
                              "vlan_count": 0}},
              "adapters":
                     {
                      "UB160120_1009": {"mac": "02-00-0C-00-01-2D", "type": "QDIO"},
                      "OPNCLOUD_0700": {"mac": "02-00-0C-00-00-0C", "type": "QDIO"}}
              },
    "errmsg": ""
}

7.7.4. Grant user to vswitch

PUT /vswitches/{name}

Grant an user to access vswitch

  • Request:
Name In Type Description
name path string vswitch name.
vswitch body dict The vswitch update info.
grant_userid path string Guest userid
  • Request sample:
{
   "vswitch":
   {
      "grant_userid": "FVTUSER1"
   }
}

  • Response code:

    HTTP status code 200 on success.

  • Response contents:

    No response.

7.7.5. Revoke user from vswitch

PUT /vswitches/{name}

Revoke the user access from vswitch

  • Request:
Name In Type Description
name path string vswitch name.
vswitch body dict The vswitch update info.
revoke_userid path string Guest userid
  • Request sample:
{
   "vswitch":
   {
      "revoke_userid": "FVTUSER1"
   }
}

  • Response code:

    HTTP status code 200 on success.

  • Response contents:

    No response.

7.7.6. Set user VLANID to vswitch

PUT /vswitches/{name}

Set vlan id for user when connecting to the vswitch

  • Request:
Name In Type Description
name path string vswitch name.
vswitch body dict The vswitch update info.
user_vlan_id body dict A dict to describe guest userid and vlanid.
userid path string Guest userid
vlanid body integer The VLAN ID. This can be any of the value between 1-4094.
  • Request sample:
{
   "vswitch":
   {
      "user_vlan_id": {
          "userid": "FVTUSER1"
          "vlanid": 100
      }
   }
}

  • Response code:

    HTTP status code 200 on success.

  • Response contents:

    No response.

7.7.7. Delete vswitch

DELETE /vswitches/{name}

Delete a vswitch by using given name.

  • Request:
Name In Type Description
name path string vswitch name.

  • Response code:

    HTTP status code 200 on success.

  • Response contents:

    No response.