Virtual images

>>> help(deployer.virtualimages)

create

Imports a new virtual image or images to IBM Cloud Pak Software. The attributes to import the new virtual images can be specified in any of the following ways:

• As a string specifying the URL from which the virtual image can be downloaded, as shown in the following example:

  >>> deployer.virtualimages.create('http://server.xyz.com/path/to/foo.ova')

• As the name of a local virtual image open virtual appliance (OVA) file to be uploaded to IBM Cloud Pak Software, as shown in the following example:

  >>> deployer.virtualimages.create('/path/to/foo.ova')

  Tip: Passing the OVA file to Cloud Pak System takes up more space on the Cloud Pak System than specifying the URL of the OVA file. If space is an issue, consider pointing to the OVA file with a string specifying the URL instead.
• In cases where you want to use your own OS image, you can use the following CLI commands to create a new image of the virtual machine by specifying the new image name, version, virtual machine id (vmid), and the url to metadata OVA (using the corresponding metadata OVA):

  1. >>> vm=admin.virtualmachines.list({'name':'name_of_virtual_machine'})[0]

     where name_of_virtual_machine is the name of the virtual machine as deployed from the virtual appliance under consideration (or a partial name that can uniquely identify the virtual machine).

  2. >>> deployer.virtualimages.create({'url':'url_of_metadata_file','vmid':vm.id,'name':'name_of_virtual_image','version':'version_of_virtual_image','description':'description_of_virtual_image'})

     where
     • url_of_metadata_file is the URL of the metadata OVA file which your Cloud Pak System can access. You can download the metadata OVA file from the IBM DeveloperWorks website at: http://www.ibm.com/developerworks/downloads/ibm/ospatternkit/index.html.
     • name_of_virtual_image is the name given to the virtual image to be created.
     • version_of_virtual_image is the version of the provided virtual image.
     • description_of_virtual_image is the description of the provided virtual image.

  For example:

  From the console virtual machine:

  >>> vm=deployer.virtualsystems[1].virtualmachines[0]
  

  >>> deployer.virtualimages.create({'url': 'http://172.16.40.23/cw/pureas/1.1.0.1/virtualimages/MAESTRO_RHEL_X64.ova','vmid':vm.uuid,'name':'
  Atest','version':'1.0.0.1','description':'a test' })

  From the console virtual machine:

  >>> vm=admin.virtualmachines.list({'name':'My RHEL 6.5 VM 2'})[0]

  >>> deployer.virtualimages.create({'url': 'http://172.16.15.250/jobs/MAESTRO_LINUX_OS_IMG_METADATA_OVA/lastSuccessful/archive/
  MAESTRO_LINUX_OS_IMG_METADATA.ova', 'vmid': vm.id, 'name': 'BYOS RHEL 6.5', 'version': '1.0.0.0', 'description': 'My RHEL 6.5 Image for
  pattern deploy'})

• As a Jython file object that references the local OVA file, as shown in the following example:

  >>> deployer.virtualimages.create(open('/path/to/foo.ova', 'rb'))

• As a dictionary (dict) object with the required keys, as shown in the following example:

  >>> deployer.virtualimages.create({'url': 'http://...' })

• As the name of a file containing a Jython expression that evaluates to one of the values in this list.
• As the value deployer.wizard or a wizard instance created by calling deployer.wizard(). If either of these values is supplied, the command-line interface prompts interactively for the values to create the resource. See Wizard objects on the command-line interface for more information about using the wizard to create a virtualimage object.
• As a list of any of these options, in which case multiple virtual images are imported, as shown in the following example:

  >>> deployer.hypervisors.create(['/path/to/foo1.ova',
                                     '/path/too/foo2.ova'])

This method returns a VirtualImage object for the newly created virtual image, or a list of VirtualImage objects if multiple virtual images were created. Because of their size, importing virtual images takes several minutes. If the location of the OVA file was specified using a local file name or file object, the OVA file is uploaded to IBM Cloud Pak Software before this method returns. Otherwise, this method queues the operation on IBM Cloud Pak Software and returns immediately. The returned VirtualImage objects can be used to track the status of the import process on IBM Cloud Pak Software.

import

The import method is an alias for the create() method and uses the same parameters and return values.

list

Lists the virtual images on this system or, optionally, on other systems in the multisystem management domain to which you have access. This method takes one optional parameter, which is a dictionary of attributes on which to filter.

Examples:

>>> deployer.virtualimages.list()

You can filter by operating system version:

>>> deployer.virtualimages.list({'operatingsystemversion': '6.5'})

With appropriate privileges, you can display all virtual images in your multisystem subdomain.

>>> deployer.virtualimages.list({'location': 'domain'})

With the location option, you can also display connection status in your multisystem subdomain. The connection status data with artifact name None is added to the list of virtual images containing a nested object name location.

>>> deployer.virtualimages.list({'location': 'domain',
'includeStatusData': 'true'})

>>> help(deployer.deploysettings)

add

Adds a deploy setting by hypervisor type and virtual image ID. This method accepts the following parameters:

hypervisorType

A string representing the hypervisor type. This parameter is required. Valid values are:

• Platform System_ESX

virtualImage

A single VirtualImage object. This parameter is required.

The following example shows the usage of this method to add a new single virtual image to the deploy settings:

>>> deployer.deploysettings.add('Platform System_ESX',image)

where image=deployer.virtualimage[1]. The previous setting is still effective.

list

Returns a list of resources in this collection, as shown in the following example. An optional dict parameter can be supplied to filter the list of resources returned. The keys and values in the dict are passed to IBM Cloud Pak Software. The supported keys and values within the dict depend on the type of resource collections.

>>> deployer.deploysettings.list()

remove

Deletes a deploy setting by hypervisor type and virtual image ID. This method accepts the following parameters:

hypervisorType

A string representing the hypervisor type. This parameter is required. Valid values are:

• Platform System_ESX

virtualImage

A single VirtualImage object. This parameter is required.

The following example shows the usage of this method to delete a single virtual image from the original deploy settings list:

>>> deployer.deploysettings.remove('Platform System_ESX',image)

where image=deployer.virtualimage[1].

update

Updates the deploy setting by hypervisor type and virtual image ID. This method accepts the following parameters:

hypervisorType

A string representing the hypervisor type. This parameter is required. Valid values are:

• Platform System_ESX

virtualImage

Either a single VirtualImage object or a list of VirtualImage objects. This parameter is required.

The following example shows the usage of this method to replace the original setting for a single virtual image:

>>> deployer.deploysettings.update('Platform System_ESX',image)

where image=deployer.virtualimage[1].

The following example shows the usage of this method to replace the original setting for a list of virtual images:

>>> deployer.deploysettings.update('Platform System_ESX',images)

where image=deployer.virtualimages.

>>> help(deployer.virtualimage)

acl

The access control list for this virtual image.

advancedoptionsaccepted

This attribute specifies if the virtual images advanced options are enabled. The default value for this boolean attribute is false.

build

The build number of the virtual image, automatically determined. This field contains a string value with a maximum of 1024 characters.

created

The creation time of the virtual image, as number of seconds since midnight, January 1, 1970 UTC. When the virtual image displays, this value is shown as the date and time in the local time zone.

currentmessage

The message associated with the status of the virtual image. This field contains an eight character string value that is generated by Cloud Pak System.

currentmessage_text

This attribute is a string representation of currentmessage in the preferred language of the requester. This attribute is automatically generated by Cloud Pak System.

currentstatus

The status of the virtual image. This field contains an eight character string value that is generated by the appliance.

currentstatus_text

This attribute is a string representation of currentstatus in the preferred language of the requester. This attribute is automatically generated by the appliance.

description

The description of the virtual image. This field contains a string value with a maximum of 1024 characters.

hardware

The default hardware configuration for the virtual image.

id

The ID of the virtual image. This attribute is an integer value.

license

The license attribute contains complete information about the licenses defined in the virtual image. A virtual image contains some number of licenses organized into some number of collections. Exactly one license from each collection must be accepted before the virtual image can be used. The value of the licenses attribute is a Python dict object. Each key in the dict object is the string ID of a collection of licenses. Each value is a nested Python dict object with the following keys and values:

label

A localized label for the collection of licenses.

licenses

An array of Python dict objects, each of which describes one license. These dict objects have the following keys and values:

label

A localized label for the license.

licenseid

The ID of the license.

text

The localized text of the license.

The value of the licenses attribute is generated by the appliance and cannot be set. The value of the dict object is not protected against updates, but such changes have no effect.

licenseaccepted

This attribute indicates if the license from this virtual image has been accepted. Cloud Pak System does not allow a virtual image to be used until the license is accepted. The license from the virtual image must be retrieved before it can be accepted. The following values are valid:

'T'

The virtual image license has been accepted.

'F'

The virtual image license has not been accepted.

locations

This attribute is present if you used the "location" filter on the list() method to retrieve objects from one or more systems in a multisystem management domain. When present, this attribute is a list of dictionaries with the following keys. One dictionary appears in the list for each system from which this object was retrieved:

isLocal

This boolean value is set to true if the object exists on the local system; otherwise, the object originates at a remote system.

location

This value is a string containing the name of the location in the multisystem domain on which the object resides.

message

If present, this is a status message about connection to the remote location.

metaSignature

This value is a string containing a unique signature for the object's metadata.

signature

This value is a string containing a unique signature for the object.

status

If present, this value is an HTTP status code about connection to the remote location.

subdomain

If present, this value is a string containing the name of the multisystem subdomain in which the system providing this artifact resides.

name

The display name associated with this virtual image. This attribute is generated automatically when the virtual image is imported. This field contains a string value with a maximum of 1024 characters.

operatingsystemdescription

This attribute specifies a textual description of the operating system used by the virtual image. The value of this attribute is a string and might be None if the OVA of the virtual image does not supply a value.

operatingsystemid

The read-only attribute specifies the ID of the guest operating system used by the virtual image. The value of this attribute is an integer that corresponds to one of the constants defined for CIM_OperatingSystem.OSType.

operatingsystemversion

This read-only attribute specifies the version of the guest operating system used by the virtual image. The value of this attribute is a string and might be None if the OVA of the virtual image does not supply a value.

owner

A user object that references the owner of this virtual image. This attribute is an integer value. For more information about the properties and methods supported by user objects, enter the following command:

 >>> help(deployer.user)

parts

The parts that can be realized by this virtual image. For more information about the operations available for this list of parts, see the Related reference section. You can also get help for deployer.parts, as shown in the following example:

>>> help(deployer.parts)

pmtype

The type of machine supported by this virtual image. This field contains a string value with a maximum of eight characters.

productids

This attribute specifies all of the product IDs associated with this virtual image.

servicelevel

The service level of the attribute. This field contains a string value with a maximum of 1024 characters.

updated

The time the virtual image was last updated, as number of seconds since midnight, January 1, 1970 UTC. When the virtual image is displayed, this value is shown as the date and time in the local time zone.

version

The version of the virtual image. This field contains a string value with a maximum of 1024 characters.

acceptLicense(licenses)

This method accepts the license presented by the virtual image. IBM Cloud Pak Software cannot use a virtual image until you have accepted its license. This method accepts a single optional parameter that allows you to specify which license for this virtual image is being accepted. The value for this parameter must be a Python dict object in which each key is a license collection ID for the virtual image. Each value is the license ID for the license to be accepted from that collection. If this parameter is not supplied, the appliance behaves as if an arbitrary license from each license collection has been accepted. The following example shows the usage of this method:

>>> myvi.acceptLicense({ 'collection1': 'license3', 'collection2': 'license17' })

For more information about virtual image licenses, enter the following command:

>>> help(deployer.virtualimage.license)

addProductid

Adds a new product ID to all the virtual image parts. This method accepts the following parameters:

productid

The product ID that you want to add. This parameter is required.

licensetype

The license type for this product ID. Valid values are:

• PVU
• Server

The default value is PVU. This parameter is required.

licensecpu

The processor count limit for a server license. This parameter is required for the server license type.

licensememory

The memory limit in GB for a server license. This parameter is required for the server license type.

The following example shows the addProductid method:

>>> myimage[0].addProductid('5724-X89', 'PVU')
>>> myimage[0].addProductid('5724-X89', 'Server', 4, 32)

capture()

Captures a virtual image that was created by extending another virtual image. The virtual image is copied from the hypervisor where it is currently running back to IBM Cloud Pak Software and prepared for future deployments.

clone(d)

Clones a virtual image to create a new virtual image. This method accepts a single Jython dict object argument with the following keys:

description

A string containing a description for the new virtual image. This key is optional. If it is not specified, the new virtual image description is empty.

name

A string containing a name for the new virtual image. This key is required.

version

A string specifying a version for the new virtual image. The value must be a sequence of dot-separated integers that are not negative values, as shown in the following examples:

• '1', '0.4' 

• '1.2.3.4'

This key is required.

hardware

A dictionary that specifies changes to the hardware resource definition of the images. The main resources that can change are disk sizes. This enables users to increase the size of the specific disk in a virtual image during the extension process.

For example:

baseImage = deployer.virtualimages[1]

newImage = baseImage.clone({'name':'Medium DB image','version':'1.1','hardware':{"diskDetails": [{"size": 128849018880, "label": "disk1"}],'niccount': 1}})

Note: The name/value pairs for label and niccount are mandatory and the values must match those of the original virtual image.

This method returns a VirtualImage object for the newly created virtual image. Use the waitFor() method on the new VirtualImage to determine when it has been deployed.

copyTo

Given appropriate permission, copy a virtual image from this system to another system in your multisystem management domain. This method accepts one parameter, a dictionary, with the following keys:

location

Set this value to the name of the system to which the resource will be copied.

deleteProductid

Delete a product ID from all of the virtual image parts. This method accepts the following parameters:

productid

The product ID that you want to delete. This parameter is required.

licensetype

The license type for this product ID. Valid values are:

• PVU
• Server

The default value is PVU. This parameter is required.

The following example shows the deleteProductid method:

>>> myimage[0].deleteProductid('5724-X89', 'PVU')

export (d)

This method starts the asynchronous process of exporting a virtual image to a remote appliance or a local directory. The various pieces of the image are extracted from the internal repository and used to generate an OVA file. This file is then copied to the given location, as shown in the following example:

>>> image = deployer.virtualimages[0]
>>> image.export({
          'host': 'example.com',
          'path': '/archive/images/',
          'userid': 'root',
          'password': 'secret'
       })

extend(d)

Extends this virtual image to create a new virtual image. The extension process begins by deploying the existing virtual image to the cloud. After login to the virtual machine and making any necessary changes, the capture() method is called on the new virtual image. The capture() method copies the virtual machine back to IBM Cloud Pak Software and prepares it for future deployments. This method accepts a single Jython dict object argument with the following keys:

cloud

A reference to the cloud to which the virtual image is being deployed for modifications. This key is required.

description

A string containing a description for the new virtual image. This key is optional. If it is not specified, the new virtual image description is empty.

name

A string containing a name for the new virtual image. This key is required.

password

A string containing the password to use for the deployed virtual image. This key is required.

version

A string specifying a version for the new virtual image. The value must be a sequence of dot-separated integers that are not negative values, as shown in the following examples:

• '1', '0.4' 

• '1.2.3.4'

This key is required.

hardware

A dictionary that contains the hardware resource definition of the images. You cannot change hardware information during extension.

syncTo

Given appropriate permission, update an existing virtual image on another system in your multisystem management domain based on this object. This method accepts one parameter, a dictionary, with the following keys:

location

Set this value to the name of the system to which the resource will be synchronized.

metadataOnly

Optional. If present, set this to true to synchronize only metadata such as access control lists. If this key is absent then it is assumed to be true. Synchronizing the entire virtual image is not supported; the value may not be set to false.

For a virtual image, synchronizing the entire object is not supported. This is not a required value because the syncTo method always synchronizes metadata for only virtual images.