6. z/VM cloud connector API¶
z/VM SDK is the layer that implements the management APIs through communicating with the under-layer z/VM management facilities.
This section gives detail descriptions of each supported SDK API.
6.1. z/VM cloud connector API¶
-
class
zvmsdk.api.SDKAPI(**kwargs)[source]¶ Compute action interfaces.
-
guest_start(*args, **kwargs)[source]¶ Power on a virtual machine.
Parameters: userid (str) – the id of the virtual machine to be power on Returns: None
-
guest_softstop(*args, **kwargs)[source]¶ Issue a shutdown command to shutdown the OS in a virtual machine and then log the virtual machine off z/VM..
Parameters: Returns: None
-
guest_reboot(*args, **kwargs)[source]¶ Reboot a virtual machine :param str userid: the id of the virtual machine to be reboot :returns: None
-
guest_reset(*args, **kwargs)[source]¶ reset a virtual machine :param str userid: the id of the virtual machine to be reset :returns: None
-
guest_pause(*args, **kwargs)[source]¶ Pause a virtual machine.
Parameters: userid (str) – the id of the virtual machine to be paused Returns: None
-
guest_unpause(*args, **kwargs)[source]¶ Unpause a virtual machine.
Parameters: userid (str) – the id of the virtual machine to be unpaused Returns: None
-
guest_get_info(*args, **kwargs)[source]¶ Get the status of a virtual machine.
Parameters: userid (str) – the id of the virtual machine Returns: Dictionary contains: power_state: (str) the running state, one of on | off max_mem_kb: (int) the maximum memory in KBytes allowed mem_kb: (int) the memory in KBytes used by the instance num_cpu: (int) the number of virtual CPUs for the instance cpu_time_us: (int) the CPU time used in microseconds
-
guest_list()[source]¶ list names of all the VMs on this host.
Returns: names of the vm on this host, in a list.
-
host_get_info()[source]¶ Retrieve host information including host, memory, disk etc.
Returns: Dictionary describing resources
-
host_diskpool_get_info(*args, **kwargs)[source]¶ Retrieve diskpool information. :param str disk_pool: the disk pool info. It use ‘:’ to separate disk pool type and name, eg “ECKD:eckdpool” or “FBA:fbapool” :returns: Dictionary describing diskpool usage info
-
image_delete(*args, **kwargs)[source]¶ Delete image from image repository
Parameters: image_name – the name of the image to be deleted
-
image_get_root_disk_size(*args, **kwargs)[source]¶ Get the root disk size of the image
Parameters: image_name – the image name in image Repository Returns: the disk size in units CYL or BLK
-
image_import(*args, **kwargs)[source]¶ Import image to zvmsdk image repository
Parameters: - image_name – image name that can be uniquely identify an image
- url (str) – image url to specify the location of image such as http://netloc/path/to/file.tar.gz.0 https://netloc/path/to/file.tar.gz.0 file:///path/to/file.tar.gz.0
- image_meta (dict) – a dictionary to describe the image info. such as md5sum, os_version. For example: {‘os_version’: ‘rhel6.2’, ‘md5sum’: ‘ 46f199c336eab1e35a72fa6b5f6f11f5’}
- remote_host (string) – if the image url schema is file, the remote_host is used to indicate where the image comes from, the format is username@IP eg. nova@192.168.99.1, the default value is None, it indicate the image is from a local file system. If the image url schema is http/https, this value will be useless
-
image_query(*args, **kwargs)[source]¶ Get the list of image info in image repository
Parameters: imagename – Used to retrieve the specified image info, if not specified, all images info will be returned Returns: A list that contains the specified or all images info
-
image_export(*args, **kwargs)[source]¶ Export the image to the specified location :param image_name: image name that can be uniquely identify an image :param dest_url: the location of exported image, eg. file:///opt/images/export.img, now only support export to remote server or local server’s file system :param remote_host: 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, the format is username@IP eg. nova@9.x.x.x :returns a dictionary that contains the exported image info { ‘image_name’: the image_name that exported ‘image_path’: the image_path after exported ‘os_version’: the os version of the exported image ‘md5sum’: the md5sum of the original image }
-
guest_deploy(*args, **kwargs)[source]¶ Deploy the image to vm.
Parameters: - userid – (str) the user id of the vm
- image_name – (str) the name of image that used to deploy the vm
- transportfiles – (str) the files that used to customize the vm
- remotehost – the server where the transportfiles located, the format is username@IP, eg nova@192.168.99.1
- vdev – (str) the device that image will be deploy to
-
guest_capture(userid, image_name, capture_type='rootonly', compress_level=6)[source]¶ Capture the guest to generate a image
Parameters: - userid – (str) the user id of the vm
- image_name – (str) the unique image name after capture
- capture_type – (str) the type of capture, the value can be: rootonly: indicate just root device will be captured alldisks: indicate all the devices of the userid will be captured
- compress_level – the compression level of the image, default is 6
-
guest_create_nic(*args, **kwargs)[source]¶ Create the nic for the vm, add NICDEF record into the user direct.
Parameters: - userid (str) – the user id of the vm
- vdev (str) – nic device number, 1- to 4- hexadecimal digits
- nic_id (str) – nic identifier
- mac_addr (str) – mac address, it is only be used when changing the guest’s user direct. Format should be xx:xx:xx:xx:xx:xx, and x is a hexadecimal digit
- active (bool) – whether add a nic on active guest system
Returns: nic device number, 1- to 4- hexadecimal digits
Return type:
-
guest_get_nic_vswitch_info(*args, **kwargs)[source]¶ Return the nic and switch pair for the specified vm.
Parameters: userid (str) – the user id of the vm Returns: Dictionary describing nic and switch info, format is {‘vdev’: ‘vswitch’}, such as {‘1000’: ‘VSWITCH1’, ‘1003’: ‘VSWITCH2’} Return type: dict
-
guest_get_definition_info(*args, **kwargs)[source]¶ Get definition info for the specified guest vm, also could be used to check specific info.
Parameters: Returns: Dictionary describing user direct and check info result
Return type:
-
guest_create(*args, **kwargs)[source]¶ create a vm in z/VM
Parameters: - userid – (str) the userid of the vm to be created
- vcpus – (int) amount of vcpus
- memory – (int) size of memory in MB
- disk_list –
(dict) 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, the format is: {‘size’: str, ‘format’: str, ‘is_boot_disk’: bool, ‘disk_pool’: str}
In which, ‘size’: case insensitive, the unit can be in Megabytes (M), Gigabytes (G), or number of cylinders/blocks, eg 512M, 1g or just 2000. ‘format’: can be ext2, ext3, ext4, xfs. ‘is_boot_disk’: For root disk, this key must be set to indicate the image that will be deployed on this disk. ‘disk_pool’: optional, if not specified, the disk will be created by using the value from configure file,the format is ECKD:eckdpoolname or FBA:fbapoolname.
For example: [{‘size’: ‘1g’, ‘is_boot_disk’: True, ‘disk_pool’: ‘ECKD:eckdpool1’}, {‘size’: ‘200000’, ‘disk_pool’: ‘FBA:fbapool1’, ‘format’: ‘ext3’}] In this case it will create one disk 0100(in case the vdev for root disk is 0100) with size 1g from ECKD disk pool eckdpool1 for guest , then set IPL 0100 in guest’s user directory, and it will create 0101 with 200000 blocks from FBA disk pool fbapool1, and formated with ext3.
- user_profile – the profile for the guest
-
guest_create_disks(*args, **kwargs)[source]¶ Add disks to an existing guest vm.
Parameters: - userid – (str) the userid of the vm to be created
- disk_list –
(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, the format is: {‘size’: str, ‘format’: str, ‘is_boot_disk’: bool, ‘disk_pool’: str}
In which, ‘size’: case insensitive, the unit can be in Megabytes (M), Gigabytes (G), or number of cylinders/blocks, eg 512M, 1g or just 2000. ‘format’: optional, can be ext2, ext3, ext4, xfs, if not specified, the disk will not be formatted. ‘is_boot_disk’: For root disk, this key must be set to indicate the image that will be deployed on this disk. ‘disk_pool’: optional, if not specified, the disk will be created by using the value from configure file,the format is ECKD:eckdpoolname or FBA:fbapoolname.
For example: [{‘size’: ‘1g’, ‘is_boot_disk’: True, ‘disk_pool’: ‘ECKD:eckdpool1’}, {‘size’: ‘200000’, ‘disk_pool’: ‘FBA:fbapool1’, ‘format’: ‘ext3’}] In this case it will create one disk 0100(in case the vdev for root disk is 0100) with size 1g from ECKD disk pool eckdpool1 for guest , then set IPL 0100 in guest’s user directory, and it will create 0101 with 200000 blocks from FBA disk pool fbapool1, and formated with ext3.
-
guest_delete_disks(*args, **kwargs)[source]¶ Delete disks from an existing guest vm.
Parameters: - userid – (str) the userid of the vm to be deleted
- disk_vdev_list – (list) the vdev list of disks to be deleted, for example: [‘0101’, ‘0102’]
-
guest_nic_couple_to_vswitch(*args, **kwargs)[source]¶ Couple nic device to specified vswitch.
Parameters:
-
guest_nic_uncouple_from_vswitch(*args, **kwargs)[source]¶ Disonnect nic device with network.
Parameters:
-
vswitch_create(*args, **kwargs)[source]¶ Create vswitch.
Parameters: - name (str) – the vswitch name
- rdev (str) – the real device number, a maximum of three devices, all 1-4 characters in length, delimited by blanks. ‘NONE’ may also be specified
- controller (str) – the vswitch’s controller, it could be the userid controlling the real device, or ‘*’ to specifies that any available controller may be used
- connection (str) –
- CONnect:
- Activate the real device connection.
- DISCONnect:
- Do not activate the real device connection.
- NOUPLINK:
- The vswitch will never have connectivity through the UPLINK port
- network_type (str) – Specifies the transport mechanism to be used for the vswitch, as follows: IP, ETHERNET
- router (str) –
- 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 (str/int) – the VLAN ID. This can be any of the following values: UNAWARE, AWARE or 1-4094
- port_type (str) –
- 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 (str) –
- 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 (int) – A number between 1 and 8, specifying the QDIO buffer size in megabytes.
- native_vid (int) – the native vlan id, 1-4094 or None
- persist (bool) – whether create the vswitch in the permanent configuration for the system
-
guest_get_console_output(*args, **kwargs)[source]¶ Get the console output of the guest virtual machine.
Parameters: userid (str) – the user id of the vm Returns: console log string Return type: str
-
guest_inspect_stats(*args, **kwargs)[source]¶ Get the statistics including cpu and mem of the guests
Parameters: userid_list – a single userid string or a list of guest userids Returns: dictionary describing the cpu statistics of the vm in the form {‘UID1’: { ‘guest_cpus’: xx, ‘used_cpu_time_us’: xx, ‘elapsed_cpu_time_us’: xx, ‘min_cpu_count’: xx, ‘max_cpu_limit’: xx, ‘samples_cpu_in_use’: xx, ‘samples_cpu_delay’: xx, ‘used_mem_kb’: xx, ‘max_mem_kb’: xx, ‘min_mem_kb’: xx, ‘shared_mem_kb’: xx }, ‘UID2’: { ‘guest_cpus’: xx, ‘used_cpu_time_us’: xx, ‘elapsed_cpu_time_us’: xx, ‘min_cpu_count’: xx, ‘max_cpu_limit’: xx, ‘samples_cpu_in_use’: xx, ‘samples_cpu_delay’: xx, ‘used_mem_kb’: xx, ‘max_mem_kb’: xx, ‘min_mem_kb’: xx, ‘shared_mem_kb’: xx } } for the guests that are shutdown or not exist, no data returned in the dictionary
-
guest_inspect_vnics(*args, **kwargs)[source]¶ Get the vnics statistics of the guest virtual machines
Parameters: userid_list – a single userid string or a list of guest userids Returns: dictionary describing the vnics statistics of the vm in the form {‘UID1’: [{ ‘vswitch_name’: xx, ‘nic_vdev’: xx, ‘nic_fr_rx’: xx, ‘nic_fr_tx’: xx, ‘nic_fr_rx_dsc’: xx, ‘nic_fr_tx_dsc’: xx, ‘nic_fr_rx_err’: xx, ‘nic_fr_tx_err’: xx, ‘nic_rx’: xx, ‘nic_tx’: xx }, ], ‘UID2’: [{ ‘vswitch_name’: xx, ‘nic_vdev’: xx, ‘nic_fr_rx’: xx, ‘nic_fr_tx’: xx, ‘nic_fr_rx_dsc’: xx, ‘nic_fr_tx_dsc’: xx, ‘nic_fr_rx_err’: xx, ‘nic_fr_tx_err’: xx, ‘nic_rx’: xx, ‘nic_tx’: xx }, ] } for the guests that are shutdown or not exist, no data returned in the dictionary
-
vswitch_set_vlan_id_for_user(*args, **kwargs)[source]¶ Set vlan id for user when connecting to the vswitch
Parameters:
-
guest_config_minidisks(*args, **kwargs)[source]¶ Punch the script that used to process additional disks to vm
Parameters:
-
vswitch_set(*args, **kwargs)[source]¶ Change the configuration of an existing virtual switch
Parameters: - vswitch_name (str) – the name of the virtual switch
- kwargs (dict) –
- grant_userid=<value>:
- A userid to be added to the access list
- user_vlan_id=<value>:
- user VLAN ID. Support following ways: 1. As single values between 1 and 4094. A maximum of four values may be specified, separated by blanks. Example: 1010 2020 3030 4040 2. As a range of two numbers, separated by a dash (-). A maximum of two ranges may be specified. Example: 10-12 20-22
- revoke_userid=<value>:
- A userid to be removed from the access list
- real_device_address=<value>:
- The real device address or the real device address and OSA Express port number of a QDIO OSA Express device to be used to create the switch to the virtual adapter. If using a real device and an OSA Express port number, specify the real device number followed by a period(.), the letter ‘P’ (or ‘p’), followed by the port number as a hexadecimal number. A maximum of three device addresses, all 1-7 characters in length, may be specified, delimited by blanks. ‘None’ may also be specified
- port_name=<value>:
- The name used to identify the OSA Expanded adapter. A maximum of three port names, all 1-8 characters in length, may be specified, delimited by blanks.
- controller_name=<value>:
- One of the following: 1. The userid controlling the real device. A maximum of eight userids, all 1-8 characters in length, may be specified, delimited by blanks. 2. ‘*’: Specifies that any available controller may be used
- connection_value=<value>:
- One of the following values: CONnect: Activate the real device connection. DISCONnect: Do not activate the real device connection.
- queue_memory_limit=<value>:
- A number between 1 and 8 specifying the QDIO buffer size in megabytes.
- routing_value=<value>:
- Specifies whether the OSA-Express QDIO device will act as a router to the virtual switch, as follows: 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
- port_type=<value>:
- Specifies the port type, ACCESS or TRUNK
- persist=<value>:
- one of the following values: NO: The vswitch is updated on the active system, but is not updated in the permanent configuration for the system. YES: The vswitch is updated on the active system and also in the permanent configuration for the system. If not specified, the default is NO.
- gvrp_value=<value>:
- GVRP or NOGVRP
- mac_id=<value>:
- A unique identifier (up to six hexadecimal digits) used as part of the vswitch MAC address
- uplink=<value>:
- One of the following: NO: The port being enabled is not the vswitch’s UPLINK port. YES: The port being enabled is the vswitch’s UPLINK port.
- nic_userid=<value>:
- One of the following: 1. The userid of the port to/from which the UPLINK port will be connected or disconnected. If a userid is specified, then nic_vdev= must also be specified 2. ‘*’: Disconnect the currently connected guest port to/from the special virtual switch UPLINK port. (This is equivalent to specifying NIC NONE on CP SET VSWITCH).
- nic_vdev=<value>:
- The virtual device to/from which the the UPLINK port will be connected/disconnected. If this value is specified, nic_userid= must also be specified, with a userid.
- lacp=<value>:
- One of the following values: ACTIVE: Indicates that the virtual switch will initiate negotiations with the physical switch via the link aggregation control protocol (LACP) and will respond to LACP packets sent by the physical switch. INACTIVE: Indicates that aggregation is to be performed, but without LACP.
- Interval=<value>:
- The interval to be used by the control program (CP) when doing load balancing of conversations across multiple links in the group. This can be any of the following values: 1 - 9990: Indicates the number of seconds between load balancing operations across the link aggregation group. OFF: Indicates that no load balancing is done.
- group_rdev=<value>:
- The real device address or the real device address and OSA Express port number of a QDIO OSA Express devcie to be affected within the link aggregation group associated with this vswitch. If using a real device and an OSA Express port number, specify the real device number followed by a period (.), the letter ‘P’ (or ‘p’), followed by the port number as a hexadecimal number. A maximum of eight device addresses all 1-7 characters in length, may be specified, delimited by blanks. Note: If a real device address is specified, this device will be added to the link aggregation group associated with this vswitch. (The link aggregation group will be created if it does not already exist.)
- iptimeout=<value>:
- A number between 1 and 240 specifying the length of time in minutes that a remote IP address table entry remains in the IP address table for the virtual switch.
- port_isolation=<value>:
- ON or OFF
- promiscuous=<value>:
- One of the following: NO: The userid or port on the grant is not authorized to use the vswitch in promiscuous mode YES: The userid or port on the grant is authorized to use the vswitch in promiscuous mode.
- MAC_protect=<value>:
- ON, OFF or UNSPECified
- VLAN_counters=<value>:
- ON or OFF
-
volume_attach(*args, **kwargs)[source]¶ - Attach a volume to a guest. It’s prerequisite to active multipath
- feature on the guest before utilizing persistent volumes.
Parameters: - guest (dict) –
- name:
- The type is string, it’s the node name of the guest instance in database.
- os_type:
- The type is string, it’s the OS running on the guest. Currently supported are RHEL7, SLES12 and their sub-versions, i.e. ‘rhel7’, ‘rhel7.2’, ‘sles12’, ‘sles12sp1’.
- volume (dict) –
- size: of type string. The capacity size of the volume, in
- unit of Megabytes or Gigabytes.
- type: of type string. The device type of the volume. The only
- one supported now is ‘fc’ which implies FibreChannel.
- lun: of type string. The LUN value of the volume, excluding
- prefixing ‘0x’. It’s required if the type is ‘fc’ which implies FibreChannel.
- connection_info (dict) –
- alias: of type string. A constant valid alias of the volume
- after it being attached onto the guest, i.e. ‘/dev/vda’. Because the system generating device name could change after each rebooting, it’s necessary to have a constant name to represent the volume in its life time.
- protocol: of type string. The protocol by which the volume is
- connected to the guest. The only one supported now is ‘fc’ which implies FibreChannel.
- fcps: of type list. The address of the FCP devices used by
- the guest to connect to the volume. They should belong to different channel path IDs in order to work properly.
- wwpns: of type list. The WWPN values through which the volume
- can be accessed, excluding prefixing ‘0x’.
- dedicate: of type list. The address of the FCP devices which
- will be dedicated to the guest before accessing the volume. They should belong to different channel path IDs in order to work properly.
- is_rollback_in_failure (bool) – Whether to roll back in failure. It’s not guaranteed that the roll back operation must be successful.
-
volume_detach(*args, **kwargs)[source]¶ - Detach a volume from a guest. It’s prerequisite to active multipath
- feature on the guest before utilizing persistent volumes.
Parameters: - guest (dict) – A dict comprised of a list of properties of a guest, including: - name: of type string. The node name of the guest instance in database. - os_type: of type string. The OS running on the guest. Currently supported are RHEL7, SLES12 and their sub-versions, i.e. ‘rhel7’, ‘rhel7.2’, ‘sles12’, ‘sles12sp1’.
- volume (dict) – A dict comprised of a list of properties of a volume, including: - type: of type string. The device type of the volume. The only one supported now is ‘fc’ which implies FibreChannel. - lun: of type string. The LUN value of the volume, excluding prefixing ‘0x’. It’s required if the type is ‘fc’ which implies FibreChannel.
- connection_info (dict) – A dict comprised of a list of information used to establish host-volume connection, including: - alias: of type string. A constant valid alias of the volume after it being attached onto the guest, i.e. ‘/dev/vda’. Because the system generating device name could change after each rebooting, it’s necessary to have a constant name to represent the volume in its life time. - protocol: of type string. The protocol by which the volume is connected to the guest. The only one supported now is ‘fc’ which implies FibreChannel. - fcps: of type list. The address of the FCP devices used by the guest to connect to the volume. - wwpns: of type list. The WWPN values through which the volume can be accessed, excluding prefixing ‘0x’. - dedicate: of type list. The address of the FCP devices which will be undedicated from the guest after removing the volume.
- is_rollback_in_failure (bool) – Whether to roll back in failure. It’s not guaranteed that the roll back operation must be successful.
-
guest_create_network_interface(*args, **kwargs)[source]¶ - Create network interface(s) for the guest inux system. It will
- create the nic for the guest, add NICDEF record into the user direct. It will also construct network interface configuration files and punch the files to the guest. These files will take effect when initializing and configure guest.
Parameters: - userid (str) – the user id of the guest
- os_version (str) – operating system version of the guest
- guest_networks (list) –
a list of network info for the guest. It has one dictionary that contain some of the below keys for each network, the format is: {‘ip_addr’: (str) IP address or None, ‘dns_addr’: (list) dns addresses or None, ‘gateway_addr’: (str) gateway address or None, ‘cidr’: (str) cidr format, ‘nic_vdev’: (str)nic VDEV, 1- to 4- hexadecimal digits or None, ‘nic_id’: (str) nic identifier or None, ‘mac_addr’: (str) mac address or None, it is only be used when changing the guest’s user direct. Format should be xx:xx:xx:xx:xx:xx, and x is a hexadecimal digit}
Example for 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’}, {‘ip_addr’: ‘192.168.96.10’, ‘dns_addr’: [‘9.0.2.1’, ‘9.0.3.1’], ‘gateway_addr’: ‘192.168.96.1’, ‘cidr’: “192.168.96.0/24”, ‘nic_vdev’: ‘1003}]
- active (bool) – whether add a nic on active guest system
Returns: guest_networks list, including nic_vdev for each network
Return type:
-
guests_get_nic_info(*args, **kwargs)[source]¶ - Retrieve nic information in the network database according to
- the requirements, the nic information will include the guest name, nic device number, vswitch name that the nic is coupled to, nic identifier and the comments.
Parameters: Returns: list describing nic information, format is [ (userid, interface, vswitch, nic_id, comments), (userid, interface, vswitch, nic_id, comments) ], such as [ (‘VM01’, ‘1000’, ‘xcatvsw2’, ‘1111-2222’, None), (‘VM02’, ‘2000’, ‘xcatvsw3’, None, None) ]
Return type:
-