COT.vm_description
package reference¶
Support for various virtual machine description formats (OVF, OVA, etc.).
The VMDescription
class describes the abstract
API that is implemented by various subclasses.
In general, other modules should not access subclasses directly but should
instead use the factory()
API to derive the appropriate subclass object.
API¶
VMDescription |
Abstract class for reading, editing, and writing VM definitions. |
VMInitError |
Class representing errors encountered when trying to init/load a VM. |
VM description modules¶
COT.vm_description.ovf |
Package for handling OVF and OVA virtual machine description files. |
-
exception
VMInitError
[source]¶ Bases:
exceptions.EnvironmentError
Class representing errors encountered when trying to init/load a VM.
-
class
VMDescription
(input_file, output_file=None)[source]¶ Bases:
object
Abstract class for reading, editing, and writing VM definitions.
Examples
Because instantiating this class creates a temporary directory (
working_dir
), it's important to always clean up. This can be done explicitly:>>> foo = VMDescription("foo.txt", None) >>> tmpdir = foo.working_dir >>> os.path.exists(tmpdir) True >>> foo.destroy() >>> os.path.exists(tmpdir) False
or implicitly by using this class as a context manager:
>>> with VMDescription("foo.txt", None) as foo: ... tmpdir = foo.working_dir ... os.path.exists(tmpdir) ... True >>> os.path.exists(tmpdir) False
If the specific VM class is unknown, you can use the
factory()
method to try to obtain an appropriate subclass:>>> try: ... with VMDescription.factory("foo.txt", None) as foo: ... print(foo.__class__.__name__) ... except VMInitError as e: ... print(e) [Errno 2] Unknown VM description type for input file...
Properties
input_file
Data file to read in. output_file
Filename that write()
will output to.working_dir
Temporary directory this instance can use for storage. platform
The Platform instance object associated with this VM. 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 methods. 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
A short string describing the product version. version_long
A long string describing the product version. -
__init__
(input_file, output_file=None)[source]¶ Read the given VM description file into memory.
Also creates a temporary directory as a working directory.
Parameters:
-
add_controller_device
(device_type, subtype, address, ctrl_item=None)[source]¶ Create a new IDE or SCSI controller, or update existing one.
Parameters: Returns: object -- New or updated controller device object
-
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 (DiskRepresentation) -- Disk file representation
- file_id (str) -- Identifier string for the file/disk mapping
- drive_type (str) -- 'harddisk' or 'cdrom'
- disk (object) -- Existing disk object to overwrite
Returns: object -- New or updated disk object
-
add_disk_device
(drive_type, address, name, description, disk, file_obj, ctrl_item, disk_item=None)[source]¶ Add a new disk device to the VM or update the provided 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 (object) -- Disk object to map to this device
- file_obj (object) -- File object to map to this device
- ctrl_item (object) -- Controller object to serve as parent
- disk_item (object) -- Existing disk device to update instead of making a new device.
Returns: object -- 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: Returns: object -- 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: Raises: ValueMismatchError
-- if the given items are not linked properly.
-
config_file_to_properties
(file_path, user_configurable=None)[source]¶ Import each line of a text file into a configuration property.
Parameters:
-
convert_disk_if_needed
(disk_image, kind)[source]¶ Convert the disk to a more appropriate format if needed.
Parameters: - disk_image (DiskRepresentation) -- Disk 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/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 configuration profile with the given ID.
Parameters: profile (str) -- Profile identifier
-
classmethod
detect_type_from_name
(filename)[source]¶ Check the given filename to see if it looks like a type we support.
Does not check file contents, as the given filename may not yet exist.
Parameters: filename (str) -- File name or path Returns: str -- A string representing a recognized and supported type of file Raises: ValueUnsupportedError
-- if COT can't recognize the file type or doesn't know how to handle this file type.
-
classmethod
factory
(input_file, *args, **kwargs)[source]¶ Factory method to select and create the appropriate subclass.
Parameters: - input_file (str) -- Input file to test against each class's
detect_type_from_name()
implementation. - *args -- Passed through to selected subclass
__init__()
. - **kwargs -- Passed through to selected subclass
__init__()
.
Returns: VMDescription -- appropriate subclass instance.
Raises: VMInitError
-- if no appropriate subclass is identifiedVMInitError
-- if the selected subclass fails instantiation
- input_file (str) -- Input file to test against each class's
-
find_device_location
(device)[source]¶ Find the controller type and address of a given device object.
Parameters: device (object) -- Hardware device object. Returns: tuple -- (type, address)
, such as("ide", "1:0")
.
-
find_empty_drive
(drive_type)[source]¶ Find a disk device that exists but contains no data.
Parameters: drive_type (str) -- Disk drive type, such as 'cdrom' or 'harddisk' Returns: object -- Hardware device object, 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 -- (controller_device, address_string)
or(None, None)
-
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 this 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 (object) -- Disk object to query Returns: str -- String that can be used to identify the file associated with this disk
-
get_id_from_disk
(disk)[source]¶ Get the identifier string associated with the given Disk object.
Parameters: disk (object) -- Disk object Returns: str -- Identifier string associated with this object
-
get_id_from_file
(file_obj)[source]¶ Get the file ID from the given opaque file object.
Parameters: file_obj (object) -- File object to query Returns: str -- Identifier string associated with this object
-
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 (object) -- File object to query Returns: str -- Relative path to the file associated with this object
-
get_property_value
(key)[source]¶ Get the value of the given property.
Parameters: key (str) -- Property identifier Returns: str -- 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 -- List of connectivity strings
-
get_serial_count
(profile_list)[source]¶ Get the number of serial ports under the given profile(s).
Parameters: profile_list (list) -- Change only the given profiles Returns: dict -- { profile_name : serial_count }
-
info_string
(width=79, verbosity_option=None)[source]¶ Get a descriptive string summarizing the contents of this VM.
Parameters: Returns: str -- Wrapped, appropriately verbose string.
-
predicted_output_size
()[source]¶ Estimate how much disk space (in bytes) is needed to write out.
Returns: int -- - Estimated number of bytes consumed when writing out to
output_file
(plus any associated files).
-
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:
-
search_from_controller
(controller, address)[source]¶ From the controller type and device address, look for existing disk.
Parameters: Returns: tuple --
(file, disk, controller_device, disk_device)
, opaque objects of which any or all may beNone
-
search_from_file_id
(file_id)[source]¶ From the given file ID, try to find any existing objects.
Parameters: file_id (str) -- File ID to search from Returns: tuple -- (file, disk, controller_device, disk_device)
, opaque objects of which any or all may beNone
-
search_from_filename
(filename)[source]¶ From the given filename, try to find any existing objects.
Parameters: filename (str) -- Filename to search from Returns: tuple -- (file, disk, controller_device, disk_device)
, opaque objects of which any or all may beNone
-
set_ide_subtype
(subtype, profile_list)[source]¶ Set the device subtype for the IDE controller(s).
Deprecated since version 1.5: Use
set_ide_subtypes()
instead.Parameters:
-
set_ide_subtypes
(type_list, profile_list)[source]¶ Set the device subtype list 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_nic_type
(nic_type, profile_list)[source]¶ Set the hardware type for NICs.
Deprecated since version 1.5: Use
set_nic_types()
instead.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.
-
set_scsi_subtype
(subtype, profile_list)[source]¶ Set the device subtype for the SCSI controller(s).
Deprecated since version 1.5: Use
set_scsi_subtypes()
instead.Parameters:
-
set_scsi_subtypes
(type_list, profile_list)[source]¶ Set the device subtype list 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 NICs.
Parameters:
-
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 the VM description to
output_file
, if any.
-
config_profiles
¶ The list of supported configuration profiles.
If there are no profiles defined, returns an empty list. If there is a default profile, it will be first in the list.
-
default_config_profile
¶ The name of the default configuration profile.
Returns: str -- Profile name or None
if none are defined.
-
environment_properties
¶ The array of environment properties.
Returns: list -- Array of dicts (one per property) with the keys "key"
,"value"
,"qualifiers"
,"type"
,"label"
, and"description"
.
-
environment_transports
¶ The list of environment transport methods.
-
input_file
¶ Data file to read in.
-
network_descriptions
¶ The list of network descriptions currently defined in this VM.
-
networks
¶ The list of network names currently defined in this VM.
-
platform
¶ The Platform instance object associated with this VM.
An instance of
Platform
or a more specific subclass if recognized as such.
-
product_class
¶ The product class identifier, such as com.cisco.csr1000v.
-
system_types
¶ List of virtual system type(s) supported by this virtual machine.
-
verbosity_options
= {None: 1, 'brief': 0, 'verbose': 2}¶
-
version_long
¶ A long string describing the product version.
-
version_short
¶ A short string describing the product version.
-