Managing Eucalyptus Images (1.4)

First, be sure to source your 'eucarc' file before running the commands below. Note that all users may upload and register images (depending on access granted to them by the Eucalyptus administrator), but only the admin user may ever upload/register kernels or ramdisks.

The latest version of EC2 API and AMI tools that we support are ec2-api-tools-1.3-30349 and ec2-ami-tools-1.3-26357. Download BOTH before proceeding, if you have not done so already.

1. Adding Images ¶

To enable a VM image as an executable entity, a user/admin must add a root disk image, a kernel and optionally, a ramdisk for the kernel to Walrus and register the uploaded data with Eucalyptus. Each is added to Walrus and registered with Eucalyptus separately, using three EC2 commands. The following example uses the test image that we provide. Unpack it to any directory:

cd $EUCALYPTUS_SRC/eucalyptus-src-deps
tar zxvf euca-ttylinux.tgz

Add the kernel to Walrus, and register it with Eucalyptus (WARNING: your bucket names must not end with a slash! In addition, you cannot upload an image to a bucket that already exists using ec2-upload-bundle. You need to create a new bucket for each image, or delete the existing bucket):

ec2-bundle-image -i ttylinux/vmlinuz-2.6.16.33-xen --kernel true
ec2-upload-bundle -b kernel-bucket -m /tmp/vmlinuz-2.6.16.33-xen.manifest.xml
ec2-register kernel-bucket/vmlinuz-2.6.16.33-xen.manifest.xml

You might see a warning about trying to use a different EC2 public certificate. Enter 'y' and proceed.

Next, add the root filesystem image to Walrus:

ec2-bundle-image -i ttylinux/ttylinux.img 
ec2-upload-bundle -b image-bucket -m /tmp/ttylinux.img.manifest.xml
ec2-register image-bucket/ttylinux.img.manifest.xml

Our test kernel does not require a ramdisk to boot. If the administrator would like to upload/register a kernel/ramdisk pair, the procedure is similar to the above:

ec2-bundle-image -i <path/to/my/>initrd.img --ramdisk true
ec2-upload-bundle -b <bucket_name> -m <path/to/my/>initrd.img.manifest.xml
ec2-register <bucket_name>/initrd.img.manifest.xml

2. Associating kernels and ramdisks with instances ¶

There are three ways that one can associate a kernel (and ramdisk) with a VM instance.

A user may associate a specific kernel/ramdisk identifier with an image at the 'ec2-bundle-image' step
```
ec2-bundle-image -i <path/to/my/>vmimage.img --kernel <eki-XXXXXXXX> --ramdisk <eri-XXXXXXXX>
```
A user may choose a specific kernel/ramdisk at instance run time as an option to 'ec2-run-instances'
```
ec2-run-instances <emi-XXXXXXXX> --kernel <eki-XXXXXXXX> --ramdisk <eri-XXXXXXXX>
```
The administrator can set 'default' registered kernel/ramdisk identifiers that will be used if a kernel/ramdisk is unspecified by either of the above options. This is accomplished by logging in to the administrative interface (https://your.cloud.server:8443), clicking on the 'Configuration' tab and adding an <eki-xxxxxxxx> and optionally an <eri-xxxxxxxx> as the defaults kernel/ramdisk to be used.

3. Deleting Images ¶

In order to delete an image, you must first de-register the image:

ec2-deregister <emi-XXXXXXXX>

Then, you can remove the files stored in your bucket. Assuming you have sourced your 'eucarc' to set up EC2 client tools:

ec2-delete-bundle -a $EC2_ACCESS_KEY -s $EC2_SECRET_KEY --url $S3_URL -b <bucket> -p <file prefix>

If you would like to remove the image and the bucket, add the '--clear' option:

ec2-delete-bundle -a $EC2_ACCESS_KEY -s $EC2_SECRET_KEY --url $S3_URL -b <bucket> -p <file prefix> --clear