documentation.help

Bundling a Linux or UNIX AMI

From Amazon Elastic Compute Cloud: 2009-04-04

previous page next page

Bundling a Linux or UNIX AMI

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

How to Install the AMI Tools

The AMI tools are available in both a zip file and 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. For information about installing tools, refer to their provided documentation.

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.

How to View Documentation

This section describes how to view Linux/UNIX 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

How to Bundle 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 AIDADH4IGTRXXKCD 
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 AIDADH4IGTRXXKCD
image.part.00
image.part.01
...
image.part.NN
image.manifest.xml

How to Upload 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.

How to Register the AMI

Your must register your image with Amazon EC2, so we can locate it and run instances based on it.

[Note] Note

If you make any changes to the source image stored in Amazon S3, you must re-register the image.

To register the AMI that you created and uploaded to Amazon S3

  • Execute the following command:

    PROMPT> ec2-register <your-s3-bucket>/sampleimage.manifest.xml
IMAGE ami-2bb65342

    Amazon EC2 returns an AMI identifier, the value next to the IMAGE tag (ami-2bb65342 in the example) that you can use to run instances.

previous page start next page