Translated by: Prabin Karanjit (e-ambition Inc.) Source: http://cloud.watch.impress.co.jp/docs/column/eucalyptus/20101008_397993.

html Part 2: Using Eucalyptus The previous article of this series dealt with the installation and configuration of Eucalyptus. In this article explains how to use it. Installing euca2ools euca2ools is a command-line client tool developed and distributed by Eucalyptus Systems. It is used for interacting with Eucalyptus and is developed to run on Linux operating system. Here, we show how to install euca2ools on the CLC/CC server. First, install all the dependency packages before installing the euca2ools.
{{{ #In case CLC/CC server is connected to Internet yum -y install swig rsync #In case CLC/CC server is not connected to Internet mkdir /media/CentOS mount /dev/cdrom /media/CentOS/ yum --disablerepo=\* --enablerepo=c5-media -y install swig rsync }}}

Go to the Eucalyptus downloads page url (http://open.eucalyptus.com/downloads) and download the euca2ools-1.2-centos-x86_64.tar.gz zip-file for CentOS from "Euca2ools 1.2 - RHEL / CentOS 5.4 x86_64" located at the bottom of the page.

Pic02-01: Downloading euca2ools from Eucalyptus site

Copy the downloaded file to the CLC/CC server, extract it, and set the extracted path as the current directory.
{{{ tar -xzf euca2ools-1.2-centos-x86_64.tar.gz cd euca2ools-1.2-centos-x86_64 }}}

Use the rpm command to install the necessary python package and euca2ools as shown below.
{{{ rpm -Uvh python25-2.5.1-bashton1.x86_64.rpm \ python25-libs-2.5.1-bashton1.x86_64.rpm \ euca2ools-1.2-1.x86_64.rpm }}}

This completes the installation procedures. Using euca2ools Before one can interact with Eucalyptus, cryptographic credentials for authentication are issued to the user by the Cloud Controller. The following commands are executed in the CLC/CC server to obtain and unbundle the credentials.
{{{ cd ~ euca_conf --get-credentials euca2-admin-x509.zip mkdir -p .euca/admin/keypairs cd .euca/admin/ unzip ../../euca2-admin-x509.zip source eucarc }}}

Run the following test command to confirm that a valid response is sent back from Eucalyptus.
{{{ euca-describe-availability-zones verbose AVAILABILITYZONE cluster0 192.168.100.1 AVAILABILITYZONE |- vm types free / max cpu ram disk AVAILABILITYZONE |- m1.small 0002 / 0002 1 128 2 AVAILABILITYZONE |- c1.medium 0002 / 0002 1 256 5 AVAILABILITYZONE |- m1.large 0001 / 0001 2 512 10 AVAILABILITYZONE |- m1.xlarge 0001 / 0001 2 1024 20 AVAILABILITYZONE |- c1.xlarge 0000 / 0000 4 2048 20 }}}

The euca-describe-availability-zones command provides information on the current available cluster. Eucalyptus Administrators can also view the detailed information on available resources per cluster by specifying the sub command verbose. VM Image Registration

Using Eucalyptus requires registration of VM Images. Although it is possible to create a machine image from scratch, we will use the VM images distributed by Eucalyptus Systems. Access the http://open.eucalyptus.com/wiki/EucalyptusUserImageCreatorGuide_v1.6 download euca-centos-5.3-x86_64.tar.gz URL and

Pic02-02: Downloading VM Image from Eucalyptus site Copy the downloaded file into the CLC/CC server, extract it, and set the extracted file path as the current directory.
{{{ tar -xzf euca-centos-5.3-x86_64.tar.gz cd euca-centos-5.3-x86_64 ls -l total 1026052 -rw-r--r-- 1 root root 1049624576 Apr 24 2009 centos.5-3.x86-64.img # Machine Image drwxr-xr-x 2 root root 4096 May 13 2009 kvm-kernel # kernel & ramdisk files for KVM drwxr-xr-x 2 root root 4096 May 13 2009 xen-kernel # kernel & ramdisk files for Xen }}}

Run the euca-bundle-image, euca-upload-bundle, and euca-register commands to register the VM image as follows.
{{{

# Registering a kernel image euca-bundle-image -i xen-kernel/vmlinuz-2.6.27.21-0.1-xen --kernel true Checking image

Tarring image Encrypting image Splitting image... Part: vmlinuz-2.6.27.21-0.1-xen.part.0 Generating manifest /tmp/vmlinuz-2.6.27.21-0.1-xen.manifest.xml # Using the manifest file generated above upload the files to Eucalyptus as follows euca-upload-bundle -b kernel.001 -m /tmp/vmlinuz-2.6.27.21-0.1-xen.manifest.xml Checking bucket: kernel.001 Creating bucket: kernel.001 Uploading manifest file Uploading part: vmlinuz-2.6.27.21-0.1-xen.part.0 Uploaded image as kernel.001/vmlinuz-2.6.27.21-0.1-xen.manifest.xml # manifest file referenced by uploaded image is registered as follows euca-register kernel.001/vmlinuz-2.6.27.21-0.1-xen.manifest.xml IMAGE eki-5E491255 # kernel ID for the registered kernel image. # Registering a ramdisk image # steps are similar to kernel registration euca-bundle-image -i xen-kernel/initrd-2.6.27.21-0.1-xen --ramdisk true euca-upload-bundle -b ramdisk.001 -m /tmp/initrd-2.6.27.21-0.1-xen.manifest.xml euca-register ramdisk.001/initrd-2.6.27.21-0.1-xen.manifest.xml IMAGE eri-596A123C # ramdisk ID for the registered ramdisk image # Registering a VM image( will take a longer time as compared to kernel or ramdisk) euca-bundle-image -i centos.5-3.x86-64.img --kernel eki-5E491255 --ramdisk eri-596A123C euca-upload-bundle -b machine.001 -m /tmp/centos.5-3.x86-64.img.manifest.xml euca-register machine.001/centos.5-3.x86-64.img.manifest.xml IMAGE emi-330411BE # Image ID for the registered VM image
}}}

The table below shows the key options for the euca-bundle-image, euca-upload-bundle, and eucaregister commands. [euca-bundle-image command key options] Option -i, --image Parameter ImageFile Description (required) path to the image file to be bundled.

--kernel

kernel ID true ramdisk ID true PATH

--ramdisk

-d, --destination

-r, --arch

x86_64 i386

In case of a VM image file, ID of the kernel to be associated with the bundled image can be specified. In case of a kernel Image file, a parameter value of true should be specified. In case of a VM image file, ID of the ramdisk to be associated with the bundled image can be specified. In case of a ramdisk image file, a parameter value of true should be specified. Directory path to store the bundled image. The default path is /tmp. Target Architecture of bundled image file.In case of 64bit OS VM image, a parameter value of x86_64 should be specified. On the other hand, in case of 32bit OS VM image, a parameter value of i386 should be specified. The default value is x86_64

[euca-upload-bundle command key options] Option Parameter Description

(required) The name of the bucket to upload. If the bucket -b, --bucket BucketName doesnt exist, a new bucket wi ll be created during the upload. (required) The manifest file that contains the -m, --manifest ManifestFile metadata of the bundled image should be specified. The directory path for the image file to be uploaded -d, --directory PATH should specified. Defaults to the manifest file directory.

[euca-register command key options] Option Parameter Description

(required) The path of the uploaded manifest and image file (None) ImageLocation to be registered. The path should be specified as bucket_name/manifest_file Moreover, registering the machine image will temporarily increase the server load since walrus needs to unbundle, decrypt, and uncompress the files. If a VM instance is started before these operations are completed, you might encounter unexpected bugs. Hence, we recommend that you wait a few minutes after executing the euca-register command before running an instance of the image. Creating general users As only administrators can register kernel and ramdisk images, so far we have stipulated a admin user carry out those operations. General users can perform other operations, and as such, we shall proceed from here by first creating a general user via the web management interface. Clicking on [Users] tab will display a list of users as shown below.

Pic02-03: Displaying user list Click on the [Add user] button, fill out the form displayed, and click [Add user] to create a user.

Pic02-04: Registering User

After creating the user, log out of the web management interface and log in again as the newly created user.

Pic02-05: Logging out of web management interface Once you have logged in, click on the [Download Credentials] button to obtain the euca2-userIDx509.zip zip-file.

Pic02-06: Downloading the user credentials for authentication Copy the downloaded euca2-userID-x509.zip to the CLC/CC server, and extract it as shown below.
{{{ cd ~ mkdir -p .euca/vtaro/keypairs

cd .euca/vtaro/ unzip ../../euca2-vtaro-x509.zip source eucarc }}}

Creating Keypairs Before starting a VM instance, it is necessary to create a key pair that allows you to log in to the VM instance using the SSH command. A command to create a key pair is shown below.
{{{ euca-add-keypair key01 > ~/.euca/vtaro/kaypairs/key01.pk chmod 400 ~/.euca/vtaro/kaypairs/key01.pk }}}

You can query the system to view created keypairs by using the euca-describe-keypairs command.
{{{ euca-describe-keypairs KEYPAIR key02 94:bc:94:92:b6:d3:7d:4d:2b:ba:d3:98:7f:5e:51:cc:6f:92:ec:56 KEYPAIR key01 25:d9:00:a8:09:8e:03:3a:7a:1b:95:37:50:86:eb:94:36:54:1c:b3 }}}

Configuring a Security group To allow one to log in to a VM instance using the SSH command, it is essential to configure a security group. By default, a security group that denies incoming traffic from all sources is provided to every user. Authorize network access to the default security group as follows.
{{{ euca-authorize -P tcp -p 22 -s 192.168.32.0/24 default GROUP default PERMISSION default ALLOWS tcp 22 22 FROM CIDR 192.168.32.0/24 }}}

The table below shows the key options for the euca-authorize command. [euca-authorize command key options] -P, --protocol tcp udp icmp (required) protocol for the security group rule added. (required if tcp or udp was specified for protocol option) port number for the security group rule added.Either a single port number or a range of ports written in from-to format (For eg: 137-139) can be specified. (required if icmp was specified for protocol option) ICMP type and code for the security group rule added.

-p, --port-range

PortNum from-to

-t, --icmp-type-code

type:code

-s, --source-subnet

Network/Subne t

-o, --source-group

SecurityGroup

-u, --source-group-user

UserID

(None)

SecurityGroup

(required if -o and -u options mentioned below is not used) specify the source network address and subnet authorized for network access. For Services such as web, that has no specific targeted users, 0.0.0.0/0 (refers to any source address) is generally specified. However, for services such as SSH connection, it is considered a bad idea to use 0.0.0.0/0 for security reasons. It is advisable to restrict access to a particular source network address. (required if -s option is not used) In order to allow access from another security group only, specify the corresponding security group. (required if -s option is not used) user id for the source group specified in the -o option. (required) name of the security group to add a rule to. The specified group name must already exist. In other cases, you must create one beforehand by using the euca-add-group.

VM Instance Control Now lets run an instance of VM image with id emi-330411BE that was registered in the Image Registration section above.
{{{ euca-run-instances -k key01 -t m1.small -n 1 emi-330411BE RESERVATION r-35CC06E6 vtaro vtaro-default INSTANCE i-410306FC emi-330411BE 0.0.0.0 0.0.0.0 24T13:46:41.218Z eki-5E491255 eri-596A123C }}}

pending

key01

2010-06-

Running a VM instance takes a few minutes, so the euca-describe-instances command is used to query the status of the instance. The transition of status from the pending to the running state denotes the instance is starting up on a hypervisor. However it will take a few seconds for the OS boot operation to complete.
{{{ euca-describe-instances RESERVATION r-35CC06E6 vtaro default INSTANCE i-410306FC emi-330411BE 192.168.32.200 10.1.2.2 pending key01 0 m1.small 2010-06-24T13:46:41.218Z cluster0 eki-5E491255 eri-596A123C }}}

The watch command can be very handy for monitoring the instance state transition as shown below.

{{{ watch -d euca-describe-instances }}}

Log into the instance using SSH as follows.

{{{ ssh -i ~/.euca/vtaro/keypairs/key01.pk -o StrictHostKeyChecking=no 192.168.32.200 }}}

To terminate the instance, run the euca-terminate-instances command, specifying the corresponding instance ID as follows.
{{{ euca-terminate-instances i-410306FC INSTANCE i-410306FC }}}

Similar to Amazon EC2, once the instance is terminated, all the changes made to that instance will be lost. If it is important to save the data, you should either use EBS volume or take a snapshot of the running instance by using the euca-bundle-vol command. We have briefly covered on how to use Eucalyptus. The next article explains how to use the eucabundle-vol and EBS volume.