COT.ovf
module¶
Module for handling OVF and OVA virtual machine description files.
Functions
byte_count |
Convert an OVF-style value + multiplier into decimal byte count. |
byte_string |
Pretty-print the given bytes value. |
factor_bytes |
Convert a byte count into OVF-style bytes + multiplier. |
Classes and Exceptions
OVF |
Representation of the contents of an OVF or OVA. |
OVFNameHelper |
Helper class for OVF . |
OVFHardware |
Helper class for OVF . |
OVFHardwareDataError |
The input data used to construct an OVFHardware is not sane. |
OVFItem |
Helper class for OVF . |
OVFItemDataError |
Data to be added to an OVFItem conflicts with existing data. |
-
byte_count
(base_val, multiplier)[source]¶ Convert an OVF-style value + multiplier into decimal byte count.
Inverse operation of
factor_bytes()
.>>> byte_count("128", "byte * 2^20") 134217728
Parameters: - base_val (str) – Base value string (value of
ovf:capacity
, etc.) - multiplier (str) – Multiplier string (value of
ovf:capacityAllocationUnits
, etc.)
Returns: Number of bytes
Return type: int
- base_val (str) – Base value string (value of
-
byte_string
(byte_count, base_shift=0)[source]¶ Pretty-print the given bytes value.
Parameters: - byte_count (float) – Value
- base_shift (int) – Base value of byte_count (0 = bytes, 1 = kB, 2 = MB, etc.)
Returns: Pretty-printed byte string such as “1.00 GB”
-
factor_bytes
(byte_count)[source]¶ Convert a byte count into OVF-style bytes + multiplier.
Inverse operation of
byte_count()
>>> factor_bytes(134217728) ('128', 'byte * 2^20') >>> factor_bytes(134217729) ('134217729', 'byte')
Parameters: byte_count (int) – Number of bytes Returns: (base_val, multiplier)
-
class
OVF
(input_file, output_file)[source]¶ Bases:
COT.vm_description.VMDescription
,COT.xml_file.XML
Representation of the contents of an OVF or OVA.
Variables: ovf_version – Float representing the OVF specification version in use. Supported values at present are 0.9, 1.0, and 2.0. Properties
input_file
Data file to read in. output_file
OVF or OVA file that will be created or updated by write()
.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. networks
The list of network names 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).-
add_controller_device
(type, subtype, address, ctrl_item=None)[source]¶ Create a new IDE or SCSI controller, or update existing one.
Parameters: - type (str) –
'ide'
or'scsi'
- subtype (str) – Subtype such as
'virtio'
(optional) - address (int) – Controller address such as 0 or 1 (optional)
- ctrl_item – Existing controller device to update (optional)
Returns: New or updated controller device object
- type (str) –
-
add_disk
(file_path, file_id, disk_type, disk=None)[source]¶ Add a new disk object to the VM or overwrite the provided one.
Parameters: - file_path (str) – Path to disk image file
- file_id (str) – Identifier string for the file/disk mapping
- disk_type (str) – ‘harddisk’ or ‘cdrom’
- disk – Existing disk object to overwrite
Returns: New or updated disk object
-
add_disk_device
(type, address, name, description, disk, file, ctrl_item, disk_item=None)[source]¶ Create a new disk hardware device or overwrite an existing one.
Parameters: - 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 – Disk object to map to this device
- file – File object to map to this device
- ctrl_item – Controller object to serve as parent
- disk_item – Existing disk device to update instead of making a new device.
Returns: New or updated disk device object.
- type (str) –
-
add_file
(file_path, file_id, file=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 – Existing file object to overwrite
- disk – Existing disk object referencing
file
.
Returns: New or updated file object
-
check_sanity_of_disk_device
(disk, file, disk_item, ctrl_item)[source]¶ Check if the given disk is linked properly to the other objects.
Parameters: - disk – Disk object to validate
- file – File object which this disk should be linked to (optional)
- disk_item – Disk device object which should link to this disk (optional)
- ctrl_item – Controller device object which should link to the
disk_item
Raises: - ValueMismatchError – if the given items are not linked properly.
- ValueUnsupportedError – if the
disk_item
has aHostResource
value in an unrecognized or invalid format.
-
config_file_to_properties
(file)[source]¶ Import each line of a text file into a configuration property.
Raises NotImplementedError: if the platform
for this OVF does not defineLITERAL_CLI_STRING
Parameters: file (str) – File name to import.
-
convert_disk_if_needed
(file_path, 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: - file_path (str) – Image to inspect and possibly convert
- kind (str) – Image type (harddisk/cdrom)
Returns: file_path
, if no conversion was required- or a file path in
output_dir
containing the converted image
-
create_configuration_profile
(id, label, description)[source]¶ Create or update a configuration profile with the given ID.
Parameters: - id – Profile identifier
- label (str) – Brief descriptive label for the profile
- description (str) – Verbose description of the profile
-
create_envelope_section_if_absent
(section_tag, info_string, attrib={})[source]¶ If the OVF doesn’t already have the given Section, create it.
Parameters: - section_tag (str) – XML tag of the desired section.
- info_string (str) – Info string to set if a new Section is created.
- attrib (dict) – Attributes to filter by when looking for any existing section.
Returns: Section element that was found or created
-
create_network
(label, description)[source]¶ Define a new network with the given label and description.
Parameters: - label (str) – Brief label for the network
- description (str) – Verbose description of the network
-
classmethod
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.
Returns: ‘.ovf’ 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: 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 – Hardware device object. Returns: (type, address)
, such as("ide", "1:0")
.
-
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: Disk element matching the file, or None
-
find_empty_drive
(type)[source]¶ Find a disk device that exists but contains no data.
Parameters: type (str) – Either ‘cdrom’ or ‘harddisk’ Returns: Hardware device object, or None.
-
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
instance, or None
-
find_item_from_file
(file)[source]¶ Find the disk Item that references the given File.
Parameters: file (xml.etree.ElementTree.Element) – File element Returns: OVFItem
instance, or None.
-
find_open_controller
(type)[source]¶ Find the first open slot on a controller of the given type.
Parameters: type (str) – 'ide'
or'scsi'
Returns: (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
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: 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 Return type: int
-
get_common_subtype
(type)[source]¶ Get the sub-type common to all devices of the given type.
Parameters: type (str) – Device type such as 'ide'
or'memory'
.Returns: None
, if multiple such devices exist and they do not all have the same sub-type.Returns: Subtype string common to all devices of the 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: ‘fileRef’ attribute value of this element
-
get_id_from_file
(file)[source]¶ Get the file ID from the given opaque file object.
Parameters: file (xml.etree.ElementTree.Element) – ‘File’ element Returns: ‘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. Return type: dict Returns: { profile_name : nic_count }
-
get_path_from_file
(file)[source]¶ Get the file path from the given opaque file object.
Parameters: file (xml.etree.ElementTree.Element) – ‘File’ element Returns: ‘href’ attribute value of this element
-
get_property_value
(key)[source]¶ Get the value of the given property.
Parameters: key (str) – Property identifier Returns: Value of this property, 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 of connectivity strings
-
get_serial_count
(profile_list)[source]¶ Get the number of serial ports under the given profile(s).
Return type: dict Returns: { profile_name : serial_count }
-
get_subtype_from_device
(device)[source]¶ Get the sub-type of the given opaque device object.
Parameters: device – Device object to query Returns: None
, or string such as ‘virtio’ or ‘lsilogic’
-
get_type_from_device
(device)[source]¶ Get the type of the given device.
Parameters: device (OVFItem) – Device object to query Returns: string such as ‘ide’ or ‘memory’
-
info_string
(TEXT_WIDTH=79, verbosity_option=None)[source]¶ Get a descriptive string summarizing the contents of this OVF.
Parameters: - TEXT_WIDTH (int) – Line length to wrap to where possible.
- verbosity_option (str) –
'brief'
,None
(default), or'verbose'
Returns: Wrapped, appropriately verbose string.
-
profile_info_list
(TEXT_WIDTH=79, verbose=False)[source]¶ Get a list describing available configuration profiles.
Parameters: - TEXT_WIDTH (int) – Line length to wrap to if possible
- verbose (str) – if True, generate multiple lines per profile
Returns: (header, list)
-
profile_info_string
(TEXT_WIDTH=79, verbosity_option=None)[source]¶ Get a string summarizing available configuration profiles.
Parameters: - TEXT_WIDTH (int) – Line length to wrap to if possible
- verbosity_option (str) –
'brief'
,None
(default), or'verbose'
Returns: Appropriately formatted and verbose string.
-
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: - controller (str) –
'ide'
or'scsi'
- address (str) – Device address such as
'1:0'
Returns: (file, disk, ctrl_item, disk_item)
, any or all of which may beNone
- controller (str) –
-
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) – Filename to search from Returns: (file, disk, ctrl_item, disk_item)
, any or all of which may beNone
-
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: (file, disk, ctrl_item, disk_item)
, any or all of which may beNone
-
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 GB instead of 8589934592 bytes).
Parameters: - disk (xml.etree.ElementTree.Element) – Disk to update
- capacity_bytes (int) – Disk capacity, in bytes
-
set_cpu_count
(cpus, profile_list)[source]¶ Set the number of CPUs.
Parameters: - cpus (int) – Number of CPUs
- profile_list (list) – Change only the given profiles
-
set_ide_subtype
(type, profile_list)[source]¶ Set the device subtype for the IDE controller(s).
Parameters: - type (str) – IDE subtype string
- profile_list (list) – Change only the given profiles
-
set_memory
(megabytes, profile_list)[source]¶ Set the amount of RAM, in megabytes.
Parameters: - megabytes (int) – Memory value, in megabytes
- profile_list (list) – Change only the given profiles
-
set_nic_count
(count, profile_list)[source]¶ Set the given profile(s) to have the given number of NICs.
Parameters: - count (int) – number of NICs
- profile_list (list) – Change only the given profiles
-
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: - mac_list (list) – List of MAC addresses to assign to NICs
- profile_list (list) – Change only the given profiles
-
set_nic_names
(name_list, profile_list)[source]¶ Set the device names for NICs under the given profile(s).
Parameters: - name_list (list) – List of names to assign.
- profile_list (list) – Change only the given profiles
-
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: - network_list (list) – List of networks to map NICs to
- profile_list (list) – Change only the given profiles
-
set_nic_type
(type, profile_list)[source]¶ Set the hardware type for NICs.
Parameters: - type (str) – NIC hardware type
- profile_list (list) – Change only the given profiles.
-
set_product_section_child
(child_tag, child_text)[source]¶ If the OVF doesn’t already have the given Section, create it.
Parameters: - child_tag (str) – XML tag of the product section child element.
- child_text (str) – Text to set for the child element.
Returns: The product section element that was updated or created
-
set_property_value
(key, value)[source]¶ Set the value of the given property (converting value if needed).
Parameters: - key (str) – Property identifier
- value – Value to set for this property
Returns: the (converted) value that was set.
-
set_scsi_subtype
(type, profile_list)[source]¶ Set the device subtype for the SCSI controller(s).
Parameters: - type (str) – SCSI subtype string
- profile_list (list) – Change only the given profiles
-
set_serial_connectivity
(conn_list, profile_list)[source]¶ Set the serial port connectivity under the given profile(s).
Parameters: - conn_list (list) – List of connectivity strings
- profile_list (list) – Change only the given profiles
-
set_serial_count
(count, profile_list)[source]¶ Set the given profile(s) to have the given number of serial ports.
Parameters: - count (int) – Number of serial ports
- profile_list (list) – Change only the given profiles
-
tar
(ovf_descriptor, tar_file)[source]¶ Create a .ova tar file based on the given OVF descriptor.
Parameters: - ovf_descriptor (str) – File path for an OVF descriptor
- tar_file (str) – File path for the desired OVA archive.
-
untar
(file)[source]¶ Untar the OVF descriptor from an .ova to the working directory.
Parameters: file (str) – OVA file path Raises VMInitError: if the given file does not represent a valid OVA archive. Returns: Path to extracted OVF descriptor
-
validate_and_update_file_references
()[source]¶ Check all File entries to make sure they are valid and up to date.
Helper method for
write()
.
-
validate_and_update_networks
()[source]¶ Make sure all defined networks are actually used by NICs.
Delete any networks that are unused and warn the user. Helper method for
write()
.
-
write
()[source]¶ Write OVF or OVA to
output_file
, if set.
-
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.
Returns: Array of dicts (one per property) with the keys "key"
,"value"
,"qualifiers"
,"type"
,"label"
, and"description"
.
-
networks
¶ The list of network names currently defined in this VM.
Return type: list[str]
-
output_file
¶ OVF or OVA file that will be created or updated by
write()
.Raises ValueUnsupportedError: if detect_type_from_name()
fails
-
platform
¶ The platform type, as determined from the OVF descriptor.
Type: Class object - GenericPlatform
or a more-specific subclass if recognized as such.
-
product
¶ Short descriptive product string (XML
Product
element).
-
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).
-
-
class
OVFNameHelper
(version)[source]¶ Bases:
object
Helper class for
OVF
.Provides string constants for easier lookup of various OVF XML elements and attributes.
-
class
OVFHardware
(ovf)[source]¶ Helper class for
OVF
.Represents all hardware items defined by this OVF; i.e., the contents of all Items in the VirtualHardwareSection.
Fundamentally it’s just a dict of
OVFItem
objects with a bunch of helper methods.-
clone_item
(parent_item, profile_list)[source]¶ Clone an
OVFItem
to create a new instance.Parameters: - parent_item (OVFItem) – Instance to clone from
- profile_list (list) – List of profiles to clone into
Returns: (instance, ovfitem)
-
find_all_items
(resource_type=None, properties=None, profile_list=None)[source]¶ Find all items matching the given type, properties, and profiles.
Parameters: - resource_type – Resource type string like ‘scsi’ or ‘serial’
- value] properties (dict[property,) – Property values to match
- profile_list (list) – List of profiles to filter on
Returns: list of
OVFItem
instances
-
find_item
(resource_type=None, properties=None, profile=None)[source]¶ Find the only
OVFItem
of the givenresource_type
.Parameters: - resource_type –
- properties –
- profile – Single profile ID to search within
Return type: OVFItem
orNone
Raises LookupError: if more than one such Item exists.
-
get_item_count
(resource_type, profile)[source]¶ Wrapper for
get_item_count_per_profile()
.Parameters: - resource_type (str) –
- profile (str) – Single profile identifier string to look up.
Returns: Number of items of this type in this profile.
-
get_item_count_per_profile
(resource_type, profile_list)[source]¶ Get the number of Items of the given type per profile.
Items present under “no profile” will be counted against the total for each profile.
Parameters: - resource_type (str) –
- profile_list (list) – List of profiles to filter on (default: apply across all profiles)
Return type: dict[profile, count]
-
new_item
(resource_type, profile_list=None)[source]¶ Create a new
OVFItem
of the given type.Parameters: - resource_type (str) –
- profile_list (list) – Profiles the new item should belong to
Returns: (instance, ovfitem)
-
set_item_count_per_profile
(resource_type, count, profile_list)[source]¶ Set the number of items of a given type under the given profile(s).
If the new count is greater than the current count under this profile, then additional instances that already exist under another profile will be added to this profile, starting with the lowest-sequence instance not already present, and only as a last resort will new instances be created.
If the new count is less than the current count under this profile, then the highest-numbered instances will be removed preferentially.
Parameters: - resource_type (str) – ‘cpu’, ‘harddisk’, etc.
- count (int) – Desired number of items
- profile_list (list) – List of profiles to filter on (default: apply across all profiles)
-
set_item_values_per_profile
(resource_type, property, value_list, profile_list, default=None)[source]¶ Set value(s) for a property of multiple items of a type.
Parameters: - resource_type (str) – Device type such as ‘harddisk’ or ‘cpu’
- property (str) – Property name to update
- value_list (list) – List of values to set (one value per item
of the given
resource_type
) - profile_list (list) – List of profiles to filter on (default: apply across all profiles)
- default – If there are more matching items than entries in
value_list
, set extra items to this value
-
set_value_for_all_items
(resource_type, property, new_value, profile_list, create_new=False)[source]¶ Set a property to the given value for all items of the given type.
If no items of the given type exist, will create a new
Item
ifcreate_new
is set toTrue
; otherwise will log a warning and do nothing.Parameters: - resource_type (str) – Resource type such as ‘cpu’ or ‘harddisk’
- property (str) – Property name to update
- new_value – New value to set the property to
- profile_list (list) – List of profiles to filter on (default: apply across all profiles)
- create_new (boolean) – Whether to create a new entry if no items
of this
resource_type
presently exist.
-
-
class
OVFHardwareDataError
[source]¶ Bases:
exceptions.Exception
The input data used to construct an
OVFHardware
is not sane.
-
class
OVFItem
(ovf, item=None)[source]¶ Helper class for
OVF
.Represents all variations of a given hardware
Item
amongst different hardware configuration profiles.In essence, it is:
- a dict of
Item
properties (indexed by element name) - each of which is a dict of sets of profiles (indexed by element value)
-
add_item
(item)[source]¶ Add the given
Item
element to this OVFItem.Parameters: item – XML Item
elementRaises OVFItemDataError: if the new Item conflicts with existing data already in the OVFItem.
-
add_profile
(new_profile, from_item=None)[source]¶ Add a new profile to this item.
Parameters: - new_profile (str) – Profile name to add
- from_item (OVFItem) – Item to inherit properties from. If unset,
this defaults to
self
.
-
generate_items
()[source]¶ Get a list of Item XML elements derived from this object’s data.
Return type: list[xml.etree.ElementTree.Element]
-
get
(tag)[source]¶ Get the dict associated with the given XML tag, if any.
Parameters: tag (str) – XML tag to look up Return type: dict Returns: Dictionary of values associated with this tag (TODO?)
-
get_all_values
(tag)[source]¶ Get the set of all value strings for the given tag.
Parameters: tag – Return type: set
-
get_value
(tag, profiles=None)[source]¶ Get the value for the given tag under the given profiles.
If the tag does not exist under these profiles, or the tag values differ across the profiles, returns
None
.Parameters: - tag (str) – Tag that the value is associated with
- profiles – set of profile names, or None
Returns: Value string or
None
-
has_profile
(profile)[source]¶ Check if this Item exists under the given profile.
Parameters: profile (str) – Profile name Return type: boolean
-
remove_profile
(profile, split_default=True)[source]¶ Remove all trace of the given profile from this item.
Parameters: - profile – Profile name to remove
- split_default – If false, do not split out ‘default’ profile items to specifically exclude this profile. Used when the profile being removed will no longer exist anywhere and so ‘default’ will continue to exclude this profile.
-
set_property
(key, value, profiles=None, overwrite=True)[source]¶ Store the value and profiles associated with it for the given key.
Parameters: - key (str) – Property key
- value – Value associated with
key
- profiles (list[str]) – If
None
, set for all profiles currently known to this item, else set only for the given list of profiles. - overwrite (boolean) – Whether to permit overwriting of existing value set in this item.
Raises OVFItemDataError: if a value is already defined and would be overwritten, unless
overwrite
isTrue
-
validate
()[source]¶ Verify that the OVFItem describes a valid set of items.
Raises RuntimeError: if validation fails and self-repair is impossible.
-
ATTRIB_KEY_SUFFIX
= ' {Item attribute}'¶
-
ELEMENT_KEY_SUFFIX
= ' {custom element}'¶
- a dict of