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

Getting Started with Ubuntu Enterprise Cloud

Overview

The Ubuntu Enterprise Cloud (UEC), powered by Eucalyptus, is highly configurable and customizable to a variety of environments. This tutorial covers UEC installation from the Ubuntu 9.10 Server Edition CD, and assumes a basic network topology, with a single system serving as the "all-in-one controller", and one or more nodes attached.

Another tutorial exists describing how to deploy UEC on already installed Ubuntu servers, or if you want to deploy a more complex network topology, with multiple clusters, or running the required cloud services from separate physical machines.

Terminology

You should be familiar with the Glossary. These terms are used throughout the documentation.

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 or several node(s) for running Virtual Machine (VM) instances. You will also use examples to help get you started using your own private compute cloud.

Tutorial

STEP 1: Prerequisites

To deploy a minimal cloud infrastructure, you’ll need at least two dedicated systems:

• a front end
• one or more node(s)

Refer to the System Requirements tables for the detailed hardware requirements of these physical systems.

STEP 2: Install the Cloud/Cluster controller

1. Download the 9.10 Server ISO

2. When you boot, select “Install Ubuntu Enterprise Cloud”.
   

3. When asked whether you want a “Cluster” or a “Node” install, select “Cluster”.
   

4. It will ask two other cloud-specific questions during the course of the install:
   1. Name of your cluster

      • e.g. cluster1

   2. A range of public IP addresses on the LAN that the cloud can allocate to instances

      • e.g. 192.168.1.200-192.168.1.249

STEP 3: Install the Node controller(s)

The node controller install is even simpler. Just make sure that you are connected to the network on which the cloud/cluster controller is already running.

1. Boot from the same ISO on the node(s)
2. Select “Install Ubuntu Enterprise Cloud”
3. It should detect the Cluster and preselect “Node” install for you
4. Confirm the partitioning scheme
5. The rest of the installation should proceed uninterrupted; complete the installation and reboot the node

STEP 4: Register the Node with the Cloud/Cluster-Controller

1. After all nodes are installed, return to the cloud/cluster-controller and run the following command to have it discover and register your newly-installed nodes.

   sudo euca_conf --no-rsync --discover-nodes

2. Confirm each node it finds

STEP 5: Credentials setup

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.

1. From your web browser (either remotely or on your Ubuntu server) access the following URL:

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

   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.

2. Use username 'admin' and password 'admin' for the first time login (you will be prompted to change your password).
3. Then follow the on-screen instructions to update the admin password and email address.

4. Once the first time configuration process is completed, click the 'credentials' tab located in the top-left portion of the screen.
   

5. Click the 'Download Credentials' button to get your certificates
6. Alternatively, if you are on the command line of the Cloud/Cluster-Controller, you can run:

   mkdir -p ~/.euca
   chmod 700 ~/.euca
   cd ~/.euca
   sudo euca_conf --get-credentials mycreds.zip
   unzip mycreds.zip

Now you will need to setup EC2 API and AMI tools on your server using X.509 certificates.

1. Unzip the downloaded zipfile into a safe location (~/.euca)

   unzip -d ~/.euca mycreds.zip

2. Source the included "eucarc" file to set up your Eucalyptus environment

   . ~/.euca/eucarc

   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).

   echo ". ~/.euca/eucarc" >> ~/.bashrc

3. Install the required cloud user tools:

   sudo apt-get install euca2ools

4. To validate that everything is working correctly, get the local cluster availability details:

   . ~/.euca/eucarc
   euca-describe-availability-zones verbose
   AVAILABILITYZONE   myowncloud                 192.168.1.1
   AVAILABILITYZONE   |- vm types                free / max   cpu   ram  disk
   AVAILABILITYZONE   |- m1.small                0004 / 0004   1    128     2
   AVAILABILITYZONE   |- c1.medium               0004 / 0004   1    256     5
   AVAILABILITYZONE   |- m1.large                0002 / 0002   2    512    10
   AVAILABILITYZONE   |- m1.xlarge               0002 / 0002   2   1024    20
   AVAILABILITYZONE   |- c1.xlarge               0001 / 0001   4   2048    20

STEP 6: Bundle a UEC Image

There is more than one way to obtain a virtual image:

• Download an image from the network, bundle and upload it
• Create a custom image using VMBuilder
• Use the Image store to download and install and image

Here we will describe the process of downloading one of the Official Ubuntu UEC Images that we publish and maintain on a regular basis.

1. Download the UEC image for the architecture you want. You can do it from your browser or from the command line:

   TIMESTAMP=$(date +%Y%m%d%H%M%S)
   RELEASE=karmic
   [ $ARCH = "amd64" ] && IARCH=x86_64 || IARCH=i386
   UEC_IMG=$RELEASE-uec-$ARCH
   URL=http://uec-images.ubuntu.com/$RELEASE/current/
   [ ! -e $UEC_IMG.tar.gz ] &&  wget $URL/$UEC_IMG.tar.gz # This may take a bit, depending on your connectivity

2. Next, you will need to bundle, upload and register a kernel, ramdisk and finally your image:
   1. Unpack the UEC image tarball

      [ ! -e $UEC_IMG.img ] && tar -S -xzf $UEC_IMG.tar.gz

   2. Bundle the kernel

      BUCKET_KERNEL="k-$TIMESTAMP"
      UEC_KERNEL=$UEC_IMG-vmlinuz-virtual
      euca-bundle-image -i $UEC_KERNEL -r $IARCH --kernel true
      euca-upload-bundle -b $BUCKET_KERNEL -m /tmp/$UEC_KERNEL.manifest.xml
      EKI=$(euca-register $BUCKET_KERNEL/$UEC_KERNEL.manifest.xml | grep "^IMAGE" | awk '{print $2}') && echo $EKI

   3. Bundle the initrd

      BUCKET_INITRD="r-$TIMESTAMP"
      UEC_INITRD=$UEC_IMG-initrd-virtual
      euca-bundle-image -i $UEC_INITRD -r $IARCH --ramdisk true
      euca-upload-bundle -b $BUCKET_INITRD -m /tmp/$UEC_INITRD.manifest.xml
      ERI=$(euca-register $BUCKET_INITRD/$UEC_INITRD.manifest.xml | grep "^IMAGE" | awk '{print $2}') && echo $ERI

   4. Bundle the image itself (this can take some time)

      BUCKET_IMAGE="i-$TIMESTAMP"
      UEC_IMG=$RELEASE-uec-$ARCH
      euca-bundle-image -i $UEC_IMG.img -r $IARCH --kernel $EKI --ramdisk $ERI # This will take a long time (~10m)
      euca-upload-bundle -b $BUCKET_IMAGE -m /tmp/$UEC_IMG.img.manifest.xml
      EMI=$(euca-register $BUCKET_IMAGE/$UEC_IMG.img.manifest.xml | grep "^IMAGE" | awk '{print $2}') && echo $EMI

3. 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'.

STEP 7: Running an Image

There are multiple way to instantiate (start) an image:

• Use the command line
• Use one of the UEC compatible management tools such as Landscape

• Use the ElasticFox extension to Firefox

Here we will describe the process from the command line:

1. 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:

   if [ ! -e ~/.euca/mykey.priv ]; then
       touch ~/.euca/mykey.priv
       chmod 0600 ~/.euca/mykey.priv
       euca-add-keypair mykey > ~/.euca/mykey.priv
   fi

   Note: 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.

2. You must also allow access to port 22 in your instances:

   euca-describe-groups    # Work around Bug:452556
   euca-authorize default -P tcp -p 22 -s 0.0.0.0/0

3. Next, you can create instances of your registered image:

   euca-run-instances $EMI -k mykey -t c1.medium

4. 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:

   watch -n5 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'.
5. When the instance is fully started, the above state will become 'running'. Look at the IP address assigned to your instance in the output, then connect to it:

   IPADDR=$(euca-describe-instances | grep $EMI | grep running | tail -n1 | awk '{print $4}')
   ssh -i ~/.euca/mykey.priv ubuntu@$IPADDR

6. And when you are done with this instance, exit your SSH connection, then terminate your instance:

   INSTANCEID=$(euca-describe-instances | grep $EMI | grep running | tail -n1 | awk '{print $2}')
   euca-terminate-instances $INSTANCEID

More Information

• Log files: /var/log/eucalyptus

• Configuration files: /etc/eucalyptus

• Database: /var/lib/eucalyptus/db

• Environment note: Don't forget to source your ~/.euca/eucarc before running the client tools.