COT.vm_description.ovf
package reference¶
Package for handling OVF and OVA virtual machine description files.
The OVF
class provides an implementation of the
COT.vm_description.VMDescription
interface. In general, COT
submodules should be agnostic of the internals of this package and should
only use the VMDescription
interface.
Exceptions¶
OVFHardwareDataError |
The input data used to construct an OVFHardware is not sane. |
OVFItemDataError |
Data to be added to an OVFItem conflicts with existing data. |
Modules¶
COT.vm_description.ovf.hardware |
Representation of OVF hardware definitions. |
COT.vm_description.ovf.item |
Module for working with individual hardware elements in an OVF. |
COT.vm_description.ovf.name_helper |
Module for handling the differences in XML between OVF spec versions. |
COT.vm_description.ovf.utilities |
Module providing utility functions for OVF and OVA handling. |
-
class
OVF
(input_file, output_file)[source]¶ Bases:
COT.vm_description.vm_description.VMDescription
,COT.xml_file.XML
Representation of the contents of an OVF or OVA.
Properties
input_file
Data file to read in. output_file
OVF or OVA file that will be created or updated by write()
.ovf_version
Float representing the OVF specification version in use. product_class
The product class identifier, such as com.cisco.csr1000v. platform
The platform type, as determined from the OVF descriptor. config_profiles
The list of supported configuration profiles. default_config_profile
The name of the default configuration profile. environment_properties
The array of environment properties. environment_transports
The list of environment transport method strings. networks
The list of network names currently defined in this VM. network_descriptions
The list of network descriptions currently defined in this VM. system_types
List of virtual system type(s) supported by this virtual machine. version_short
Short descriptive version string (XML Version
element).version_long
Long descriptive version string (XML FullVersion
element).-
__init__
(input_file, output_file)[source]¶ Open the specified OVF and read its XML into memory.
Parameters: - input_file (str) – Data file to read in.
- output_file (str) – File name to write to. If this VM is read-only,
(there will never be an output file) this value should be
None
; if the output filename is not yet known, use""
and subsequently setoutput_file
when it is determined.
Raises: VMInitError
– * if the OVF descriptor cannot be located * if an XML parsing error occurs * if the XML is not actually an OVF descriptor * if the OVF hardware validation failsException
– will calldestroy()
to clean up before reraising any exception encountered.
-
add_controller_device
(device_type, subtype, address, ctrl_item=None)[source]¶ Create a new IDE or SCSI controller, or update existing one.
Parameters: Returns: OVFItem – New or updated controller device object
Raises: ValueTooHighError
– if no more controllers can be created
-
add_disk
(disk_repr, file_id, drive_type, disk=None)[source]¶ Add a new disk object to the VM or overwrite the provided one.
Parameters: - disk_repr (COT.disks.DiskRepresentation) – Disk file representation
- file_id (str) – Identifier string for the file/disk mapping
- drive_type (str) – ‘harddisk’ or ‘cdrom’
- disk (xml.etree.ElementTree.Element) – Existing object to overwrite
Returns: xml.etree.ElementTree.Element – New or updated disk object
-
add_disk_device
(drive_type, address, name, description, disk, file_obj, ctrl_item, disk_item=None)[source]¶ Create a new disk hardware device or overwrite an existing one.
Parameters: - drive_type (str) –
'harddisk'
or'cdrom'
- address (str) – Address on controller, such as “1:0” (optional)
- name (str) – Device name string (optional)
- description (str) – Description string (optional)
- disk (xml.etree.ElementTree.Element) – Disk object to map to this device
- file_obj (xml.etree.ElementTree.Element) – File object to map to this device
- ctrl_item (OVFItem) – Controller object to serve as parent
- disk_item (OVFItem) – Existing disk device to update instead of making a new device.
Returns: xml.etree.ElementTree.Element – New or updated disk device object.
- drive_type (str) –
-
add_file
(file_path, file_id, file_obj=None, disk=None)[source]¶ Add a new file object to the VM or overwrite the provided one.
Parameters: - file_path (str) – Path to file to add
- file_id (str) – Identifier string for the file in the VM
- file_obj (xml.etree.ElementTree.Element) – Existing file object to overwrite
- disk (xml.etree.ElementTree.Element) – Existing disk object
referencing
file
.
Returns: xml.etree.ElementTree.Element – New or updated file object
-
check_sanity_of_disk_device
(disk, file_obj, disk_item, ctrl_item)[source]¶ Check if the given disk is linked properly to the other objects.
Parameters: - disk (xml.etree.ElementTree.Element) – Disk object to validate
- file_obj (xml.etree.ElementTree.Element) – File object which this disk should be linked to (optional)
- disk_item (OVFItem) – Disk device object which should link to this disk (optional)
- ctrl_item (OVFItem) – Controller device object which should link
to the
disk_item
Raises: ValueMismatchError
– if the given items are not linked properly.ValueUnsupportedError
– if thedisk_item
has aHostResource
value in an unrecognized or invalid format.
-
config_file_to_properties
(file_path, user_configurable=None)[source]¶ Import each line of a text file into a configuration property.
Parameters: Raises: NotImplementedError
– if theplatform
for this OVF does not defineLITERAL_CLI_STRING
-
convert_disk_if_needed
(disk_image, kind)[source]¶ Convert the disk to a more appropriate format if needed.
- All hard disk files are converted to stream-optimized VMDK as it is the only format that VMware supports in OVA packages.
- CD-ROM iso images are accepted without change.
Parameters: - disk_image (COT.disks.DiskRepresentation) – Image to inspect and possibly convert
- kind (str) – Image type (harddisk/cdrom)
Returns: DiskRepresentation –
disk_image
, if no conversion was required, or a newDiskRepresentation
instance representing a converted image that has been created inoutput_dir
.
-
create_configuration_profile
(pid, label, description)[source]¶ Create or update a configuration profile with the given ID.
Parameters:
-
create_network
(label, description)[source]¶ Define a new network with the given label and description.
Also serves to update the description of an existing network label.
Parameters:
-
delete_configuration_profile
(profile)[source]¶ Delete the profile with the given ID.
Parameters: profile (str) – Profile ID to delete. Raises: LookupError
– if the profile does not exist.
-
static
detect_type_from_name
(filename)[source]¶ Check the given filename to see if it looks like a type we support.
For our purposes, the file needs to match ”.ov[af]” to appear to be an OVF/OVA file. We also support names like “foo.ovf.20150101” as those have been seen in the wild.
Does not check file contents, as the given filename may not yet exist.
Parameters: filename (str) – File name/path Returns: str – ‘.ovf’, ‘.box’ or ‘.ova’ Raises: ValueUnsupportedError
– if filename doesn’t match ovf/ova
-
device_info_str
(device_item)[source]¶ Get a one-line summary of a hardware device.
Parameters: device_item (OVFItem) – Device to summarize Returns: str – Descriptive string such as “harddisk @ IDE 1:0”
-
find_device_location
(device)[source]¶ Find the controller type and address of a given device object.
Parameters: device (OVFItem) – Hardware device object. Returns: tuple – (type, address)
, such as("ide", "1:0")
.Raises: LookupError
– if the controller is not found.
-
find_disk_from_file_id
(file_id)[source]¶ Find the Disk that uses the given file_id for backing.
Parameters: file_id (str) – File identifier string Returns: xml.etree.ElementTree.Element – Disk matching the file, or None
-
find_empty_drive
(drive_type)[source]¶ Find a disk device that exists but contains no data.
Parameters: drive_type (str) – Either ‘cdrom’ or ‘harddisk’ Returns: OVFItem – Instance representing this disk device, or None. Raises: ValueUnsupportedError
– ifdrive_type
is unrecognized.
-
find_item_from_disk
(disk)[source]¶ Find the disk Item that references the given Disk.
Parameters: disk (xml.etree.ElementTree.Element) – Disk element Returns: OVFItem – Corresponding instance, or None
-
find_item_from_file
(file_obj)[source]¶ Find the disk Item that references the given File.
Parameters: file_obj (xml.etree.ElementTree.Element) – File element Returns: OVFItem – Corresponding instance, or None.
-
find_open_controller
(controller_type)[source]¶ Find the first open slot on a controller of the given type.
Parameters: controller_type (str) – 'ide'
or'scsi'
Returns: tuple – (ctrl_item, address_string)
or(None, None)
-
find_parent_from_item
(item)[source]¶ Find the parent Item of the given Item.
Parameters: item (OVFItem) – Item whose parent is desired Returns: OVFItem – instance representing the parent device, or None
-
generate_manifest
(ovf_file)[source]¶ Construct the manifest file for this package, if possible.
Parameters: ovf_file (str) – OVF descriptor file path Returns: bool – True if the manifest was successfully generated, False if not successful (such as if checksum helper tools are unavailable).
-
get_capacity_from_disk
(disk)[source]¶ Get the capacity of the given Disk in bytes.
Parameters: disk (xml.etree.ElementTree.Element) – Disk element to inspect Returns: int – Disk capacity, in bytes
-
get_common_subtype
(device_type)[source]¶ Get the sub-type common to all devices of the given type.
Parameters: device_type (str) – Device type such as 'ide'
or'memory'
.Returns: str – Subtype string common to all devices of the type, or None
, if multiple such devices exist and they do not all have the same sub-type.
-
get_file_ref_from_disk
(disk)[source]¶ Get the file reference from the given opaque disk object.
Parameters: disk (xml.etree.ElementTree.Element) – ‘Disk’ element Returns: str – ‘fileRef’ attribute value of this element
-
get_id_from_disk
(disk)[source]¶ Get the identifier string associated with the given Disk object.
Parameters: disk (xml.etree.ElementTree.Element) – Disk object to inspect Returns: str – Disk identifier
-
get_id_from_file
(file_obj)[source]¶ Get the file ID from the given opaque file object.
Parameters: file_obj (xml.etree.ElementTree.Element) – ‘File’ element Returns: str – ‘id’ attribute value of this element
-
get_nic_count
(profile_list)[source]¶ Get the number of NICs under the given profile(s).
Parameters: profile_list (list) – Profile(s) of interest. Returns: dict – { profile_name : nic_count }
-
get_path_from_file
(file_obj)[source]¶ Get the file path from the given opaque file object.
Parameters: file_obj (xml.etree.ElementTree.Element) – ‘File’ element Returns: str – ‘href’ attribute value of this element
-
get_property_value
(key)[source]¶ Get the value of the given property.
Parameters: key (str) – Property identifier Returns: str – Value of this property as a string, or None
-
get_serial_connectivity
(profile)[source]¶ Get the serial port connectivity strings under the given profile.
Parameters: profile (str) – Profile of interest. Returns: list – connectivity strings
-
get_serial_count
(profile_list)[source]¶ Get the number of serial ports under the given profile(s).
Parameters: profile_list (list) – Profile(s) of interest. Returns: dict – { profile_name : serial_count }
-
info_string
(width=79, verbosity_option=None)[source]¶ Get a descriptive string summarizing the contents of this OVF.
Parameters: Returns: str – Wrapped, appropriately verbose string.
-
predicted_output_size
()[source]¶ Estimate how much disk space (in bytes) is needed to write out.
Since OVA (TAR) is an uncompressed format, the disk space required is approximately the same for both OVF and OVA output. Thus we can provide this value even if
output_file
isNone
.In the TAR format, each file in the archive has a 512-byte header and its total size is rounded up to a multiple of 512 bytes. The archive is terminated by 2 512-byte blocks filled with zero, and the overall archive file size is a multiple of 10 kiB.
Returns: int – - Estimated number of bytes consumed when writing out to
output_file
(plus any associated files).
-
profile_info_list
(width=79, verbose=False)[source]¶ Get a list describing available configuration profiles.
Parameters: Returns: tuple – (header, list)
-
profile_info_string
(width=79, verbosity_option=None)[source]¶ Get a string summarizing available configuration profiles.
Parameters: Returns: str – Appropriately formatted and verbose string.
-
remove_file
(file_obj, disk=None, disk_drive=None)[source]¶ Remove the given file object from the VM.
Parameters: - file_obj (xml.etree.ElementTree.Element) – File object to remove
- disk (xml.etree.ElementTree.Element) – Disk object referencing
file
- disk_drive (OVFItem) – Disk drive mapping
file
to a device
Raises: ValueUnsupportedError
– If thedisk_drive
is a device type other than ‘cdrom’ or ‘harddisk’
-
search_from_controller
(controller, address)[source]¶ From the controller type and device address, look for existing disk.
This implementation uses the parameters to find matching controller and disk
Item
elements, then using the diskItem
to find matchingFile
and/orDisk
.Parameters: Returns: tuple –
(file, disk, ctrl_item, disk_item)
, any or all of which may beNone
-
search_from_file_id
(file_id)[source]¶ From the given file ID, try to find any existing objects.
This implementation uses the given
file_id
to find a matchingFile
in the OVF, then using that to find a matchingDisk
andItem
entries.Parameters: file_id (str) – File ID to search from
Returns: tuple –
(file, disk, ctrl_item, disk_item)
, any or all of whichmay be
None
Raises: LookupError
– If thedisk
entry is found but no correspondingfile
is found.LookupError
– If thedisk_item
is found but noctrl_item
is found to be its parent.
-
search_from_filename
(filename)[source]¶ From the given filename, try to find any existing objects.
This implementation uses the given
filename
to find a matchingFile
in the OVF, then using that to find a matchingDisk
andItem
entries.Parameters: filename (str) – Filename to search from Returns: tuple – (file, disk, ctrl_item, disk_item)
, any or all of which may beNone
Raises: LookupError
– If thedisk_item
is found but noctrl_item
is found to be its parent.
-
set_capacity_of_disk
(disk, capacity_bytes)[source]¶ Set the storage capacity of the given Disk.
Tries to use the most human-readable form possible (i.e., 8 GiB instead of 8589934592 bytes).
Parameters: - disk (xml.etree.ElementTree.Element) – Disk to update
- capacity_bytes (int) – Disk capacity, in bytes
-
set_ide_subtypes
(type_list, profile_list)[source]¶ Set the device subtype(s) for the IDE controller(s).
Parameters:
-
set_nic_count
(count, profile_list)[source]¶ Set the given profile(s) to have the given number of NICs.
Parameters:
-
set_nic_mac_addresses
(mac_list, profile_list)[source]¶ Set the MAC addresses for NICs under the given profile(s).
Note
If the length of
mac_list
is less than the number of NICs, will use the last entry in the list for all remaining NICs.Parameters:
-
set_nic_names
(name_list, profile_list)[source]¶ Set the device names for NICs under the given profile(s).
Parameters:
-
set_nic_networks
(network_list, profile_list)[source]¶ Set the NIC to network mapping for NICs under the given profile(s).
Note
If the length of
network_list
is less than the number of NICs, will use the last entry in the list for all remaining NICs.Parameters:
-
set_property_value
(key, value, user_configurable=None, property_type=None, label=None, description=None)[source]¶ Set the value of the given property (converting value if needed).
Parameters: - key (str) – Property identifier
- value (object) – Value to set for this property
- user_configurable (bool) – Should this property be configurable at deployment time by the user?
- property_type (str) – Value type - ‘string’ or ‘boolean’
- label (str) – Brief explanatory label for this property
- description (str) – Detailed description of this property
Returns: str – the (converted) value that was set.
Raises: NotImplementedError
– ifovf_version
is less than 1.0; OVF version 0.9 is not currently supported.
-
set_scsi_subtypes
(type_list, profile_list)[source]¶ Set the device subtype(s) for the SCSI controller(s).
Parameters:
-
set_serial_connectivity
(conn_list, profile_list)[source]¶ Set the serial port connectivity under the given profile(s).
Parameters:
-
set_serial_count
(count, profile_list)[source]¶ Set the given profile(s) to have the given number of serial ports.
Parameters:
-
tar
(ovf_descriptor, tar_file)[source]¶ Create a .ova tar file based on the given OVF descriptor.
Parameters:
-
untar
(file_path)[source]¶ Untar the OVF descriptor from an .ova to the working directory.
Parameters: file_path (str) – OVA file path Returns: str – Path to extracted OVF descriptor Raises: VMInitError
– if the given file doesn’t represent a valid OVA archive.
-
validate_hardware
()[source]¶ Check sanity of hardware properties for this VM/product/platform.
Returns: bool – True
if hardware is sane,False
if not.
-
write
()[source]¶ Write OVF or OVA to
output_file
, if set.
-
INFO_STRING_DISK_COLUMNS_WIDTH
= 41¶
-
INFO_STRING_DISK_TEMPLATE
= '{{0:{0}}} {{1:>9}} {{2:>9}} {{3:.20}}'¶
-
INFO_STRING_FILE_TEMPLATE
= '{{0:{0}}} {{1:>9}}'¶
-
PROFILE_INFO_TEMPLATE
= '{{0:{0}}} {{1:>4}} {{2:>9}} {{3:>4}} {{4:>7}} {{5:>14}}'¶
-
application_url
¶ Application URL string (XML
AppUrl
element).
-
config_profiles
¶ The list of supported configuration profiles.
If this OVF has no defined profiles, returns an empty list. If there is a default profile, it will be first in the list.
-
environment_properties
¶ The array of environment properties.
Array of dicts (one per property) with the keys
"key"
,"value"
,"qualifiers"
,"type"
,"user_configurable"
,"label"
, and"description"
.
-
environment_transports
¶ The list of environment transport method strings.
-
network_descriptions
¶ The list of network descriptions currently defined in this VM.
Returns: list – List of network description strings
-
networks
¶ The list of network names currently defined in this VM.
-
output_file
¶ OVF or OVA file that will be created or updated by
write()
.Raises: ValueUnsupportedError
– ifdetect_type_from_name()
fails
-
ovf_version
¶ Float representing the OVF specification version in use.
Supported values at present are 0.9, 1.0, and 2.0.
-
platform
¶ The platform type, as determined from the OVF descriptor.
This will be the class
Platform
or a more-specific subclass if recognized as such.
-
product
¶ Short descriptive product string (XML
Product
element).
-
product_class
¶ The product class identifier, such as com.cisco.csr1000v.
-
product_url
¶ Product URL string (XML
ProductUrl
element).
-
system_types
¶ List of virtual system type(s) supported by this virtual machine.
For an OVF, this corresponds to the
VirtualSystemType
element.
-
vendor
¶ Short descriptive vendor string (XML
Vendor
element).
-
vendor_url
¶ Vendor URL string (XML
VendorUrl
element).
-
version_long
¶ Long descriptive version string (XML
FullVersion
element).
-
version_short
¶ Short descriptive version string (XML
Version
element).
-