Libvirt Provisioning Module

(this page is probably beyond repair and should be recreated - it would probably be best to separate the manually created part from the auto generated part and just directly check in the manually created part as a plain html file instead of a .mdtext file)

Libvirt is an open source toolkit which can interact with KVM, Xen, and several other virtualization architectures.

libvirt.pm¶

libvirt.pm is the main provisioning module
Computers should have their provisioningID attributes set to point to this module in order to utilize it
Implements the required provisioning module subroutines: load, capture, node_status, power_status, power_on, power_off, power_reset...
Implements the functions provided by libvirt: define, start, destroy...
Does not contain code specific to any of the hypervisors supported by libvirt (KVM, Xen, etc)
File location: lib/VCL/Module/Provisioning/Libvirt.pm
Automatically determines which hypervisor driver object to use upon initialization by examining the host

Hypervisor Driver Modules¶

Libvirt hypervisor drivers allow it to interact with and control various types of hypervisors. The drivers are listed at http://libvirt.org/drivers.html. A hypervisor driver module must be written in order for VCL to support any of the hypervisors supported by libvirt. These driver modules only contain code specific to the driver in order to perform functions not handled by libvirt.pm.

Hypervisor driver directory: lib/VCL/Module/Provisioning/libvirt/
Example: lib/VCL/Module/Provisioning/libvirt/KVM.pm
- Contains code which only applies to KVM
- Calls qemu-img to perform image file operations

!Libvirt UML Diagram.gif!

Virtual Machine Disks¶

A master disk image is stored in the location specified by the datastore path in the VM host profile. A copy on write virtual disk image is created for each virtual machine when it is loaded. The master disk image is used as a read-only backing file for the copy on write disk images. Each VM writes to its own copy on write disk image. Using copy on write virtual disks allows VMs to be loaded without having to create a complete copy of the master disk image. !Copy on Write.gif|width=367,height=448!

libvirt.pm¶

NAME
SYNOPSIS
DESCRIPTION
OBJECT METHODS

initialize
load
capture
node_status
does_image_exist
get_image_size
get_image_repository_search_paths
power_status
power_on
power_off
power_reset
post_maintenance_action

<li><a href="#private_methods">PRIVATE METHODS</a></li>
<ul>

    <li><a href="#driver">driver</a></li>
    <li><a href="#get_driver_name">get_driver_name</a></li>
    <li><a href="#get_domain_name">get_domain_name</a></li>
    <li><a

href="#get_domain_file_base_name">get_domain_file_base_name

get_domain_xml_directory_path
get_domain_xml_file_path
get_master_image_directory_path
get_master_image_file_path
get_copy_on_write_file_path
delete_existing_domains
delete_domain
generate_domain_xml
get_domain_info
get_domain_xml
domain_exists
get_snapshot_info
create_snapshot
delete_snapshot
get_image_size_bytes
find_repository_image_file_paths

<li><a href="#see_also">SEE ALSO</a></li>

NAME

VCL::Provisioning::libvirt - VCL provisioning module to support the libvirt toolkit

SYNOPSIS

 use VCL::Module::Provisioning::libvirt;
 my $provisioner =
(VCL::Module::Provisioning::libvirt)->new({data_structure => $self->data});

DESCRIPTION

 Provides support allowing VCL to provisioning resources supported by the
 libvirt toolkit.
 http://libvirt.org

OBJECT METHODS

initialize

Parameters : none Returns : boolean Description : Enumerates the libvirt driver modules directory: lib/VCL/Module/Provisioning/libvirt/

       Attempts to create and initialize an object for each hypervisor
       driver module found in this directory. The first driver module
       object successfully initialized is used. This object is made
       accessible within this module via $self-&gt;driver. This allows
       libvirt support driver modules to be added without having to
       alter the code in libvirt.pm.</pre>

load

 Parameters  : none
 Returns     : boolean
 Description : Loads the requested image on the domain:

Destroy and delete any domains have already been defined for the computer assigned to this reservation.
Construct the default libvirt XML definition for the domain.
Call the libvirt driver module's 'extend_domain_xml' subroutine if it is implemented. Pass the default domain XML definition hash reference as an argument. The 'extend_domain_xml' subroutine may add or modify XML values. This allows the driver module to customize the XML specific to that driver.
Call the driver module's 'pre_define' subroutine if it is implemented. This subroutine completes any necessary tasks which are specific to the driver being used prior to defining the domain.
Create a text file on the node containing the domain XML definition.
Define the domain on the node by calling 'virsh define <XML file>'.
Power on the domain.
Call the domain guest OS module's 'post_load' subroutine if implemented.

capture

 Parameters  : none
 Returns     : boolean
 Description : Captures the image currently loaded on the computer.

node_status

 Parameters  : $computer_id (optional)
 Returns     : string
 Description : Checks the status of the computer in order to determine if the
           computer is ready to be reserved or needs to be reloaded. A
           string is returned depending on the status of the computer:
           'READY':
          * Computer is ready to be reserved
          * It is accessible
          * It is loaded with the correct image
          * OS module's post-load tasks have run
           'POST_LOAD':
          * Computer is loaded with the correct image
          * OS module's post-load tasks have not run
           'RELOAD':
          * Computer is not accessible or not loaded with the correct
            image

does_image_exist

 Parameters  : $image_name (optional)
 Returns     : array (boolean)
 Description : Checks if the requested image exists on the node or in the
           repository. If the image exists, an array containing the image
           file paths is returned. A boolean evaluation can be done on the
           return value to simply determine if an image exists.

get_image_size

 Parameters  : $image_name (optional)
 Returns     : integer
 Description : Returns the size of the image in megabytes.

get_image_repository_search_paths

 Parameters  : $management_node_identifier (optional)
 Returns     : array
 Description : Returns an array containing paths on the management node where an
           image may reside. The paths may contain wildcards. This is used
           to attempt to locate an image on another managment node in order
           to retrieve it.

power_status

 Parameters  : $domain_name (optional)
 Returns     : string
 Description : Determines the power state of the domain. A string is returned
           containing one of the following values:
          * 'on'
          * 'off'
          * 'suspended'

power_on

 Parameters  : $domain_name (optional)
 Returns     : boolean
 Description : Powers on the domain. Returns true if the domain was successfully
           powered on or was already powered on.

power_off

 Parameters  : $domain_name
 Returns     : boolean
 Description : Powers off the domain. Returns true if the domain was
           successfully powered off or was already powered off.

power_reset

 Parameters  : $domain_name (optional)
 Returns     : boolean
 Description : Resets the power of the domain by powering it off and then back
           on.

post_maintenance_action

 Parameters  : none
 Returns     : boolean
 Description : Performs tasks to the computer after it has been put into
           maintenance mode.

PRIVATE METHODS

driver

 Parameters  : none
 Returns     : Libvirt driver object
 Description : Returns a reference to the libvirt driver object which is created
           when this libvirt.pm module is initialized.

get_driver_name

 Parameters  : none
 Returns     : string
 Description : Returns the name of the libvirt driver being used to control the
           node. Example: 'KVM'

get_domain_name

 Parameters  : none
 Returns     : string
 Description : Returns the name of the domain. This name is passed to various
           virsh commands. It is also the name displayed in virt-manager.
           Example: 'vclv99-197:vmwarewin7-Windows764bit1846-v3'

get_domain_file_base_name

 Parameters  : none
 Returns     : string
 Description : Returns the base name for files created for the current
           reservation. A file extension is not included. This file name is
           used for the domain's XML definition file and it's copy on write
           image file. Example: 'vclv99-37_234-v23'

get_domain_xml_directory_path

 Parameters  : none
 Returns     : string
 Description : Returns the directory path on the node where domain definition
           XML files reside. The directory used is: '/tmp/vcl'

get_domain_xml_file_path

 Parameters  : none
 Returns     : string
 Description : Returns the domain XML definition file path on the node.
           Example: '/tmp/vcl/vclv99-37_234-v23.xml'

get_master_image_directory_path

 Parameters  : none
 Returns     : string
 Description : Returns the directory path on the node where the master image
           files reside. Example: '/var/lib/libvirt/images'

get_master_image_file_path

 Parameters  : $image_name (optional)
 Returns     : string
 Description : Returns the path on the node where the master image file resides.
           Example:
           '/var/lib/libvirt/images/vmwarelinux-RHEL54Small2251-v1.qcow2'

get_copy_on_write_file_path

 Parameters  : none
 Returns     : string
 Description : Returns the path on the node where the copy on write file for the
           domain resides. Example:
           '/var/lib/libvirt/images/vclv99-197_2251-v1.qcow2'

delete_existing_domains

 Parameters  : none
 Returns     : boolean
 Description : Deletes existing domains which were previously created for the
           computer assigned to the current reservation.

delete_domain

 Parameters  : $domain_name
 Returns     : boolean
 Description : Deletes a domain from the node.

generate_domain_xml

Parameters : none Returns : string Description : Generates a string containing the XML definition for the domain.

get_domain_info

 Parameters  : none
 Returns     : hash reference
 Description : Retrieves information about all of the domains defined on the
           node and constructs a hash containing the information. Example:
          "vclv99-197:vmwarewin7-Windows764bit1846-v3" => {
             "id" => 135,
             "state" => "paused"
          },
          "vclv99-37:vmwarewinxp-base234-v23" => {
             "state" => "shut off"
          }

get_domain_xml

Parameters : $domain_name Returns : hash reference Description : Retrieves the XML definition of a domain already defined on the node. Generates a hash using XML::Simple::XMLin.

domain_exists

Parameters : $domain_name Returns : boolean Description : Determines if the domain is defined on the node.

get_snapshot_info

Parameters : $domain_name Returns : hash reference Description : Retrieves snapshot information for the domain specified by the argument and constructs a hash. The hash keys are the snapshot names. Example: "VCL snapshot" => { "creation_time" => "2011-12-07 16:05:50 -0500", "state" => "shutoff" }

create_snapshot

Parameters : $domain_name, $description Returns : boolean Description : Creates a snapshot of the domain specified by the argument.

delete_snapshot

Parameters : $domain_name, $snapshot Returns : boolean Description : Deletes a snapshot created of the domain specified by the argument.

get_image_size_bytes

Parameters : $image_name (optional) Returns : integer Description : Returns the size of the image in bytes.

find_repository_image_file_paths

Parameters : $image_name (optional) Returns : array Description : Locates valid image files stored in the image repository. Searches for all files beginning with the image name and then checks the results to remove any files which should not be included. File extensions which are excluded: vmx, txt, xml If multiple vmdk files are found it is assumed that the image is one of the split vmdk formats and the <image name>.vmdk contains the descriptor information. This file is excluded because it causes qemu-img to fail.

KVM.pm¶

NAME
DESCRIPTION
OBJECT METHODS

initialize
get_domain_type
get_disk_driver_name
get_disk_format
get_disk_file_extension
pre_define

<li><a href="#private_methods">PRIVATE METHODS</a></li>
<ul>

    <li><a

href="#get_virtual_disk_file_info">get_virtual_disk_file_info

get_virtual_disk_size_bytes
copy_virtual_disk
create_copy_on_write_image
update_windows_image

<li><a href="#see_also">SEE ALSO</a></li>

NAME

VCL::Provisioning::libvirt::KVM - Libvirt hypervisor driver module to allow support for the KVM hypervisor

DESCRIPTION

 This is a driver module to allow the main libvirt.pm provisioning module to
 support KVM hosts. It performs the KVM-specific tasks not handled by libvirt
 itself.

OBJECT METHODS

initialize

 Parameters  : none
 Returns     : boolean
 Description : Checks if the node has KVM installed by checking if /usr/bin/qemu
           exists. Returns true if the file exists, false otherwise.

get_domain_type

 Parameters  : none
 Returns     : string
 Description : Returns 'kvm'. This is specified in the domain XML definition:
          <domain type='kvm'>

get_disk_driver_name

 Parameters  : none
 Returns     : string
 Description : Returns 'qemu'. The disk driver name is specified in the domain
           XML definition:
          <domain ...>
             <devices>
            <disk ...>
               <driver name='qemu' ...>

get_disk_format

 Parameters  : none
 Returns     : string
 Description : Returns 'qcow2'. The disk format is specified in the domain XML
           definition:
          <domain ...>
             <devices>
            <disk ...>
               <driver type='qcow2' ...>

get_disk_file_extension

 Parameters  : none
 Returns     : string
 Description : Returns 'qcow2'. This is used by libvirt.pm as the file extension
           of the virtual disk file paths.

pre_define

 Parameters  : none
 Returns     : boolean
 Description : Performs the KVM-specific steps prior to defining a domain:
           * Checks if the master image file exists on the node, If it does
             not exist, attempts to copy image from repository to the node
           * Creates a copy on write image which will be used by the domain
             being loaded

PRIVATE METHODS

get_virtual_disk_file_info

 Parameters  : $virtual_disk_file_path
 Returns     : hash reference
 Description : Calls 'qemu-img info' to retrieve the virtual disk information.
           Builds a hash based on the output. Example:
          "backing_file" => "/var/lib/libvirt/images/vmwarewinxp-base234-v23.qcow2 (actual path:
/var/lib/libvirt/images/vmwarewinxp-base234-v23.qcow2)", 
          "backing_file_actual_path" => "/var/lib/libvirt/images/vmwarewinxp-base234-v23.qcow2",
          "cluster_size" => 65536,
          "disk_size" => "423M",
          "disk_size_bytes" => 443547648,
          "file_format" => "qcow2",
          "image" => "/var/lib/libvirt/images/vclv99-37_234-v23.qcow2",
          "snapshot" => {
            1 => {
              "date" => "2011-12-07 14:43:12",
              "tag" => "snap1",
              "vm_clock" => "00:00:00.000",
              "vm_size" => 0
            }
          },
          "virtual_size" => "20G (21474836480 bytes)",
          "virtual_size_bytes" => "21474836480"

get_virtual_disk_size_bytes

 Parameters  : $image_name (optional)
 Returns     : integer
 Description : Returns the size of the virtual disk in bytes.

copy_virtual_disk

 Parameters  : $source_file_paths, $destination_file_path, $disk_format (optional)
 Returns     : boolean
 Description : Calls qemu-img to copy a virtual disk image. The destination disk
           format can be specified as an argument. If omitted, qcow2 is
           used.

create_copy_on_write_image

 Parameters  : $master_image_file_path, $copy_on_write_file_path
 Returns     : boolean
 Description : Calls qemu-img to create a copy on write virtual disk image based
           on the master image. The resulting image is written to by the VM
           when it makes changes to its hard disk. Multiple VMs may utilize
           the master image file. Each writes to its own copy on write image
           file. The master image file is not altered.

update_windows_image

Parameters : $virtual_disk_file_path Returns : boolean Description : Runs virt-win-reg to update the registry of the image specified by the $virtual_disk_file_path argument. The virt-win-reg utility is provided by libguestfs-tools. This subroutine returns true if virt-win-reg isn't installed.

       Adds registry keys to disable VMware services. If the image is
       Windows 5.x, registry keys are added to enable the builtin IDE
       drivers. This allows Windows images converted from VMware using a
       SCSI virtual disk to be loaded on KVM.</pre>