Module: OmfRc::ResourceProxy::VirtualMachine

Includes:: OmfRc::ResourceProxyDSL
Defined in:: omf_rc/lib/omf_rc/resource_proxy/virtual_machine.rb

Overview

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:

:use_sudo, use 'sudo' when running VM-related commands (default => true)
:hypervisor, the hypervisor to use (default => HYPERVISOR_DEFAULT)
:hypervisor_uri, the URI of the hypervisor to use (default => HYPERVISOR_URI_DEFAULT)
:virt_mngt, the virtualisation management tool to use (default => VIRTUAL_MNGT_DEFAULT)
:img_builder, the tool to use to build VM image (default => IMAGE_BUILDER_DEFAULT)
:state, the current state of this VM Proxy (default => :stopped)
:ready, is the VM for this Proxy ready to be run? (default => false)
:action, the next action to perform on this VM Proxy (build, define, stop, run, delete, attach, or clone_from)
:vm_name, the name of this VM (default => VM_NAME_DEFAULT_PREFIX + “_” + current time)
:image_directory, the directory holding this VM's disk image (default => VM_DIR_DEFAULT)
:image_path, the full path to this VM's disk image (default => image_directory + vm_name)
:vm_os, the OS to use on this VM (default => VM_OS_DEFAULT)
:vm_definition, the path to an definition file for this VM
:vm_original_clone, the name of an existing VM that may be used as a template for this one
:enable_omf, is an OMF Resource Proxy (to be) installed on this VM? (default => true)
:omf_opts, the options to set for the OMF v6 RC on this VM (default => OMF_DEFAULT)

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:

A) build a brand new VM resource, including building a new disk image for it
B) build a new VM resource from an existing VM definition file
C) build a new VM resource by cloning an existing VM resource
D) attach a VM resource (existing already on the system) to this VM Proxy

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.

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.

to extend:
- create one/many utility file(s) to hold the code of your extension, e.g. “myext.rb”
- assuming you will use the “foo” virtualisation management tools, and the “bar” image building tool, then you must define within your utility file(s) the following work methods, which should perform the obvious tasks mention by their names. In addition they must return 'true' if their tasks were successfully performed, or 'false' otherwise. See the provided libvirt and vmbuilder utility files for some examples.
  - define_vm_with_foo
  - stop_vm_with_foo
  - run_vm_with_foo
  - attach_vm_with_foo
  - clone_vm_with_foo
  - delete_vm_with_foo
  - build_img_with_bar
to use that extension:
- require that/these utility files
- set the virt_mngt, virt_mngt properties to “foo”, “bar” respectively

Examples:

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

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

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

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

Constant Summary

HYPERVISOR_DEFAULT = Default Hypervisor to use

:kvm

HYPERVISOR_URI_DEFAULT = Default URI for the default Hypervisor

'qemu:///system'

VIRTUAL_MNGT_DEFAULT = Default virtualisation management tool to use

:libvirt

IMAGE_BUILDER_DEFAULT = Default VM image building tool to use

:vmbuilder

VM_NAME_DEFAULT_PREFIX = Default prefix to use for the VM's name

"vm"

VM_DIR_DEFAULT = Default directory to store the VM's disk image

"/home/thierry/experiments/omf6-dev/images"

VM_OS_DEFAULT = Default OS used on this VM

'ubuntu'

OMF_DEFAULT = Default OMF v6 parameters for the Resource Controller on the VM

Hashie::Mash.new({
server: 'srv.mytestbed.net', 
user: nil, password: nil,
topic: nil
})

Constants included from OmfRc::ResourceProxyDSL

OmfRc::ResourceProxyDSL::DEFAULT_PROP_ACCESS, OmfRc::ResourceProxyDSL::PROXY_DIR, OmfRc::ResourceProxyDSL::UTIL_DIR

Method Summary

Methods included from OmfRc::ResourceProxyDSL

#call_hook, #hook_defined?, included