Image Management

In order to use run instances from images that you have created (or downloaded), you need to bundle the images with your cloud credentials, upload them and register them with the cloud. Following examples show how you would perform the necessary steps.

Bundling images

"euca-bundle-image" can be used to bundle an image for use with Eucalyptus or Amazon. A bundled image consists of a manifest file and several image parts.

For instance, to bundle an image "image.img" for user id "123456789111" in the directory "image-dir"

euca-bundle-image -i image.img -u 12345678111 -d image-dir

OR, if you wish to specify credentials separately ("cert-xyz.pem" and "pk-xyz.pem" are the user certificate and private key PEM files, respectively).

euca-bundle-image -i image.img -u 123456789111 -d image-dir -c cert-xyz.pem -k pk-xyz.pem

To bundle an image for use with Amazon, make sure you locate the Amazon ec2 cert file that is provided as part of the EC2 AMI tools. This file is generally located in $EC2_AMITOOL_HOME/etc/ec2/amitools/cert-ec2.pem

euca-bundle-image -i image.img -u 123456789111 -d image-dir -c cert-abc.pem -k pk-abc.pem --ec2cert $EC2_AMITOOL_HOME/etc/ec2/amitools/cert-ec2.pem

Make sure that the "cert-abc.pem" and "pk-abc.pem" files in the above example are your Amazon credentials (not your Eucalyptus credentials).

For more options, type,

euca-bundle-image --help

or refer to the manpage for "euca-bundle-image."

Uploading an image

To upload an image bundled with "euca-bundle-image" you can use "euca-upload-bundle."

For example, to upload the bundle corresponding to the manifest "image.img.manifest.xml" to the bucket "image-bucket," you would run the following command,

euca-upload-bundle -b image-bucket -m image.img.manifest.xml

For more options, type

euca-upload-bundle --help

or refer to the manpage for "euca-upload-bundle."

Registering an image

Bundle images that have been uploaded to the cloud need to be registered with the cloud prior to running instances.

For instance, to register a bundled image referenced by the manifest file "image.img.manifest.xml" that has been uploaded to the bucket "image-bucket" type the following command,

euca-register image-bucket/image.img.manifest.xml

For more options, refer to the manpage for "euca-register" or type,

euca-register --help

Downloading an image

Bundled images that have been uploaded may also be downloaded or deleted from the cloud.

For instance, to download the image(s) that have been uploaded to the bucket "image-bucket" you may use the following command,

euca-download-bundle -b image-bucket

For more options, type,

euca-download-bundle --help

Deleting a bundled image

To delete a bundled image, use "euca-delete-bundle."

For instance, to delete the images in bucket "image-bucket" you can use the following command,

euca-delete-bundle -b image-bucket

You can specify a manifest using the "-m" or "--manifest" argument if you wish to delete a specific bundle.

To delete the bucket after deleting the bundled image,

euca-delete-bundle -b image-bucket --clear

A bucket can only be deleted when it is empty.

For more options, type,

euca-delete-bundle --help

Unbundling an image

To unbundle a previously bundled image, use "euca-unbundle"

For instance, to unbundle the bundled image referenced by the manifest "image.img.manifest.xml" to the directory image-dir, use the following command,

euca-unbundle -m image.img.manifest.xml -d image-dir

For more options, try,

euca-unbundle --help

VM Control

A cloud will let users control virtual machine (VM) instances using uploaded images as a template. The following commands can be used to control VM instances.

Displaying instances currently running

You may use "euca-describe-instances," which will display a list of currently running instances.

euca-describe-instances

To get information about a specific instance, you can use the instance id as an argument to euca-describe-instances. For example,

euca-describe-instances i-43035890

For more options, type,

euca-describe-instances --help

Running instances

"euca-run-instances" will allow you to deploy VM instances of images that have been previously uploaded to the cloud.

For instance, to run an instance of the image with id "emi-53444344" with the kernel "eki-34323333" the ramdisk "eri-33344234" and the keypair "testkey" you can use the following command,

euca-run-instances -k testkey --kernel eki-34323333 --ramdisk eri-33344234 emi-53444344

To run more than one instances, you may use the "-n" or "--instance-count" option.

For more help, try,

euca-run-instances --help

or refer to the manpage for "euca-run-instances."

Shutting down instances

You may shutdown running instances using the "euca-terminate-instances" command. For example, to terminate an instance "i-34523332"

euca-terminate-instance i-34523332

For more options, type,

euca-terminate-instances --help

or refer to the manpage.

Rebooting instances

To reboot running instances, you can use "euca-reboot-instances." For example, to reboot the instance "i-34523332"

euca-reboot-instances i-34523332

A reboot will preserve the root filesystem for the instance across restarts.

Networking and Security

You can assign IP address to instances dynamically, unassign addresses, create security groups and assign networking rules to security groups.

Allocating and associating IP addresses

You may use "euca-allocate-address" and "euca-associate-address" to allocate IP addresses and associate public IP addresses with instances, respectively.

In the following example, we will allocate an IP address and associate it with the instance "i-56785678".

euca-allocate-address
ADDRESS    a.b.c.d

euca-associate-address -i i-56785678 a.b.c.d

Disassociating and Releasing addresses

You may use "euca-disassociate-address" and "euca-release-address" to disassociate an IP address from an instance and to release the IP address to the global pool. For instance, to release and disassociate the address "a.b.c.d."

euca-disassociate-address a.b.c.d

euca-release-address a.b.c.d

Creating a security group

You can create a security group using the "euca-add-group" command. For instance, to create a group named "mygroup," you may use the following command,

euca-add-group -d "mygroup description" mygroup

Security groups may be specified when running instances with "euca-run-instances" using the "-g" parameter.

Adding networking rules to security groups

By default, a security group denies incoming network traffic from all sources. You may add networking related rules to security groups using the command "euca-authorize."

To see the entire list of options, type,

euca-authorize --help

For example, to allow incoming ssh (port 22) traffic to the security group "mygroup" you may use the following command, which specifies a protocol (tcp) a port (22) and a CIDR source network (0.0.0.0/0, which refers to any source):

euca-authorize -P tcp -p 22 -s 0.0.0.0/0 mygroup

Instead of specifying a CIDR source, you may instead specify another security group to allow access from:

euca-authorize --source-group someothergroup --source-group-user someotheruser -P tcp -p 22 mygroup

Revoking networking rules from security groups

Revocation works the same way as addition (i.e. the command takes the same parameters), except that you should use the "euca-revoke"

euca-revoke -P tcp -p 22 -s 0.0.0.0/0 mygroup

euca-revoke --help

will list all options.

Deleting a security group

You may use "euca-delete-group" to delete a security group. For example,

euca-delete-group mygroup

will delete the security group "mygroup."

Using Block Storage

You can create dynamic block volumes, attach volumes to instances, detach volumes, deletes volumes, create snapshots from volumes and create volumes from snapshots with your cloud. Volumes are raw block devices. You can create a filesystem on top of an attached volume and mount the volume inside a VM instance as a block device. You can also create instantaneous snapshots from volumes and create volumes from snapshots.

Creating a volume

To create a dynamic block volume, use "euca-create-volume."

For instance, to create a volume that is 1GB in size in the availability zone "myzone" you may use the following command,

euca-create-volume --size 1 -z myzone

To list availability zones, you may use "euca-describe-availability-zones"

You may also create a volume from an existing snapshot. For example, to create a volume from the snapshot "snap-33453345" in the zone "myzone" try the following command,

euca-create-volume --snapshot snap-33453345 -z myzone

For more options, type,

euca-create-volume --help

Attaching a volume to an instance

You may attach block volumes to instances using "euca-attach-volume." You will need to specify the local block device name (this will be used inside the instance) and the instance identified. For instamce, to attach a volume "vol-33534456" to the instance "i-99838888" at "/dev/sdb" use the following command,

euca-attach-volume -i i-99838888 -d /dev/sdb vol-33534456

You can attach a volume to only one instance at a given time.

Detaching a volume

To detach a previously attached volume, use "euca-detach-volume." For example, to detach the volume "vol-33534456"

euca-detach-volume vol-33534456

You must detach a volume before terminating an instance or deleting a volume. If you fail to detach a volume, it may leave the volume in an inconsistent state and you risk losing data.

Delete a volume

To delete a volume, use "euca-delete-volume." For example, to delete the volume "vol-33534456" use the following command

euca-delete-volume vol-33534456

You may only delete volumes that are not currently attached to instances.

Creating a snapshot

You may create an instantaneous snapshot of a volume. A volume could be attached and in use during a snapshot operation. For example, to create a snapshot of the volume "vol-33534456" use the following command

euca-create-snapshot vol-33534456

Deleting a snapshot

To delete a snapshot, use "euca-delete-snapshot." For example, to delete the snapshot snap-33453345, use the following command,

euca-delete-snapshot snap-33453345