On FutureGrid, how can I save an active Eucalyptus VM?

If you are starting an image in Eucalyptus, modifying the software contained in the image, upgrading the software, installing security patches, or performing maintenance, you might need to save the new system state.

These instructions are for CentOS 5 and 6 (tested with 5.7 and 6.2) while working in the FutureGrid context. This document is based on information from Jens Vöckler and the Eucalyptus community forum at Eucalyptus Engage. These instructions assume that you are familiar with Eucalyptus, and have worked through the Eucalyptus tutorial if you are a FutureGrid user, to familiarize yourself with the nomenclature.

When you list the available images on your Eucalyptus cluster, it shows a number of columns, for example:

• IMAGE: A fixed string.
  
  
• exi-XXXXXXX: This is the image handle. You need the handle when attempting to start a virtual machine. The first part is either emi for virtual machine image, eki for kernel images, or eri for ramdisk images. This is a reflection of Amazon's naming convention of ami, aki and ari.
  
  
• bucketname/bundlename: This column contains a compound name that uniquely identifies an image for the human user. The part before the slash is called the bucket. A bucket may contain one or more bundles. The name of the bundle is the part after the slash.
  
  
• owner: This column shows the account name of the image creator.
  
  
• available
  
  
• public or private: Typically, images that you save according to the instructions below are public.
  
  
• arch: This column denotes the architecture of the image.
  
  
• machine or kernel or ramdisk: For the VM you are about to save, it will be machine.
  
  
• eki-XXXXXXXX: For VM images, this column denotes the kernel image used to start it. It is empty for kernel and ramdisk images themselves.
  
  
• eri-XXXXXXXX: For VM images, this column denotes the ramdisk image used to start it. It is empty for kernel and ramdisk images themselves.

Note: The distinction between buckets and bundles is important.

The code fragments that follow will show part of the command prompt. The various prompt shapes show you whether a command is executed on a desktop (dt) or remote virtual machine (vm), and whether it is as regular user ($) or as root (#).

1. When going into maintenance mode, it is important to start the image on an instance type that is large enough to contain the saved image file. Please refer to your vendor's manual what instance type best fits. For FutureGrid, it is recommended that you use at least m1.large, or preferably m1.xlarge.
   
   

   dt $ euca-run-instances ... -t m1.xlarge ...

   
   
2. Carefully note down the kernel number eki-XXXXXXXX and ramdisk number eri-XXXXXXXX associated with the image; you will need that later when saving the image.
   
   

   dt $ euca-describe-instances RESERVATION r-4AC808BF username default INSTANCE i-4A390892 emi-73D90EDC publicip privateip running userkey 0 m1.small 2012-02-09T15:55:46.771Z indiafg eki-78EF12D2 eri-5BB61255 INSTANCE i-34B706F0 emi-73D90EDC publicip privateip running userkey 1 m1.small 2012-02-09T15:55:46.772Z indiafg eki-78EF12D2 eri-5BB61255

   The numbers are found in the last two columns. Please make sure that you are writing down the right numbers for your active image, in case you have multiple images running.

3. Once the instance is running, you need to copy your credentials to the instance. This is the euca2-xxxxxxx-x509.zip file that was provided by your cloud vendor.
   
   

   dt $ scp -i /path/to/privkey /path/to/zip root@xxx.xxx.xxx.xxx:/mnt

   In FutureGrid, the extra disk space is mounted under the /mnt directory. This is where you will create the image. You do not want to copy your credentials onto the root file system, because that may save them into the bundle you are going to create.

4. Connect to the remote machine:
   
   

   dt $ ssh -i /path/to/privkey root@xxx.xxx.xxx.xxx

   At this point, do what you need to the remote image, e.g., upgrading, installing software, etc.

5. If the euca2ools were not already installed, install them. They are already installed on Jens's VMs on FutureGrid.
   
   
6. Carefully read the steps in Creating a movable CentOS virtual machine about removing, and modifying, files that will interfere with the networking on the virtual machine. It is probably not necessary to erase the free image disk space before bundling because of the way euca2ools bundles images.
   
   
7. Once you are ready to capture the active instance, change into the /mnt directory:
   
   

   vm # cd /mnt

   
   
8. Unzip your credentials and source the rc file. This will set up the proper environment. This step assumes that you have the unzip package installed on your VM (true for Jens's VMs).
   
   

   vm # unzip euca2-*-x509.zip vm # . eucarc

   
   
9. Bundle the image volume. (This is the step that differs from the original instructions.)
   
   

   vm # euca-bundle-vol -c ${EC2_CERT} -k ${EC2_PRIVATE_KEY} -u ${EC2_USER_ID} --ec2cert ${EUCALYPTUS_CERT} --no-inherit --kernel eki-XXXXXXXX --ramdisk eri-XXXXXXXX -d /mnt -r x86_64 -p bundlename -s targetsize

   The parameters need an explanation:

   --kernel eki-XXXXXXXX

   The kernel image number you wrote down previously.

   --ramdisk eri-XXXXXXXX

   The ramdisk image number you wrote down previously.

   -d /mnt

   This names the location where to create the bundle files. For all practical purposes, this will always be in the /mnt partition.

   -r arch

   This names the architecture. Obviously, you need to use the same architecture as the image you started. These days, the architecture is typically x86_64.

   -p bundlename

   This is the name you chose for you image bundle. The term bundle refers to what was shown on top. Use something descriptive; it also helps to mention the architecture in the bundle's name. Note that you do not provide a bucket name in this step.

   -s targetsize

   This is the size of the root (/) partition of the new image. If you need to grow your disk space, this is a good way to do it. However, consider that your /mnt partition must be large enough to fit at least 20% more than the target image size.

   The last line of output from a successful bundling of a volume is a manifest file, which you will need in the next step.

10. Upload the bundle into a bucket. If this is a new bucket that does not exist yet, it will be created. Default FutureGrid users can only create two buckets, but you can request an extension.
    
    

    vm # euca-upload-bundle -b bucketname -m /mnt/bundlename.manifest.xml

    
    

    -b bucketname

    This is the name of the bucket into which you want to put the image bundle. If the bucket already exists, you add the image. If the bucket does not exist, it will be created first. It is not recommended to "overwrite" an existing bundle in an existing bucket.

    -m /mnt/bundlename.manifest.xml

    The final line of the image bundling step before prints out the full path to the bundle's manifest file. You insert that path after the argument. Effectively, it is the bundlename with a suffix.

    Note that image management is much simpler, if each image bundle has its own bucket. It is difficult to properly remove a single image bundle from a bucket without affecting the other bundles in the same bucket.

    The last line of output from a successful upload will print the registration filename that you will need in the next step.

11. Register the newly created bundle with Eucalyptus. It will not be accessible until you have registered it.
    
    

    vm # euca-register bucketname/bundlename.manifest.xml

    The bucketname is the bucket you named in the previous step, and the bundlename is that in the previous step. Effectively, the argument to euca-register is the output of a successful upload.

    The output of a successful run of this step is the image handle emi-XXXXXXX you can use to start a new instance of the image.

It is typically a good idea to start the newly saved image immediately while the original one is still running. Reaching image state running for the new image is necessary but not sufficient to determine a succcessful image bundling. You need to check that you can actually connect to it.

If the new image is not responsive, you still have the original one running. Sometimes there are transient errors, and after cleaning up /mnt, you can try to remove the broken image and rebundle it.

Removing an image bundle

1. Determine the image bucket- and bundlename, and image handle:
   
   

   dt $ euca-describe-images

   
   
2. Deregister the image from the Eucalyptus store:
   
   

   dt $ euca-deregister emi-XXXXXXXX

   Warning: After you deregister an image, it will no longer show up in euca-describe-images listings.

3. Remove the image bundle from its bucket. For this step to work, you either need to know the image bundlename, or have its manifest file, unless you want to remove all images in the given bucket.
   
   

   $ euca-delete-bundle -b bucketname -p bundlename

   This alternative removes an image by its given bundlename. This should be a unique prefix within the bucket.

   $ euca-delete-bundle -b bucketname -m bundlename.manifest.xml

   This alternative removes an image given a manifest file. This alternative is helpful if the image bundle is a prefix of another image bundle inside the same bucket. Typically, the manifest file is most easily available during image creation, or when downloading a whole bucket.

   $ euca-delete-bundle -b bucketname --clear

   This alternative is useful if you need to remove all image bundles, regardless of name, that reside in the given bucket, and when you need to remove the bucket itself. If this is more than a single image, make sure that you have deregistered all images separately beforehand. This step will remove the bucket.

References

• Image Management
• Eucalyptus. 5: Creating and running VMs

This document is based upon work supported in part by National Science Foundation (NSF) grant 0910812 to Indiana University for "FutureGrid: An Experimental, High-Performance Grid Test-bed." FutureGrid project partners include the University of California - San Diego and the San Diego Supercomputer Center (SDSC), the University of Chicago/Argonne National Labs, the University of Florida, Purdue University, the University of Southern California, the University of Texas - Austin, and the Center for Information Services and High Performance Computing at Technische Universität Dresden.