SmartDomains tutorial

SmartDomains is a tool for automated deployment and management of distributed Xen virtual machines.
Project page
Project authors: Olivier Pernet and Xavier Grehant.
Developed as part of Grid IC projects of CERN openlab second phase.

This tutorial: Xavier Grehant (xagATcernDOTch)
In sync with revision 127 (release 0.9.08)

SmartDomains is a showcase of SmartFrog, a framework for distributed configuration and deployment developed at HP Labs.

Contents

• Installation
• Launch a simple description
• Describe a pool of virtual domains
• Orchestrate virtual domains

Describe a pool of virtual domains

• A local pool with minimal attributes
• A distributed deployment
• Using all attributes
• Runtime update

A local pool with minimal attributes

localVirtualPool.sf describes a pool of 2 virtual domains to be deployed on the same machine: domain1 and domain2. The file's content is displayed below:

This description illustrates the 3 base components you can manipulate in a SmartDomains description: XenDomain, LVMStorageBackend and LoopbackStorageBackend. A virtual domain is described by extending a XenDomain component. In this description, our two virtual domains have some attributes in common. We factorized these attributes in DefaultXenDomain.

To clarify the meaning of extends, let's just observe that the description of domain1 in localVirtualPool.sf is equivalent to the one below:

In localVirtualPool.sf, loop is the StorageBackend of domain1, and lvm the StorageBackend of domain2: they handle guest filesystems setup (resp. teardown) on the physical host before (resp. after) guest domains being started (resp. shutdown). domain1 will run on a logical volume, and domain2 on a loopback-mounted image file.

Some if this description's attributes are self-explanatory: kernel, gateway, netmask, baseImage, ip, hostname, domainName. They need to be customized according to your infrastructure.

Understanding attributes sfSyncTerminate, shell and StorageBackend probably requires more explanations:

• sfSyncTerminate is an attribute of Compound. Unlike the other attributes here, it doesn't refer to a component. It is not meant to be deployed, but to customize the way Compound handles its children components. sfSyncTerminate true means that Compound will ensure that all its children terminate together. In particular, we'll not loose the shell nor the StorageBackends before the domains are closed.
• shell: All base SmartDomains components run shell commands on the host on which they are deployed. They need to know what shell to use. BashShell is a SmartFrog component. ATTRIB is a keyword referring to an attribute up in the components hierarchy. LAZY means that attribute shell will not get bound its value before myShell is deployed. It is important to note that attributes are always ordered, and a Compound deploys its children in order, then starts them in order. It is therefore important to put myShell before loop for loop:shell to be resolved successfully on loop deployment.
• StorageBackend's resolution follows the same principle as shell.

A distributed deployment

distVirtualPool.sf launches virtual domains on remote physical machines, and the management console on the host specified in sfStart command. Changes with regards to localVirtualPool.sf are displayed below.

sfProcessHost takes either a hostname or an ip address. A component with this attribute will be deployed on the designated host, as well as its children components (attributes in the description) and recursively their descendants.

Using all attributes

remoteConfig.sf, defaultPool.sf and selection.sf together describe a single virtual machine deployment on a remote host. This example shows other self-explanatory SmartFrog language tricks, as well as other attributes for base SmartDomains components. defaultPool.sf contains default components for possible use in sfConfig through a direct include of selection.sf. To launch the example after adapting values to your setup, you need to call sfStart command on the file that contains sfConfig: remoteConfig.sf.

We provide here a list of attributes that must/can be defined in using base SmartDomains components.

• XenDomain
• shell: LAZY binding to a deployed component made from org.smartfrog.services.shellscript.SFScriptImpl.
• domainName: Same as in StorageBackend below. Useless since rev 84 (rel 0.9.02)
• hostname: string; virtual guest hostname
• ip: string; virtual guest ip
• netmask: string; usually same as physical host
• gateway: optional string; Xen generates the default
• kernel: string; full path to the file, like in grub.conf
• ramdisk: optional string; default: no initrd
• memory: optional Integer; default 512; in MBytes
• vcpus: optional Integer; default 1. Number of virtual CPUs
• domainLivenessDelay: optional Integer; default 2000. Time in ms between 2 liveness checks. Since rev 88 (rel 0.9.02)
• domainLivenessFactor: optional Integer; default 3. Number of failed liveness checks before termination diagnosis. Since rev 88 (rel 0.9.02)
• domainLivenessCheck: optional boolean; default true. True if we want SmartFrog to keep checking the liveness of the virtual domain. Since rev 126 (rel 0.9.08)
• extra: optional String; default "fastboot nousb". Extra options for root module (Xen configuration options.) Since rev 88 (rel 0.9.02)
• storageBackend: LAZY binding to a deployed StorageBackend

• LoopbackStorageBackend and LvmStorageBackend
• shell: idem
• domainName: string; name you would see on 'xm list'
• baseImage: string; e.g. "/data/xen/slc3-smartfrog.img"; can be a tar, tar.gz, tgz, tar.bz2, gz, bz2, img
• volumeSize: optional string; e.g. "1500m", "5g"; default "1g"
• swapSize: optional string; default "512m"
• volumeBaseName: optional string; default xen-domain-[domainName]; name of root logical volume or root loopback image
• usingExistingVolumes: optional boolean; default false; if set to true: reuses the volumes if they exist, which saves a lot of time; if set to false: fails if volumes already exist.
• keepVolumes: optional string (not boolean); tells if volumes will be kept after termination for fast re-use; default "statuquo". Other possible values : "true" or "false"; "statuquo" means it keeps the volumes only if the root volume was already there before. Taken into account only on normal termination; true otherwise.
• saveImage: optional boolean; default false; tells if the root volume will be saved as an image after termination.
• saveImageName: optional string; if not provided, a name based on the time will be generated.
• saveImagePath: optional string; necessary if [saveImageName] is not provided and [saveImage] is true; chosen in case of contradiction with path of saveImageName
• saveImageExtension: optional string; necessary if saveImageName is not provided and saveImage is true; decides compression type in case of contradiction with extension of saveImageName; possible extensions: tar, gz, tar.gz, tgz, tar.bz2, bz2, img
• tempMountPoint: optional string; for internal use; to specify if you don't want the program to create a random directory into /tmp/mnt/
• makeFs: optional string; for advanced users who want to specify a different way of creating the root filesystem. Default "mkfs.ext3" (fine for most ext3 and ext2 filesystems).

• LvmStorageBackend-specific
• volumeGroup: optional string; default "vg"; receives the logical volumes to run the guest domain.

• LoopbackStorageBackend-specific
• imageReceptacle: optional string; default "/data/xen"; receives the loopback image to run the guest domain.

Runtime update

Using the management console, it is possible to modify, add or delete at run-time attributes that affect the component only on termination. The snapshot below was taken from the deployment described in previous paragraph.