Contents

Getting Started with Ubuntu Enterprise Cloud

Getting Started with Ubuntu Enterprise Cloud

Note: Please see Eucalyptus-Jaunty for documentation covering UEC on Ubuntu 9.04.

Overview

The Ubuntu Enterprise Cloud (UEC), powered by Eucalyptus, is highly configurable, allowing it to be customized to fit a wide variety of environments. This installation tutorial covers setting up a UEC private cloud.

Objective

From this Tutorial you will learn how to install, configure, register and perform several operations on a basic UEC setup that results in a cloud with a one controller "front-end" and one node for running Virtual Machine (VM) instances (steps 1, 2, and 3). You will also use examples to help get you started using your own private compute cloud and, optionally, how to register your private cloud with the RightScale Cloud Management Platform (steps 4, 5, and 6).

Prerequisites
Installation and Configuration
Registering Eucalyptus components
Initial Login and optional Cloud Registration
Creating a Virtual Machine (VM) image
Running your image

Tutorial

STEP 1: Prerequisites

A UEC system includes the following high level packages:

eucalyptus-cc - includes the Cluster Controller that provides support for the virtual network overlay
eucalyptus-cloud - includes the front-end services (Cloud Controller) as well as the Walrus storage system.
eucalyptus-nc - includes the Node Controller that interacts with KVM to manage individual VMs

In a basic UEC setup, the system is composed of two machines (a front-end and a node). The front end runs both eucalyptus-cloud and eucalyptus-cc in this configuration. The node runs the node controller, eucalyptus-nc. It is possible to separate the cloud controller and cluster controller in a more complex multi-host setup. The following diagram depicts a simple setup:

Before you install the packages (or shortly thereafter), there are some prerequisites that should be satisfied to end up with a fully functioning Eucalyptus system.

On each node, configure the system's primary ethernet interface as a bridge. (See the Ubuntu Server Guide Bridging for details). The node controller will attach virtual network interfaces to this bridge for VM that is started before it to enable network connectivity.
Note: Remember the name of your node's bridge device (we assume the name of your bridge device is "br0" for the rest of this document).
The default Eucalyptus configuration assumes that there is not a DHCP server in your environment that is handing out dynamic IP addresses. The Cluster Controller runs a dhcp server that will statically assign IP addresses to VMs (which will be bridged on the local network).
From any host that you wish to use as a Eucalyptus client, you should install the euca2ools package from universe:
```
$ sudo apt-get install euca2ools
```
Also, other tools that can interact with the EC2 and S3 APIs should work with Eucalyptus.
If you wish to access Eucalyptus from behind a firewall (i.e. the euca2ools tools and the cloud controller will be on different sides of a firewall) then port 8773 must be open on the cloud controller. Additionally, if you plan to register your Eucalyptus installation with a cloud management platform, 8773 and 8443 must be open.

STEP 2: System Installation and Configuration

Install the eucalyptus-cloud and eucalyptus-cc packages on the front-end machine:

$ sudo apt-get install eucalyptus-cloud eucalyptus-cc

Next, install the eucalyptus-nc package on each node:

$ sudo apt-get install eucalyptus-nc

Finally, on the node, bring down the eucalyptus-nc service and modify /etc/eucalyptus/eucalyptus.conf with the name of the bridge that you set up as the node's primary interface.

Note that there are several ways to configure a node to have a bridge as its primary interface, depending on the configuration of your machine. We show an example set of steps here but you will need to take care to ensure that this example configuration does not conflict with your local configuration if you wish to use it.

However, if you have arranged for the bridge to be configured, you need to specify that bridge name ("br0" in our examples) in the node controller's configuration. To do so, type

$ sudo /etc/init.d/eucalyptus-nc stop
$ sudo vi /etc/eucalyptus/eucalyptus.conf
# set VNET_BRIDGE="br0"
$ sudo /etc/init.d/eucalyptus-nc start

The following diagram depicts what your setup should now resemble:

You will also need to change your networking configuration to make it so that IPv4 traffic is passed to IPv6 ports since the Eucalyptus web frontend runs by default only on IPv6. To do so, type

$ sudo vi /etc/sysctl.conf
# uncomment net.ipv4.ip_forward=1
# (it may not be commented out)
$ sudo sysctl -p

Also, you may have noticed a message such as:

apache2: Could not reliably determine the server's fully qualified domain name, using 127.0.0.1 for ServerName

UEC has its own Apache config, you can add your ServerName statement there to make that go away, just edit /etc/eucalpytus/httpd.conf to begin somewhat like this:

# 
# This is the apache config for eucalyptus: we use it only to load the
# axis2c module which will take care of the WebServices
#

ServerTokens OS
ServerName WHATEVER_YOUR_HOSTNAME_IS_HERE
ServerRoot "/tmp"

Listen 8774
KeepAliveTimeout 30

You can verify that this resolved the issue by running

sudo dpkg-reconfigure eucalyptus-nc

STEP 3: Registering UEC Components

UEC assumes that each node in the system belongs to a cluster and that each cluster belongs to a cloud. Each node (there is only one node in this example) runs a copy of eucalyptus-nc. Similarly, each cluster (again, there is only one cluster in this example) must run a copy of eucalytpus-cc. For simplicity, the eucalyptus-cc in this example runs on the same machine as the cloud controller (eucalyptus-clc). These components must be registered with each other before the system starts. To register a cluster, execute the following on the cloud controller:

$ sudo euca_conf -addcluster <clustername> localhost

where <clustername> is the name that you would like this cluster to appear as to your users. Note that this name is logical and local only to Eucalyptus. It will correspond to an availability zone in the output of the client tools. Next, register your node with the cluster by running the following command on the clound controller:

$ sudo euca_conf -addnode <node_hostname>

Later, you can add more nodes by repeating the above command for each node running a copy of eucalyptus-nc. At this point, your Eucalyptus system should be up and running, ready for first time use.

STEP 4: Initial Login

The first time the cloud controller boots, you are required to go through some configuration steps that set up the administrative environment for the cloud. From your web browser (either remotely or on your Ubuntu server) access the following URL:

https://<cloud-controller-ip-address>:8443/

Use username 'admin' and password 'admin' for the first time login (you will be prompted to change your password). You can use "localhost" instead of your front-end's IP address if you are on that server. Now follow the on-screen instructions. When you finish the first time configuration process, click the 'credentials' tab located in the top-left portion of the screen. Click the 'Download Certificate' button to get your credentials.

Important! You must use a secure connection, so make sure you use "https" not "http" in your URL. You will get a security certificate warning. You will have to add an exception to view the page. If you do not accept it you will not be able to view the Eucalyptus configuration page.

Now you will need to setup EC2 API and AMI tools on your server using X.509 certificates. Unzip the downloaded zipfile into a safe location (~/.euca), and source the included "eucarc" file to set up your Eucalyptus environment. You may additionally wish to add this command to your ~/.bashrc file so that your Eucalyptus environment is set up automatically when you log in. Eucalyptus treats this set of credentials as 'administrator' credentials that allow the holder global privileges across the cloud. As such, they should be protected in the same way that other elevated-priority access is protected (e.g. should not be made visible to the general user population).

Alternatively, you can script the installation using these instructions.

Optional Registration With RightScale

RightScale offers a Cloud Management Platform for use with Eucalyptus, both as a free service and through paid subscriptions. This cloud management software runs as a service within Amazon's AWS so it must be able to communicate with the UEC cloud controller (eucalyptus-clc) through any firewalls that separate the public Internet from where eucalyptus-clc is running. Thus ports 8443 and 8773 must be open to the public Internet for RightScale to be able to communicate with your Eucalyptus cloud.

To register your UEC cloud with RightScale's service, see Register my cloud with RightScale

STEP 5: Obtain a Virtual Machine (VM) Image

There is more than one way to obtain a virtual image. The easiest way is to simply download one of the Official Ubuntu UEC Images. Alternatively, if you would want to author your own image, you can use the vmbuilder procedure below to create an image.

$ wget http://uec-images.ubuntu.com/releases/karmic/<release>/ubuntu-uec-karmic-i386.img.gz

Next, you will need to bundle, upload and register a kernel, ramdisk and finally your image. Using the EC2 API tools, perform the following steps:

# bundle and upload the systems kernel
$ mkdir kernel
$ euca-bundle-image --image /boot/vmlinuz-$(uname -r) \
  --destination ./kernel --kernel true
$ euca-upload-bundle --bucket kernel \
  --manifest ./kernel/vmlinuz-$(uname -r).manifest.xml
$ EKI=`euca-register kernel/vmlinuz-$(uname -r).manifest.xml | awk '{print $2}'`
$ echo $EKI

# create a ramdisk with acpiphp, bundle and upload
$ mkdir ramdisk
$ sudo sh -c 'grep -q acpiphp /etc/initramfs-tools/modules ||
   printf "#acpiphp needed for ebs\nacpiphp\n" > /etc/initramfs-tools/modules'
$ sudo mkinitramfs -o ./ramdisk/initrd.img-$(uname -r)
$ euca-bundle-image --image ./ramdisk/initrd.img-$(uname -r) \
   --destination ./ramdisk --ramdisk true
$ euca-upload-bundle --bucket ramdisk \
   --manifest ramdisk/initrd.img-$(uname -r).manifest.xml
$ ERI=`euca-register ramdisk/initrd.img-$(uname -r).manifest.xml | awk '{print $2}'`
$ echo $ERI

# uncompress, bundle the image
$ mkdir image 
$ zcat ubuntu-uec-karmic-i386.img.gz |
   cp --sparse=always /dev/stdin ubuntu-uec-karmic-i386.img
$ euca-bundle-image --image ubuntu-uec-karmic-i386.img \
   --destination ./image --kernel $EKI --ramdisk $ERI
$ euca-upload-bundle --bucket image --manifest ./image/root.img.manifest.xml
$ EMI=`euca-register image/root.img.manifest.xml | awk '{print $2}'`
$ echo $EMI

Note the shell variables that have been set in the above code snippets. They will be used to test the installation in the steps below. Now, your kernel, ramdisk and image will have been uploaded into Eucalyptus and should be ready to run. To confirm, run the following command:

$ euca-describe-images

You should see a registered kernel, ramdisk and image and they should be marked as 'available'.

Please note: if you are preparing the bundle on a machine that uses encrypted filesystems be aware that you cannot bundle the machine ramdisk for your AMI. This is because your local ramdisk includes routines to decrypt your local encrypted filesystem and these will make the instance crash at boot (as the encrypted filesystem does not exist).

STEP 6: Running an Image

Before running an instance of your image, you should first create a keypair (ssh key) that you can use to log into your instance as root, once it boots. The key is stored, so you will only have to do this once. Run the following command:

$ euca-add-keypair mykey > ~/.euca/mykey.priv
$ chmod 0600 ~/.euca/mykey.priv

Note: that you can call your key whatever you like (in this example, the key is called 'mykey'), but remember what it is called. If you forget, you can always run 'euca-describe-keypairs' to get a list of created keys stored in the system. Next, you can create instances of your registered image:

$ euca-run-instances $EMI -k mykey

The first time you run an instance, the system will be setting up caches for the image from which it will be created. This can often take some time the first time an instance is run given that VM images are usually quite large. To monitor the state of your instance, run:

$ euca-describe-instances

In the output, you should see information about the instance, including its state. While first-time caching is being performed, the instance's state will be 'pending'. As soon as the instance is started, the state will become 'running'. As soon as the instance acquires an IP address from DHCP, you will see the public and private address fields change from '0.0.0.0' to a usable IP. When this happens, you can log into your new instance using the previously generated ssh key:

$ ssh -i ~/.euca/mykey.priv ubuntu@<ip_of_instance>

Your UEC cloud should now look similar to the following logical diagram:

More Information

Log files: /var/log/eucalyptus
Configuration files: /etc/eucalyptus
Init Scripts: /etc/init.d/eucalyptus-cc, /etc/init.d/eucalytpus-cloud and /etc/init.d/eucalytpus-nc
Database: /var/lib/eucalyptus/db
Reboot note: If you reboot your machine Eucalyptus may not start up and function automatically. You may need to restart the services manually.
Environment note: Don't forget to source your ~/.euca/eucarc before running the client tools.

Next Steps and Links

Optional procedure to create images

Eucalyptus procedure

The Eucalyptus project is proposing an alternate guide to create images

Using vmbuilder

If you would want to author your own image, you can use the vmbuilder utility utility to create an image that will run in Eucalyptus. First, create a partition description file called 'part'. The contents describe the size, types, and mount points of your VM disk partitions:

$ cat > part <<EOF
root 400
/mnt/ephemeral 0 /dev/sda2 
swap 1 /dev/sda3
EOF

Next, create a simple script called 'firstboot' that will be executed the first time your image boots inside Eucalyptus to install an ssh daemon. In a file called 'firstboot' create the shell script:

$ cat >firstboot <<EOF
#!/bin/sh
apt-get -y install openssh-server 
EOF

Then, create the image with vmbuilder passing the name of the script file as an argument so that it can be installed. Note that even though we are asking vmbuilder to create a 'xen' image (this simply just means that the output format of the image is a disk partition), the resulting image will boot in Eucalyptus using KVM.

$ sudo vmbuilder xen ubuntu --part ./part --firstboot ./firstboot