Bundling an AMI

Amazon Elastic Compute Cloud: 2008-05-05

previous page next page

Bundling an AMI

To use a file system image with Amazon EC2, you must bundle it as an AMI. The bundling process does the following:

  • Compresses the image to minimize bandwidth usage and storage requirements

  • Encrypts and signs the compressed image to ensure confidentiality and authenticates the image against its creator

  • Splits the encrypted image into manageable parts for upload

  • Creates a manifest file that contains a list of the image parts with their checksums

This section describes the AMI tools that automate this process and provides examples of their use

The AMI tools include three command-line utilities:

  • ec2-bundle-image bundles an existing AMI

  • ec2-bundle-vol creates an AMI from an existing machine or installed volume

  • ec2-upload-bundle uploads a bundled AMI to Amazon S3 storage

Installing the AMI Tools

The AMI tools are packaged as an RPM suitable for running on Fedora Core with Ruby 1.8.2 (or greater) installed. You need root privileges to install the software.

The AMI tools RPM is available from our public Amazon S3 downloads bucket.

To install the AMI tools

  1. Install Ruby using the yum package manager.

    # yum install ruby

  2. Install the AMI tools RPM.

    # rpm -i ec2-ami-tools-x.x-xxxx.i386.rpm

Installation Issues

The AMI tools libraries install in /usr/lib/site_ruby.

If you receive a load error when running one of the AMI utilities, Ruby might not have found the path. To fix this, add /usr/lib/site_ruby to Ruby's library path, which is set in the RUBYLIB environment variable.

Viewing Documentation

To view the manual for each utility

  • Append --manual to the command that invokes the utility.

                  # 
              
                ec2-bundle-image --manual

To view help for each utility

  • Append --help to the command that invokes the utility.

    # ec2-bundle-image --help

Bundling an AMI Using the AMI Tools

After creating a machine image, it must be bundled as an AMI for use with Amazon EC2. How you bundle the image depends on how you created the image (for information about creating AMIs, see Creating an AMI).

To bundle the loopback file image

  • Enter the following command:

    # ec2-bundle-image -i <image_name>.img -k <private_keyfile> -c <certificate_file> -u <user_id>

    The <image_name> is the name of the image file, <private_keyfile> is the file that contains the private key, <certificate_file> is the file that contains the certificate, and <user_id> is the user ID associated with your account.

    [Note] Note

    The user ID is your AWS account ID without dashes. It is the same as your Amazon Access ID and consists of 12 digits.

To bundle a snapshot image (requires root privileges)

  • Enter the following command:

    # ec2-bundle-vol -k <private_keyfile> -c <certificate_file> -u <user_id>

    The <private_keyfile> is the file that contains the private key, <certificate_file> is the file that contains the certificate, and <user_id> is the user ID associated with your account.

    [Note] Note

    Make sure to disable SELinux when running ec2-bundle-vol.

    [Note] Note

    The user ID is your AWS account ID without dashes. It is the same as your Amazon Access ID and consists of 12 digits.

Example

This command bundles an image created in a loopback file.

# ec2-bundle-image -i my-image.fs -k pk-HKZYKTAIG2ECMXYIBH3HXV4ZBZQ55CLO.pem -c cert-HKZYKTAIG2ECMXYIBH3HXV4ZBZQ55CLO.pem -u 495219933132 
image.part.00
image.part.01
...
image.part.NN
image.manifest.xml

This command bundles the local machine root file system.

# ec2-bundle-vol -k pk-HKZYKTAIG2ECMXYIBH3HXV4ZBZQ55CLO.pem -c cert-HKZYKTAIG2ECMXYIBH3HXV4ZBZQ55CLO.pem -u 495219933132
image.part.00
image.part.01
...
image.part.NN
image.manifest.xml

Uploading a Bundled AMI

You must upload the bundled AMI to Amazon S3 before it can be accessed by Amazon EC2. Use ec2-upload-bundle to upload the bundled AMI that you created earlier. Amazon S3 stores data objects in buckets, which are similar to directories.

Buckets must have globally unique names. The ec2-upload-bundle utility uploads the bundled AMI to a specified bucket. If the specified bucket does not exist, it will be created. If the specified bucket exists and belongs to another user, the ec2-upload-bundle command will fail.

To upload the bundled AMI

  • Enter the following command:

    # ec2-upload-bundle -b <bucket> -m image.manifest.xml -a <access_key> -s <secret_key>

    The <bucket> is the target bucket, <access_key> is your AWS Access Key, and <secret_key> is your AWS Secret Key.

    The AMI manifest file and all image parts are uploaded to Amazon S3. The manifest file is encrypted with the Amazon EC2 public key before being uploaded.

previous page start next page