imagefactory | build, push, deploy

Writing Plugins For Imagefactory

2014-07-30T00:00:00+00:00

Have you found yourself wishing that Image Factory supported your favorite tool for building system images or some new hypervisor / cloud? Maybe you’re developing a new cloud offering or you have a favorite OS that you would like to see Image Factory build images for.

Would you be surprised if I told you that writing a plugin for Image Factory is relatively easy? Actually, let’s back up a second… are you surprised to learn that Image Factory uses plugins?

If the answer to any of these questions was ‘Yes’, then hopefully this post will introduce you to an exciting world of image building possibilities.

Since the Nova plugin was just released, I’ll tear that open to use as a real world example. The source for this plugin can be found in the imagefactory git repository.

What’s in a plugin?

First, what IS an imagefactory plugin? If you look at the plugins already installed on your system, you’ll see a number of directories that look like Python packages. You will find these in the imagefactory_plugins directory in the SITE_PACKAGES for the Python environment under which you run imagefactory.

According to the imagefactory plugins documentation, there are only two things you need to add to a Python package in order to make it a plugin that imagefactory will recognize and load.

These tasks are:

Assign the delegate class.
Define the plugin metadata.

Let’s take a look at the second item first and create a .info document that describes our plugin. This file is named after the plugin it describes. In our case, this would be the Nova.info file that looks like this:

{
    "type": "os",
    "targets": [ ["Fedora", null, null], ["RHEL-6", null, null], ["RHEL-5", null, null],
                 ["RHEL-7", null, null], ["Ubuntu", null, null], ["CentOS-6", null, null],
                 ["CentOS-5", null, null], ["Windows", null, null] ],
    "description": "Plugin to support building OS base images using OpenStack Nova.",
    "maintainer": {
        "name": "Red Hat, Inc.",
        "email": "imagefactory-devel@lists.fedorahosted.org",
        "url": "http://imgfac.org"
    },
    "version": "1.0",
    "license": "Copyright 2012 Red Hat, Inc. - http://www.apache.org/licenses/LICENSE-2.0"
}

The .info file is just a JSON document that describes the plugin with a set of key/value pairs.See all of that stuff there? It is REALLY important that everything is defined before a plugin is released. Okay, now that I’ve said that, I’ll point out that the only two keys that need values in order for the plugin to be loaded by imagefactory are the first two, type and targets.

The “type” of the plugin is either “os” or “cloud”. If your plugin will be installing an operating system into an image in some way, then it is an “os” plugin. If your plugin will be transforming a base image that already has an operating system installed into something that your target hypervisor or cloud can use, then the plugin is a “cloud” plugin. This will come into play once we start writing code to implement our plugin, but we’ll get to that soon enough.

The “targets” value is a list of terms matched when building a base or target image. In the case of an OS plugin, each value in that list is itself a list of the OS name, the OS version, and the OS architecture. In a TDL document, this matches the name, version, arch child elements under the os element. In our example the above, null is used as a wildcard meaning that each entry matches for any version or architecture of the OS listed by name.

For a Cloud plugin, each of the values in the targets list is just a string that is the name of the cloud or hypervisor with which the plugin is compatible. This cloud name is what will be passed to imagefactory when using the target_image or provider_image command. Here is the target entry in the .info file for the Docker plugin as an example:

    "targets": [ [ "docker"] ],

Now that we have described the plugin, we need to implement it. Here is where we need to satisfy the first requirement of assigning the delegate class. The delegate class is the interface imagefactory uses to interact with the plugin and define the methods your plugin can implement. This class will implement either the OSDelegate or CloudDelegate interface. The Nova plugin, the example for this article, is an OS plugin, so the delegate class implements the OSDelegate interface in the Nova.py module:

import zope
import logging

class Nova(object):
    zope.interface.implements(OSDelegate)
    def __init__(self):
        super(Nova, self).__init__()
        self.log = logging.getLogger('%s.%s' % (__name__, self.__class__.__name__))

    def create_base_image(self, builder, template, parameters):
        self.log.info('create_base_image() called for Nova plugin - creating a BaseImage')

    def create_target_image(self, builder, target, base_image, parameters):
        self.log.info('create_target_image() called for Nova plugin - creating a TargetImage')

In order for imagefactory to find the class that implements the delegate interface, in this case Nova, we need to assign that class. We do this in the __init__.py of our plugin package with a line like this:

from Nova import Nova as delegate_class

Now imagefactory knows how to call into our plugin when creating a base image for the operating systems our plugin supports.

Our example code listing above doesn’t do anything but log that each method was called. There is, of course, more to connecting to OpenStack Nova to spawn an instance, install an OS, and customize it for use by future instances. Luckily, there is a project we can use in this plugin to handle these tasks. Once we have installed Nova Image Builder we can import what we need into our delegate class and call out to this other project to do the heavy lifting for us:

import zope
import logging
from novaimagebuilder.Builder import Builder

class Nova(object):
    zope.interface.implements(OSDelegate)
    def __init__(self):
        super(Nova, self).__init__()
        self.log = logging.getLogger('%s.%s' % (__name__, self.__class__.__name__))
        self.nib = None

    def create_base_image(self, builder, template, parameters):
        self.log.info('create_base_image() called for Nova plugin - creating a BaseImage')
        if template.os_version:
            if template.os_name[-1].isdigit():
                install_os = '%s.%s' % (template.os_name, template.os_version)
            else:
                install_os = '%s%s' % (template.os_name, template.os_version)
        else:
            install_os = template.os_name

        install_os = install_os.lower()

        install_location = template.install_location
        # TDL uses 'url' but Nova Image Builder uses 'tree'
        install_type = 'tree' if template.install_type == 'url' else template.install_type
        install_script = parameters.get('install_script')
        install_config = {'admin_password': parameters.get('admin_password'),
                          'license_key': parameters.get('license_key'),
                          'arch': template.os_arch,
                          'disk_size': parameters.get('disk_size'),
                          'flavor': parameters.get('flavor'),
                          'storage': parameters.get('storage'),
                          'name': template.name,
                          'direct_boot': parameters.get('direct_boot', False),
                          'timeout': parameters.get('timeout', 1800),
                          'public': parameters.get('public', False),
                          'floating_ip': parameters.get('request_floating_ip', False)}

        builder.base_image.update(10, 'BUILDING', 'Created Nova Image Builder instance...')
        self.nib = Builder(install_os, install_location, install_type, install_script, install_config)
        self.nib.run()
        jeos_image_id = self.nib.wait_for_completion(180)
        builder.base_image.properties['x-image-properties-glance_id'] = jeos_image_id

In the code above, we are gathering the information Nova Image Builder will need from the TDL that was passed in along with any external build parameters. This information is then passed to a new instance of the Builder class in Nova Image Builder, which is then told to run the build task. Finally, we wait for a glance id for the built image to be returned which we set in the metadata imagefactory stores locally so that we can find the image and use it later.

There is more to the implementation of the Nova plugin, but that gets beyond the scope of this article. If you are interested in all of the gory details, have a look in the imagefactory git repository.

So, there you have it. Plugins for imagefactory.

Running Diskimage Builder With Indirection Plugin

2014-07-29T00:00:00+00:00

Indirection plugin is the most versatile plugin for ImageFactory. Indirection allows the user to go beyond just package installation and configuration. Originally it was developed to generate LiveCD images using the livemedia-creator project in Fedora. More on that can be found [here] (https://github.com/redhat-imaging/imagefactory/blob/master/imagefactory_plugins/IndirectionCloud/README.md). Such flexibility is achieved by breaking up the image building process into three steps.

Step 1: Create utility image

Utility image is the image that contains any special tools needed to customize an image. In the example here, the utility image will contain diskimage-builder, instack-undercloud, and git packages. The following kickstart file will be passed in to imagefactory as utility_image.ks:

url --url=http://ftp.linux.ncsu.edu/pub/fedora/linux/releases/20/Fedora/x86_64/os/
# Without the Everything repo, we cannot install cloud-init
repo --name="fedora-everything" --baseurl=http://ftp.linux.ncsu.edu/pub/fedora/linux/releases/20/Everything/x86_64/os/
repo --name="testing" --baseurl=http://mirror.pnl.gov/fedora/linux/updates/20/x86_64/
# At moment this is where the working version of diskimage-builder lives
repo --name=updates-testing --baseurl=http://mirror.pnl.gov/fedora/linux/updates/testing/20/x86_64/
# instack-undercloud lives here for now
repo --name=openstack --baseurl=http://repos.fedorapeople.org/repos/openstack/openstack-icehouse/fedora-20/

install
text
keyboard us
lang en_US.UTF-8

skipx

network --device eth0 --bootproto dhcp
rootpw ROOTPW
firewall --disabled
authconfig --enableshadow --enablemd5
selinux --enforcing
timezone --utc America/New_York
bootloader --location=mbr --append="console=tty0 console=ttyS0,115200"
zerombr
clearpart --all --drives=vda

part biosboot --fstype=biosboot --size=1
part /boot --fstype ext4 --size=200 --ondisk=vda
part pv.2 --size=1 --grow --ondisk=vda
volgroup VolGroup00 --pesize=32768 pv.2
logvol swap --fstype swap --name=LogVol01 --vgname=VolGroup00 --size=768 --grow --maxsize=1536
logvol / --fstype ext4 --name=LogVol00 --vgname=VolGroup00 --size=1024 --grow
reboot

%packages
@core
diskimage-builder
instack-undercloud
git
%end

The above TDL does not contain administrative password property. ImageFactory will complain unless /etc/imagefactory/imagefactory.conf has root password enforcement disabled in following manner:

{
  ...
  "tdl_require_root_pw": 0,
  ...
}

In addition to the kickstart file, ImageFactory requires a TDL template to build an image. Let’s call this file utility_image.tdl:

<template>
  <name>f20-jeos</name>
  <os>
    <name>Fedora</name>
    <version>20</version>
    <arch>x86_64</arch>
    <install type='url'>
      <url>http://ftp.linux.ncsu.edu/pub/fedora/linux/releases/20/Fedora/x86_64/os/</url>
    </install>
  </os>
  <disk>
    <size>20</size>
  </disk>
  <description>Fedora 20 JEOS Image</description>
</template>

The following command should be run from the directory where utility_image.tdl and utility_image.ks live:

imagefactory --debug base_image --file-parameter install_script utility_image.ks utility_image.tdl

Please take note of the image ID when ImageFactory finishes building the utility image ###Step 2: Create input image

After a utility image is built, another base image needs to be created to be used as input image. Since both utility image and input image are base_image, it is possible to use one image for both. Because diskimage-builder can only modify images without logical volumes, the following kickstart file (input_image.ks) will create a Fedora 20 image that fits this criteria:

url --url=http://ftp.linux.ncsu.edu/pub/fedora/linux/releases/20/Fedora/x86_64/os/
# Without the Everything repo, we cannot install cloud-init
repo --name="fedora-everything" --baseurl=http://ftp.linux.ncsu.edu/pub/fedora/linux/releases/20/Everything/x86_64/os/
install
text
keyboard us
lang en_US.UTF-8
skipx
network --device eth0 --bootproto dhcp
rootpw ROOTPW
firewall --disabled
authconfig --enableshadow --enablemd5
selinux --enforcing
timezone --utc America/New_York
bootloader --location=mbr --append="console=tty0 console=ttyS0,115200"
zerombr
clearpart --all --drives=vda
part / --fstype="ext4" --size=3000
reboot

%packages
@core
cloud-init
tar

%end

The following TDL template (input_image.tdl) is needed to build the input image:

<template>
  <name>f20-jeos</name>
  <os>
    <name>Fedora</name>
    <version>20</version>
    <arch>x86_64</arch>
    <install type='url'>
      <url>http://ftp.linux.ncsu.edu/pub/fedora/linux/releases/20/Fedora/x86_64/os/</url>
    </install>
  </os>
  <description>Fedora 20 JEOS Image</description>
</template>

The following command should be run from the directory where input_image.tdl and input_image.ks live:

imagefactory --debug base_image --file-parameter install_script input_image.ks input_image.tdl

Please take note of the image id when ImageFactory finishes building input image. ###Step 3: Create target image

The indirection plugin takes the following parameters. Some of the parameters have default values and as a result will not be present in the command used to build the target image. However, they are discussed here so one can modify this example in all possible ways.

–id - The image id for the input image

–parameter utility_image - The image id for utility image

–parameter input_image_device - The name of the device where the base_image is presented to the utility VM. Default is /dev/vdb1. The filesystem on this device is also referred to as workspace.

–parameter input_image_file - The path to the copy of input image in the workspace. Default is /input_image.raw. Either input_image_device or input_image_file can be provided at a time.

–parameter results_location - Full path to the customized image in the filesystem presented as work space. Default is /results/images/boot.iso

–file-parameter utility_customizations - Name of file containing partial TDL with commands to be exectuted after the utility image is launched in run level 3

The utility image is used to launch a VM in run level 3. The utility VM has an unmounted filesystem attached as ‘/dev/vdb1’ or input_image_device with the following characteristics:

The input image is available as ‘/input_image.raw’ or input_image_file
Once the customization TDL has finished running the plugin expects to find the resulting image at ‘/results/images/boot.iso’ or results_location.

The partial TDL (dib_overcloud_compute.tdl) below does the following:

Mounts the workspace filesystem to /mnt
Makes a copy of sudoers files
Modifies the sudoers file to disable requirement for tty when using sudo
Converts the input image from RAW to QCOW2 so diskimage-builder can consume it
Runs all the commands needed to build the ovecloud-compute [1]. disk-image-create command takes -o argument which specifies the name of output image. Since the workspace was mounted at /mnt the full path should be ‘/mnt/overloud-compute’ in order for the indirection plugin to find it at /overcloud-compute.qcow2

[1] https://github.com/agroup/instack-undercloud/blob/instack-undercloud-0.0.13-1/scripts/instack-build-images#L65

<template>
<commands>
   <command name='mount'>mount /dev/vdb1 /mnt</command>
   <command name='backup'>cp /etc/sudoers /etc/sudoers_backup</command>
   <command name='pty'>sed 's/.*requiretty//g' /etc/sudoers_backup > /etc/sudoers</command>
   <command name='convert'>qemu-img convert -f raw -O qcow2 /mnt/input_image.raw /mnt/input_image.qcow2</command>
   <command name="localimage">export DIB_LOCAL_IMAGE=/mnt/input_image.qcow2
set -eux
export TMP_DIR=${TMP_DIR:-/var/tmp}
export NODE_ARCH=${NODE_ARCH:-amd64}
export NODE_DIST=${NODE_DIST:-"fedora selinux-permissive"}
export DEPLOY_IMAGE_ELEMENT=${DEPLOY_IMAGE_ELEMENT:-deploy}
export DIB_INSTALLTYPE_nova=package
export DIB_INSTALLTYPE_heat=package
export DIB_INSTALLTYPE_keystone=package
export DIB_INSTALLTYPE_neutron=package
export DIB_INSTALLTYPE_glance=package
export DIB_INSTALLTYPE_swift=package
export DIB_INSTALLTYPE_cinder=package
export DIB_INSTALLTYPE_horizon=package
export DIB_INSTALLTYPE_python_cinderclient=package
export DIB_INSTALLTYPE_python_glanceclient=package
export DIB_INSTALLTYPE_python_heatclient=package
export DIB_INSTALLTYPE_python_keystoneclient=package
export DIB_INSTALLTYPE_python_neutronclient=package
export DIB_INSTALLTYPE_python_novaclient=package
export DIB_INSTALLTYPE_python_swiftclient=package
export DIB_INSTALLTYPE_python_ceilometerclient=package
export DIB_INSTALLTYPE_python_ironicclient=package
export DIB_INSTALLTYPE_os_collect_config=package
export DIB_INSTALLTYPE_os_refresh_config=package
export DIB_INSTALLTYPE_os_apply_config=package
export DIB_INSTALLTYPE_get_pip_py=package
export ELEMENTS_PATH=/usr/share/tripleo-image-elements:/usr/share/instack-undercloud
disk-image-create \
        --no-tmpfs \
        -a $NODE_ARCH \
        -o /mnt/overcloud-compute \
        $NODE_DIST pip-cache nova-compute nova-kvm neutron-openvswitch-agent os-collect-config \
        baremetal \
        dhcp-all-interfaces stackuser fedora-rdo-icehouse-repository \
        stable-interface-names</command>
</commands>
</template>

The following command will execute the target image build:

imagefactory --debug target_image --id [input_image_id] \
    --parameter utility_image [utility_image_id] \
    --file-parameter utility_customizations dib_overcloud_compute.tdl \
    --parameter results_location "/overcloud-computer.qcow2" indirection

Introducing Nova Plugin

2014-07-25T00:00:00+00:00

The imagefactory approach to image creation has always been to use the native installer for an OS to create an image that has “Just Enough OS”, customize that image by adding packages or running commands to create a base image, and then translating that base image into various formats compatible with a wide range of cloud/virtualization targets. These activities of creating the JEOS image, customizing, and converting are delegated out to plugins by imagefactory. While there have been a number of “cloud plugins” that allow imagefactory to work with numerous hypervisors and public clouds, there has only been one “OS plugin” and that is the TinMan plugin.

The name comes from the plugin’s dependency on the Oz project to create the JEOS image. Oz is a powerful tool that has been stable, fast, and offers support for a wide range of Linux distributions along with limited support for creating Microsoft Windows images. Oz has worked so well that TinMan has been the only OS plugin for imagefactory since the plugin API was added to imagefactory in early 2012.

While the Oz and TinMan have served us well, this combination has a couple of requirements the system running imagefactory must meet. Because Oz uses libvirt and and TinMan uses libguestfs, imagefactory has been limited to running on systems that support these libraries. It also means that the system running imagefactory needs a fair amount of memory and storage to run installers in virtual machines and to store the images created.

It’s true that imagefactory has the ability to talk to a remote imagefactory and have the remote instance do the heavy lifting. But we live in exciting times when projects like OpenStack have made it relatively easy to spin up our own clouds to pool together physical resources. With that available to us, why setup a system dedicated to building images? Using OpenStack directly allows us to break the tight dependency on libvirt and libguestfs and open up the possibility of running imagefactory on systems with fewer resources or systems that do not support those libraries. It also gives us a way to scale imagefactory for a higher number of concurrent builds by letting OpenStack manage the pool of physical resources.

Introducing the Nova plugin for imagefactory:

The Nova plugin was written to allow imagefactory to benefit from access to an OpenStack infrastructure. Now, imagefactory can spawn an instance on OpenStack to run the OS installer. Once the JEOS installation is completed, the customization and creation of the base image is also done within OpenStack. The resulting base image can be used to create other OpenStack instances or it can be passed to one of the imagefactory Cloud plugins to be used on a different cloud or hypervisor.

The Nova plugin is a drop in replacement for the TinMan plugin. It handles the same OS, version, architecture combinations. In order to use Nova instead of TinMan, you’ll want to remove the TinMan.info alias in /etc/imagefactory/plugins.d and make sure that Nova.info exists.

Once installed, using the Nova plugin is mostly the same as building images with the TinMan plugin with some additional arguments and setup related to connecting to OpenStack.

You’ll want to make sure that you have the common OpenStack environment variables set where you are running imagefactory. These are OS_AUTH_URL, OS_TENANT_NAME, OS_USERNAME, and OS_PASSWORD.

If instances in the OpenStack you are connecting to require the instance to request a floating IP address instead of automatically assigning one, you’ll want to pass the request_floating_ip option to imagefactory.

Similarly, if instances have a default non-root user, you need to tell imagefactory what that username is using the option default_user as well as how to run commands as a privileged user using the command_prefix option.

Finally, you need to choose what instance flavor to use for installation and customization steps. The flavor id can be passed to imagefactory with the flavor option.

Example:

So, let’s run through a quick example of building a base image using the Nova plugin. We’ll build a Fedora 19 for x86_64 using the following kickstart and TDL files.

We’ll use this kickstart file to setup the instance and specify the repository to use for installing over the network:

url --url=http://download.fedoraproject.org/pub/fedora/linux/releases/19/Fedora/x86_64/os
# Without the Everything repo, we cannot install cloud-init
repo --name="fedora-everything" --baseurl=http://download.fedoraproject.org/pub/fedora/linux/releases/19/Everything/x86_64/os/
install
text
keyboard us
lang en_US.UTF-8
skipx
network --device eth0 --bootproto dhcp
rootpw myrootpw
firewall --disabled
authconfig --enableshadow --enablemd5
selinux --enforcing
timezone --utc America/New_York
bootloader --location=mbr
zerombr
clearpart --all --drives=vda

part biosboot --fstype=biosboot --size=1 --ondisk=vda
part /boot --fstype ext4 --size=200 --ondisk=vda
part pv.2 --size=1 --grow --ondisk=vda
volgroup VolGroup00 --pesize=32768 pv.2
logvol swap --fstype swap --name=LogVol01 --vgname=VolGroup00 --size=768 --grow --maxsize=1536
logvol / --fstype ext4 --name=LogVol00 --vgname=VolGroup00 --size=1024 --grow
poweroff

bootloader --location=mbr --timeout=5 --append="rhgb quiet"

%packages
@core
cloud-init

%end

This simple TDL file just specifies what OS and version we’re building in order to select the correct OS plugin.

<template>
  <name>f19</name>
  <os>
    <name>Fedora</name>
    <version>19</version>
    <arch>x86_64</arch>
    <rootpw>test</rootpw>
    <install type='url'>
      <url>http://download.fedoraproject.org/pub/fedora/linux/releases/19/Fedora/x86_64/os</url>
    </install>
  </os>
  <disk>
    <size>20</size>
  </disk>
</template>

We’ll pass those two files to imagefactory using a command like this:

imagefactory base_image \
 --file-parameter install_script f19.ks \
 --parameter request_floating_ip True \
 --parameter default_user ec2-user \
 --parameter command_prefix sudo \
 --parameter flavor 2 f19.tdl

A number of steps are completed as an image is built:

First any images needed to boot into the installation are created or downloaded.
Once a bare bones installation is completed, the instance is shutdown and a snapshot is taken before terminating the instance.
A new instance is spawned from the snapshot and imagefactory installs any packages and/or runs any commands specified in the TDL by issuing commands via a series of ssh connections.
Once customization is complete, an ICICLE document is created that lists all of the packages installed before shutting down this second instance.
A snapshot is taken before terminating the instance.

Upon completion of these steps, imagefactory will report that the image has been created successfully and provide the UUID for reference. We can then pass this UUID when creating a target image for another cloud or hypervisor or we can use the final snapshot in OpenStack to spawn new instances.

Here is an example of the final output from imagefactory:

============ Final Image Details ============
UUID: bdd32b97-0e94-473a-b376-74d2da289a2c
Type: base_image
Image filename: /var/lib/imagefactory/storage/bdd32b97-0e94-473a-b376-74d2da289a2c.body
Image build completed SUCCESSFULLY!

Getting the plugin:

The Nova plugin will be packaged and released with the 1.1.6 release of imagefactory. To start using this plugin now, pull the master branch from the imagefactory repository on GitHub.

To see a demo of the plugin being installed and used, have a look at this video:

Introduction to the Nova plugin for Image Factory

Floss Weekly 231

2012-11-01T00:00:00+00:00

Ian and Steve met up with Aaron Newcomb and Dan Lynch yesterday to talk about imagefactory on FLOSS Weekly episode 231.

You can download the interview (audio and video) from the podcast website:
http://twit.tv/show/floss-weekly/231

or watch it on YouTube:
http://www.youtube.com/watch?v=H5z-tpYS0Ng

Our thanks to the whole FLOSS Weekly team for giving us a chance to talk about the project.

V2 Coming Soon

2012-10-31T00:00:00+00:00

We have been working hard to get a stable release of imagefactory 2.0 released. There is still a bit of revision to be done on documentation (particularly the REST api and examples there). Watch this space for news as we get closer to release. Until then, release candidate RPMs are ready for testing.