/ 
Provision-Unix-0.79
River stage zero No dependents
/ Provision::Unix::VirtualOS

NAME

Provision::Unix::VirtualOS - Provision virtual environments (VEs)

SYNOPSIS

use Provision::Unix;
use Provision::Unix::VirtualOS;

my $prov = Provision::Unix->new();
my $vos = Provision::Unix::VirtualOS->new( prov => $prov );

$vos->create(
     name        => 42,
     password    => 't0ps3kretWerD',
     ip          => '10.1.1.43',
     hostname    => 'test_debian_5.example.com',
     disk_size   => 1000,
     ram         => 512,
     template    => 'debian-5-i386-default.tar.gz',
     nameservers => '10.1.1.2 10.1.1.3',
     searchdomain => 'example.com',
)
or $prov->error( "unable to create VE" );

DESCRIPTION

Provision::Unix::VirtualOS aims to provide a clean, consistent way to manage virtual machines on a variety of virtualization platforms including Xen, OpenVZ, Vmware, FreeBSD jails, and others. P:U:V provides a command line interface (prov_virtual) and a stable programming interface (API) for provisioning virtual machines on supported platforms. To start a VE on any supported virtualization platform, you run this command:

prov_virtual --name=42 --action=start

Versus this:

xen: xm create /home/xen/42/42.cfg
ovz: vzctl start 42
ezj: ezjail-admin start 42

P:U:V tries very hard to insure that every valid command that can succeed will. There is abundant code for handling common errors, such as unmounting xen volumes before starting a VE, making sure a disk volume is not in use before mounting it, and making sure connectivity to the new HW node exists before attempting to migrate.

In addition to the pre-flight checks, there are also post-action checks to determine if the action succeeded. When actions fail, they provide reasonably good error messages geared towards comprehension by sysadmins. Where feasible, actions that fail are rolled back so that when the problem(s) is corrected, the action can be safely retried.

USAGE

If you are looking for a command line utility, have a look at the docs for prov_virtual. If you are looking to mate an existing Customer Relationship Manager (CRM) or billing system (like Ubersmith, WHMCS, Modernbill, etc..) with a rack full of hardware nodes, this class is it. There are two existing implementations, the prov_virtual CLI, and an RPC agent. The CLI and remote portion of the RPC agent is included in the distribution as bin/remoteagent.

CLI

The best way to interface with P:U:V is using a RPC agent to drive this class directly. However, doing so requires a programmer to write an application that accepts/processes requests from your CRMS system and formats them into P:U:V requests.

If you don't have the resources to write your own RPC agent, and your CRM/billing software supports it, you may be able to dispatch the requests to the HW nodes via a terminal connection. If you do this, your CRM software will need to inspect the result code of the script to determine success or failure.

P:U calls are quiet by default. If you want to see all the logging, append each CLI request with --verbose. Doing so will dump the audit and error reports to stdout.

API

The implementation I use implements RPC over SSH. The billing system we use is rather 'limited' so I wrote a separate request brokering application (maitred). It uses the billing systems API as a trigger to perform basic account management actions (create, destroy, enable, disable). We also provide a control panel so our clients can manage their VEs. The control panel also generates requests (start, stop, install, reinstall, reboot, upgrade, etc). Administrators also have their own control panel which also generates requests.

When a request is initiated, the broker allocates any necessary resources (IPs, licences, a slot on a HW node, etc) and then dispatches the request. The dispatcher builds an appropriate SSH invocation that connects to the remote HW node and runs the remoteagent. Once connected to the remoteagent, the P:U:V class is loaded and its methods are invoked directly. The RPC agent checks the result code of each call, as well as the audit and error logs, feeding those request events back. The RPC local agent logs the request events into the request brokers database so there's a complete audit trail.

RPC methods

RPC is often implemented over HTTP, using SOAP or XML::RPC. However, our VEs are deployed with local storage. We needed the ability to move a VE from one node to another. In addition to the broker to node relationship, we would have also need temporary trust relationships between the nodes, in order to move files between them with root permissions.

The trust relationships are much easier to manage with SSH keys. In our environment, only the request brokers are trusted. In addition to being able to connect to any node, they can also connect from node to node using using ssh-agent and key forwarding.

RPC gotcha

The $vos->migrate() function expects to be running as a user that has the ability to initiate a SSH connection from the node on which it's running, to the node on which you are moving the VE. Our RPC agent connects to the HW nodes as the maitred user and then invokes the remoteagent using sudo. Our sudo config on the HW nodes looks like this:

Cmnd_Alias MAITRED_CMND=/usr/bin/remoteagent, /usr/bin/prov_virtual
maitred     ALL=NOPASSWD: SETENV: MAITRED_CMND

Since the RPC remoteagent is running as root, the request broker has access to a wide variety of tools (tar over ssh pipe, rsync, etc) to move files from one node to another, without the nodes having any sort of trust relationship between them.

FUNCTIONS

$vos->start(   name => 42 );
$vos->stop(    name => 42 );
$vos->restart( name => 42 );

$vos->enable(  name => 42 );
$vos->disable( name => 42 );

$vos->set_hostname(    name => 42, hostname => 'new-host.example.com' );
$vos->set_nameservers( name => 42, nameservers => '10.1.1.3 10.1.1.4' );
$vos->set_password(    name => 42, password    => 't0ps3kretWerD' );
$vos->set_ssh_key(     name => 42, ssh_key     => 'ssh-rsa AAAAB3N..' );

$vos->modify(
    name      => 42,
    disk_size => 2000,
    hostname  => 'new-host.example.com',
    ip        => '10.1.1.43 10.1.1.44',
    ram       => 768,
);

$vos->get_status( name => 42 );
$vos->migrate( name => 42, new_node => '10.1.1.13' );
$vos->destroy( name => 42 );

AUTHOR

Matt Simerson, <matt at tnpi.net>

BUGS

Please report any bugs or feature requests to bug-unix-provision-virtualos at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Provision-Unix. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Provision::Unix::VirtualOS

You can also look for information at:

COPYRIGHT & LICENSE

Copyright 2008 Matt Simerson

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.