Revision as of 08:02, 12 October 2010

What is IMG

IMG (Image Me Give) is a small python client/server application suite, its sole job is to get a POST'd kickstart file from a user and then run Moblin-Image-Creator. It is also possible to use kickstarter yaml files to create a tailor-made image or using the default selection of yaml templates.

Design

• Asynchronous

Fire and forget about it, check back later with the cli client for results

• Queue view with django,

Show a nice html view of currently running or standby MIC jobs in the queues

• Submit/cancel via .ks

Upload via a form

• No security

No https or file filter restrictions :)

Example workflow

The application consists of two parts, django frontend and the actual image creation application. Both of them are connected via AMQP, RabbitMQ is used as the server.

So an example workflow:

1. User posts an image creation request with email address and sample kickstart file (or yaml templates for kickstarter), using a form or the command line client.
2. Django application receives the request and imports the information on a model object and saves it.
3. When the object is saved, a message is sent via a broker to the image creation app, containing the details for the creation.
   1. Image creation commences
   2. Virtual machine disk image containing mic2 and kickstarter is engaged (as a kvm overlay image), with ssh access.
      1. When a yaml overlay is received, it is passed via kickstarter and then to worker
      2. When a kickstart file is received, it is passed directly to worker
   3. Worker starts up and connects to the virtual machine using ssh and passes the required arguments to mic2.
   4. Worker copies image on success from the virtual machine to well-known www-root, if there is an error, only a message about it is sent via AMQP.
   5. When mic2 has finished, the virtual machine is shut down by the worker.
   6. When image is created, the virtual machine disk image is deleted

Client

For demonstration see img_client.py for example client.

Usage

img_client.py -p|--poll <id> -n|--name <name> -t|--type <imagetype> -e|--email <author@email> -r|--release -a|--arch s|--submit -k <kickstart_file.ks>"

where:

-p|--poll <message_id>, poll the AMQP server for messages relating to the id, see -a|--async

-t|--type <imagetype>, image type, can be of: livecd, liveusb, loop, raw, nand, mrstnand, vdi or vmdk

-n|--name Image name

-a|--arch Image architecture

-r|--release Image release number

-c|--config Configuration file to use

BOSS Client

See boss_img_client.py for example BOSS client.

Usage

Usage: boss_client.py -n|--name <name> -t|--type <imagetype> -e|--email <author@email> -r|--release <release> -a|--arch <arch >-s|--submit -k <kickstart_file.ks>

boss_client.py Sends a message (poll for result later) to the BOSS, using
<kickstart.ks>  as the kickstart file.

Options:
 -h, --help            show this help message and exit
 -s, --submit          Submit to BOSS, takes no options
 -k KICKSTART, --kickstart=KICKSTART
                       Kickstart file
 -t TYPE, --type=TYPE  Image type
 -n NAME, --name=NAME  Image name
 -e EMAIL, --email=EMAIL
                       Author email
 -r RELEASE --release  Image release, goes directly to mic2
 -a ARCH --arch        Architecture to use

Django client

Views

• submit

If this view receives a POST request, it constructs a bound form with the data from POST array. If the form is valid it extracts the data, as specified in the forms section.

Applying the overlay is handled in this form, in the following way.

• Get the overlay text from the form field
• use python strings split() method to split the overlay text in to a list, with a comma delimiter
• parse the template configurations.yaml
  • append the overlay list to the platform selected via the form, to the !ExtraPackages element

After the overlay is applied, the resulting YAML template is passed to the kickstarter via a AMQP message.

• queue

This view is responsible of two things. Firstly it checks wether there are any messages in the "status_queue" message queue, if there are, then it updates the !ImageJob model object (identified by the identification string from the message) to include the ready image URL.

Secondly, it checks for possible error messages in "status_queue" queue, if there are any, it assigns a special variable to indicate that there has been an error.

If no messages are received, it simply redirects to a template with all the !ImageJob model objects.

• job

Job view is responsible of providing the information about the log file. The information about the logfile is formed in the server side, such as the URL to the log file. If there is a URL, it will open the URL and read its contents and return the resulting text to the template. The template renders the log message with a textarea html widget.

• index

Index only returns a template in which one can click a link about uploading the image.

URLs

   url(r'submit/$', 'meego_img.app.views.submit', name='img-app-submit'), 
   url(r'queue/$', 'meego_img.app.views.queue', name='img-app-queue'),    
   url(r'job/(?P<msgid>\S+)$', 'meego_img.app.views.job', name='img-app-job'),       
   url(r'images/(?P<msgid>\S+)$', 'meego_img.app.views.download',name='img-app-download'),

Models

IMG currently has only one model, !ImageJob, here is the Django code for it:

# Create your models here.
class ImageJob(models.Model):    
   email = models.CharField(max_length=40)
   filename = models.CharField(max_length=40)
   logfile = models.CharField(max_length=50)
   task_id = models.CharField(max_length=30)
   imagefile = models.CharField(max_length=50)    
   created = models.DateTimeField(auto_now_add=True)
   error = models.CharField(max_length=500)
   type = models.CharField(max_length=10)
   status = models.CharField(max_length=30)
   def delete(self, *args, **kwargs): 
       if self.logfile:
           if os.path.exists(self.logfile):
               os.remove(self.logfile)
               os.remove(self.logfile.replace("-log", ""))
               print "Removed %s"%self.logfile
       super(ImageJob, self).delete(*args, **kwargs)

As can be seen in the delete method, this model cleans up all image creation related files, like the kickstarter file and log file.

Forms

 !UploadFileForm

Contains the following fields

• email, email field
• overlay, text input field
• platform, select field for the platform, parsed from the default template
• imagetype, select field for the image type, with values: livecd, liveusb, loop, raw, nand, mrstnand, vdi, vmdk
• ksfile, the raw kickstart file

Server

See build_image.py for example server.

This section documents the server component of IMG.

Worker configuration

The configuration file is to be installed in /etc/imger/img.conf and a sample file is here.

Configuration file

base_url: A base URL that has a direct access to the base_dir via HTTP, example http://127.0.0.1
base_dir: A directory to put the finished images, example /var/www/images
num_workers: Number of workers to start, OBSOLETE, USE INITSCRIPT OR MANUALLY RUN MANY PARTICIPANTS
post_creation: Path to a script to run after the image is created
use_kvm: Wether to use a virtual machine, values are "yes" or "no"

mic_opts: Example, mic_opts = --save-kernel, --use_comps, so comma separated options

amqp_host: Host that runs BOSS
amqp_user: Username to tap into the BOSS virtual host
amqp_pwd: Password
amqp_vhost: The actual virtual host to connect to

Virtual machine

Currently, IMGer can run the MIC2 jobs inside a KVM virtual machine, the only prerequisites are that image is located in /usr/share/img/base.img (configurable in the future) path and that the virtual machine has MIC2 installed and configured.

One must also confirm that the image SSH-keys in the source distribution are configured in the virtual machine and both keys exist in /usr/share/img (configurable in the future)

BOSS Workitem definition

Input

The following defines the input dictionary for the participant:

"kickstart" : a kickstart file, in raw, not a path
"email": email address, not parsed so can be a dummy address
"id": a simple UUID, eg. from pythons uuid library
"type":type, from values: livecd, liveusb, loop, raw, nand, mrstnand, vdi or vmdk
"name":name, a simple string for the image name

Output

The work item can contain the following dictionary entries:

Status: Status, is either "DONE" or "ERROR" in the final workitem, depending on success/failure
URL: URL to a image/log/kickstart file location on the worker
Error: An error string with details of the error, if any
Image: A direct URL to the finished image
Log: A direct URL to the log file of the mic2 output