VF Profile Format

From RedHatET

Virt-Factory uses a concept of "profiles" to express what a machine should do.

The easiest way to look at how profiles are built is to look at the sample profiles at http://virt-factory.et.redhat.com/download/profiles, and crack them open.

The main thing about profiles is they have an XML file in a certain format, which specifies the distribution, memory, and other requirements the machine should have.

It also bundles with it a list of Puppet (see http://reductivelabs.com) recipes and files which describe the machine configuration. Profile authors have the option of specifying all sorts of configuration in the profiles, or just leaving them fairly minimal.

The "Test1" and "Container" profiles are both fairly minimal. This makes the machines pretty much unmanaged by puppet, though if one really wants to make "real" appliances, these profiles would be more feature rich.

We'll be posting some more sample profiles as the project rolls along.

We keep profiles in the source under the "docs/profile" directory.

Profile structure

Profiles should be a self-contained tarball with the following directory structure:

• profile.xml -- includes metadata needed for adding to VF database.
• manifests/profilename.pp -- main puppet manifest for the profile (should include the others)
• manifests/*.pp -- other puppet manifests, can be named anything
• files/* -- includes data files referenced by manifests
• templates/* -- includes templates referenced by manifests

Starting with version 0.0.3, profiles will be distributed as an RPM, with installed file layout similar in structure to the current tarball:

• /var/lib/virt-factory/profiles/PROFILENAME/profile.xml -- includes metadata needed for adding to VF database.
• /var/lib/virt-factory/profiles/PROFILENAME/manifests/init.pp -- main puppet manifest for the profile (other manifest files could be in this dir if they're included by init.pp)
• /var/lib/virt-factory/profiles/PROFILENAME/manifests/*.pp -- other puppet manifests, can be named anything
• /var/lib/virt-factory/profiles/PROFILENAME/files/* -- includes data files referenced by manifests
• /var/lib/virt-factory/profiles/PROFILENAME/templates/* -- includes templates referenced by manifests

profile.xml structure

Here's a sample profile.xml:

<?xml version='1.0' encoding='utf-8'?>
<appliance-container>
  <name>Container</name>
  <version>1</version>
  <distribution>FC-6-i386</distribution>
  <virt_storage_size>0</virt_storage_size>
  <virt_ram>0</virt_ram>
  <kickstart_metadata></kickstart_metadata>
  <kernel_options></kernel_options>
  <valid_targets>is_baremetal</valid_targets>
  <is_container>1</is_container>
  <puppet_classes>site_settings class1 class2</puppet_classes>
</appliance-container>

Fields are defined as follows:

• name: name of the image
• version: the version
• distribution: must match the name of the imported cobbler distribution
• virt_storage_size: minimum required storage for hosts/guests which use this profile
• virt_ram: minimum allocated RAM for hosts/guests which use this profile
• kickstart_metadata: kickstart metadata
• kernel_options: kernel options
• valid_targets: whether this profile defines hosts (is_baremetal) or guests (is_virt)
• is_container: (for hosts only) whether guests may be started on a host running this profile
• puppet_classes: space-delimited list of puppst classes which will be assigned to nodes running this profile (shoult correspond to those classes defined in the puppet manifest files)

Creating profiles (0.0.3 and later)

vf_get_profile_stub is a helper script that will generate a profile src/build tree for a single profile. The only required argument is name (--name or -n). Running:

vf_gen_profile_stub --name foo

will set up the directory structure for a profile with the name "foo". First, a directory foo will be created as a subdirectory of the current working dir. Within this directory will be the following:

• Makefile: to generate the profile xml, run 'make'
• profile.xml: in the minimal case, the name element will be filled in. The remaining profile.xml elements will be filled in if the optional args to vf_gen_profile_stub are included
• version: contains 3 space-separated elements. profile name, version, and release -- these are all used by the spec file
• vf-profile-$profilename.spec: specfile for the profile RPM. Summary, description, and changelog entries must be entered manually
• manifests: puppet manifest dir. init.pp is included but is blank (except for comments)
• files: empty directory for puppet files referenced by the manifest
• templates: empty directory for puppet templates referenced by the manifest

Additional command line args to vf_gen_profile_stub will fill out the remaining profile.xml fields:

usage: vf_gen_profile_stub [options] 

options:
  -h, --help            show this help message and exit
  -n NAME, --name=NAME  profile name
  -v VERSION, --version=VERSION
                        profile version
  -r RELEASE, --release=RELEASE
                        profile rpm release
  -d DISTRIBUTION, --distribution=DISTRIBUTION
                        profile distribution
  -s STORAGE, --storage=STORAGE
                        profile virt storage size
  -m RAM, --ram=RAM     profile virt ram
  -k KSMETADATA, --ksmetadata=KSMETADATA
                        profile kickstart metadata
  -o KOPTIONS, --koptions=KOPTIONS
                        profile kernel options
  -t TARGETS, --targets=TARGETS
                        Valid target type for the profile (i.e. for virt vs.
                        baremetal provisioning).
  -c CONTAINER, --container=CONTAINER
                        Whether a host running this profile is a valid target
                        for VM guests.
  -p PUPPETCLASSES, --puppetclasses=PUPPETCLASSES
                        profile puppet classes

Installing profiles (0.0.3 and later)

The first step in installing (or upgrading) a profile is to install the RPM. When the RPM is installed, an empty file with the name of the profile is created in /var/lib/virt-factory/profiles/queued. Running vf_import with no arguments will import (or update) all profiles that have not yet been imported. If a profile name is passed into vf_import, then only that single profile will be imported.