Eucalyptus: User Guide
Eucalyptus User's Guide (1.5.2)
This guide is meant for people interested in using an existing installation of Eucalyptus. (If you have a cluster that you would like to install Eucalyptus on, then take a look at the Administrator's Guide first.) Getting Started Using Eucalyptus (1.5.2)
These instructions will walk you through the essential steps for using a Eucalyptus-based cloud. Those who have worked with Amazon's EC2 system will find most of these instructions familiar (in fact, you may continue using Amazon's command-line tools with Eucalyptus). 1. Install command-line tools ¶
The instructions below rely on the euca2ools command-line tools distributed by the Eucalyptus Team. Please, install them if you haven't done so already. 2. Sign up ¶ If you are using the Eucalyptus Public Cloud, use mayhem9.cs.ucsb.edu instead of your.cloud.server.
Load in your browser the Web page of the Eucalyptus cloud installation that you would like to use. Ask your system administrator for the URL if you don't know it. (The URL will be of the form https://your.cloud.server:8443/, where your.cloud.server is likely to be the front-end of the cluster.)
login.png
Click the "Apply" link and fill out the form presented to you. You may not be able to use the system until the (human) administrator receives the notification of your application and approves it. The more information you supply the easier it may be for the administrator to make the decision.
signup.png
Load the confirmation URL that you receive in the approval email message from the cloud administrator. Log in to the system with the login and password that you chose when filling out the application form.
confirm_link.png 3. Obtain Credentials ¶
Once you have logged in, you will see the 'Generate Certificate' button under the 'Credentials' tab. Generating a certificate for your account is necessary before you can use Amazon's EC2 command-line tools for querying and controlling Eucalyptus instances. Currently, the Web interface to Eucalyptus is limited and, hence, the use of command-line tools is practically inevitable.
credentials1.4.png
Click the button to generate the certificate and save it. You can keep these keys in a secure place on any host. The following command-line instructions apply to any Unix-flavored machine with bash (not necessarily the cluster where Eucalyptus was installed). (See Amazon's Getting Started Guide for the similar instructions to use under Windows.)
Unzip the keys using the following command and protect them from exposure. The zip-file contains two files with the .pem extension; these are your public and private keys.
mkdir ~/.euca cd ~/.euca unzip name-of-the-key-zip.zip chmod 0700 ~/.euca chmod 0600 ~/.euca/*
Finally, ensure that the environment variables necessary for euca2tools to work are set by sourcing the eucarc file:
. ~/.euca/euca2-*/eucarc
4. Quick Start ¶
Now you can begin running VM instances on the Eucalyptus cloud. Using the EC2 command-line tools, you can learn about installed images, start VM instances using those images, describe the running instances, and terminate them when you're finished with them.
The following EC2 commands will allow you to query the system:
euca-describe-images IMAGE <emi-id> ...
euca-describe-instances (will be empty until you start an instance, as shown below)
euca-describe-availability-zones
euca-describe-keypairs (will be empty until you add key pairs, as shown below)
Before starting a VM, you need to create at least one key pair. This key pair will be injected into the VM, allowing you to SSH into the instance. Below we will use mykey as a handle, but you may choose any string you like instead:
euca-add-keypair mykey >mykey.private ('mykey' is the name for the key in Eucalyptus, 'mykey.private' is the file to be used by ssh)
chmod 0600 mykey.private
euca-run-instances -k mykey -n <number of instances to start> <emi-id>
euca-describe-instances (should now show the instance)
If your administrator has configured Eucalyptus to provide security groups and elastic IPs, you may be required to allow logins to your instance, allocate a public IP (if you have not done so before, check 'euca-describe-addresses' as a reminder), and assign it to your running instance:
Allow 'ssh' connections from the Internet:
euca-authorize -P tcp -p 22 -S 0.0.0.0/0 default
Allocate a public IP if you have not done so already:
euca-allocate-address
Associate an allocated IP with your running instance:
euca-associate-address <IP from allocate> -i <instance ID>
Once the instance is shown as 'Running', it will also show two IP addresses assigned to it. You may log into it with the SSH key that you created:
ssh -i mykey.private root@<accessible-instance-ip>
To terminate instances, use:
euca-terminate-instances <instance-id1> <instance-id2> ... <instance-idn>
Please, see Amazon's EC2 Getting Started Guide for more information about these command-line tools. Keep in mind that, depending on how the administrator has configured Eucalyptus, not all tools/operations are necessarily supported (security groups/elastic IPs). Consult your administrator for more information. Interacting with Walrus (1.5.2)
Walrus is a storage service included with Eucalyptus that is interface compatible with Amazon's S3. Walrus allows users to store persistent data, organized as buckets and objects (see Amazon's S3 Getting Started Guide for more information). Walrus system options can be modified via the administrator web interface.
If you would like to use Walrus to manage Eucalyptus VM images, you can use Amazon's tools to store/register/delete them from Walrus.
Otherwise, you may use other third party tools to interact with Walrus directly. Third party tools for interacting with Walrus/S3 ¶
* s3curl S3 Curl is a command line tool that is a wrapper around curl.
* s3cmd is a tool that allows easy command line access to storage that supports the S3 API.
* s3fs is a tool that allows users to access S3 buckets as local directories.
Interacting with Block Storage (1.5.2)
The Block Storage Service in Eucalyptus is interface-compatible with Amazon's Elastic Block Store. You can therefore use either EC2 commands or euca2ools commands to control it.
The instructions below rely on the euca2ools command-line tools distributed by the Eucalyptus Team. Please, install them if you haven't done so already.
The following operations are possible,
1. Creating volumes
You may create a volume either from scratch or from an existing snapshot.
euca-create-volume --size <size> --zone <zone>
where <size> is the size in GB and <zone> is the availability zones you wish to create the volume in (use euca-describe-availability-zones to discover zones).
For instance,
euca-create-volume --size 1 --zone myzone
will create a 1GB volume in the availability zone "myzone"
To create a volume from a snapshot,
euca-create-volume --snapshot <snapshot id> --zone <zone>
where <snapshot id> is the unique identifier for a snapshot and <zone> is the availability zone you wish to create the volume in.
For instance,
euca-create-volume --snapshot --zone myzone snap-EF4323
will create a volume from the snapshot "snap-EF4323" in the zone "myzone"
2. Query the status of volumes
euca-describe-volumes
Volumes marked "available" are ready for use.
3. Attaching a volume
You can attach volumes to existing instances (that have been started with euca-run-instances). You may attach a volume to only one instance at a time.
euca-attach-volume -i <instance id> -d <local device name> <volume id>
where <volume id> is the unique identifier for a volume (vol-XXXX), <instance id> is a unique instance identifier and <local device name> is the name of the local device in the guest VM.
For instance,
euca-attach-volume -i i-345678 -d /dev/sdb vol-FG6578
will attach the previously unattached volume "vol-FG6578" to instance "i-345678" with the local device name "/dev/sdb"
4. Detaching a volume
euca-detach-volume <volume id>
where <volume id> is the unique identifier for a previously attached volume (vol-XXXX).
For instance,
euca-detach-volume vol-FG6578
will detach volume "vol-FG6578"
Important! The user of the instance is responsible for making sure that the block device is unmounted before a detach. Detach cannot ensure the consistency of user data if the user detaches a volume that is in use.
5. Deleting a volume
euca-delete-volume <volume id>
where <volume id> is the unique identifier for a volume (vol-XXXX).
6. Creating a snapshot from a volume
You can snapshot a volume so that you can create volumes in the future from the snapshot.
euca-create-snapshot <volume id>
where <volume id> is the unique identifier for a volume (vol-XXXX).
For instance,
euca-create-snapshot vol-GH4342
will snapshot the volume "vol-GH4342"
The volume to be snapshotted needs to be "available" or "in-use." You cannot snapshot a volume that is in the "creating" state.
7. Querying the status of snapshots
euca-describe-snapshots
You may create volumes from snapshots that are marked "completed."
8. Deleting a snapshot
euca-delete-snapshot <snapshot id>
where <snapshot id> is the unique identifier for a snapshot.