module OmfRc::ResourceProxy::VirtualMachine

This module defines a Resource Proxy (RP) for a Virtual Machine Factory

Utility dependencies: common_tools, libvirt, vmbuilder

This VM Proxy has the following properties:

USAGE NOTES:

A VirtualMachine Proxy is an interface to an underlying VM resource on a physical resource. When a VM Proxy is created, it is not necessarily yet associated with such a VM resource (unless the original ‘create’ command for this VM Proxy had some optional property configuration as described below).

Thus you must associate this VM Proxy with an underlying VM resource. This could be done in the following manner:

Once the VM Proxy is associated to an underlying VM resource, it can start/stop it or de-associated (‘delete’ action) from it, according to the following state diagram:

                 build,
              clone,define,
+---------+      attach     +---------+     run     +---------+
|         |--------|------->| stopped |------|----->|         |
| stopped |                 | + ready |             | running |
|         |<-------|--------|         |<-----|------|         |
+---------+     delete      +---------+     stop    +---------+

Some examples of message sequences to send to a freshly created VM proxy ‘new_VMP’ to realise each of the above association cases are given in the ‘Examples’ section below.

@example Case A: create and then run a new VM with a new disk image using all the default settings:

# Communication setup
comm = Comm.new(:xmpp)
vm_topic = comm.get_topic('new_VMP')

# Define the messages to publish
conf_vm_name = comm.configure_message([vm_name: 'my_VM_123'])
conf_vm_options = comm.configure_message([
                       ubuntu_opts: { bridge: 'br0' }, 
                       vmbuilder_opts: {ip: '10.0.0.240', 
                                        net: '10.0.0.0',
                                        bcast: '10.255.255.255',
                                        mask: '255.0.0.0',
                                        gw: '10.0.0.200',
                                        dns: '10.0.0.200'} ])
conf_vm_build = comm.configure_message([action: :build])
conf_vm_run = comm.configure_message([action: :run])

# Define a new event to run the VM resource once it is 'ready'
vm_topic.on_message do |m|
  if (m.operation == :inform) && (m.read_content("itype") == 'STATUS') && m.read_property('ready')
    conf_vm_run.publish vm_topic.id    
  end
end

# Publish the defined messages
conf_vm_name.publish vm_topic.id    
conf_vm_options.publish vm_topic.id    
conf_vm_build.publish vm_topic.id

@example Case B: create and run a new VM using an existing definition file:

# Do the communication setup as in the above example...

# Define the messages to publish
conf_vm_name = comm.configure_message([vm_name: 'my_VM_123'])
conf_vm_definition = comm.configure_message([vm_definition: '/home/me/my_vm_definition.xml'])
conf_vm_define = comm.configure_message([action: :define])
conf_vm_run = comm.configure_message([action: :run])

# Define a new event to run the VM resource as in the above example...

# Publish the defined messages
conf_vm_name.publish vm_topic.id    
conf_vm_definition.publish vm_topic.id    
conf_vm_define.publish vm_topic.id

@example Case C: create and run a new VM by cloning an existing VM:

# Do the communication setup as in the above example...

# Define the messages to publish
# Note that the existing VM to clone from must be defined and known
# by the virtualisation management tool set in the :virt_mngt property
conf_vm_name = comm.configure_message([vm_name: 'my_VM_123'])
conf_vm_original_name: comm.configure_message([vm_original_clone: 'existing_VM_456']),
conf_vm_clone = comm.configure_message([action: :clone_from])
conf_vm_run = comm.configure_message([action: :run])

# Define a new event to run the VM resource as in the above example...

# Publish the defined messages
conf_vm_name.publish vm_topic.id    
conf_vm_original_name.publish vm_topic.id    
conf_vm_clone.publish vm_topic.id

@example Case D: associate an existing VM to this VM Proxy and run it:

# Do the communication setup as in the above example...

# Define the messages to publish
# Note that the existing VM to associate to this VM Proxy must be defined 
# and known by the virtualisation management tool set in the :virt_mngt property
conf_vm_name = comm.configure_message([vm_name: 'my_VM_123'])
conf_vm_attach: comm.configure_message([action: :attach]),
conf_vm_run = comm.configure_message([action: :run])

# Define a new event to run the VM resource as in the above example...

# Publish the defined messages
conf_vm_name.publish vm_topic.id    
conf_vm_attach.publish vm_topic.id

EXTENSION NOTES:

By default this VM Proxy interacts with a KVM hypervisor using the libvirt virtualisation tools (i.e. virsh, virt-clone) to manipulate Ubuntu-based VMs, which may be built using ubuntu’s vmbuilder tool. However, one can extend this to support other hypervisors and tools.

@see OmfRc::Util::Libvirt @see OmfRc::Util::Vmbuilder

Constants

HYPERVISOR_DEFAULT

Default Hypervisor to use

HYPERVISOR_URI_DEFAULT

Default URI for the default Hypervisor

IMAGE_BUILDER_DEFAULT

Default VM image building tool to use

OMF_DEFAULT

Default OMF v6 parameters for the Resource Controller on the VM

VIRTUAL_MNGT_DEFAULT

Default virtualisation management tool to use

VM_DIR_DEFAULT

Default directory to store the VM’s disk image

VM_NAME_DEFAULT_PREFIX

Default prefix to use for the VM’s name

VM_OS_DEFAULT

Default OS used on this VM