60 Recipes for Apache CloudStack

Chapter 1. Installing from Source

These recipes are aimed at CloudStack developers who need to build the code. These instructions are valid on Ubuntu 14.04 and CentOS 6.5 systems, and were tested with the 4.4 branch of Apache CloudStack; you might need to adapt them if you are on a different operating system or using a newer/older version of CloudStack. In these recipes, we cover the following items:

• Installing the prerequisites
• Compiling and installing from source
• Using the CloudStack simulator
• Testing with the CloudStack sandbox: DevCloud
• Building your own packages

Note

At the time of this writing, the 4.4 release is not out yet: therefore, the source testing is done on the release branch 4.4 and the packages used are the 4.3.0 packages.

1.1. Installing the Prerequisites for Ubuntu 14.04

Problem

Like any software, CloudStack has some dependencies. In this recipe, we look at installing the dependencies you’ll need for Apache CloudStack development. You can use the package installation snippets to set up a machine that will allow you to build CloudStack on Ubuntu 14.04.

Solution

First, update your system. Install OpenJDK, which is our first choice, because we’re using Linux. Install MySQL. Install Git to later clone the CloudStack source code. Install Maven to later build CloudStack.

Discussion

The following package installation will get the prerequisites installed on Ubuntu/Debian-based systems (this was tested on a Ubuntu 14.04 machine):

# apt-get -y update
# apt-get -y install openjdk-7-jdk
# apt-get -y install mysql-server
# apt-get install git
# apt-get install maven

MySQL should be running, but you can check its status with:

# service mysql status

This should have installed Maven 3.0.5 (you can check the version number with mvn --version).

A little bit of Python can be used, as we will see with the simulator described in Recipe 1.4. Therefore, install the Python package management tools:

# apt-get install python-pip

1.2. Installing the Prerequisites for CentOS 6.5

Problem

Like any software, CloudStack has some dependencies. In this recipe, we look at installing the dependencies you’ll need for Apache CloudStack development. You can use the package installation snippets to set up a machine that will allow you to build CloudStack and CentOS 6.5.

Solution

First, update your system. Install OpenJDK, which is our first choice, because we’re using Linux. Next, install MySQL, if it’s not already present on the system. Install Git to later clone the CloudStack source code. Finally, install mkisofs via the genisoimage package.

Discussion

The following package installation snippet will get most of the prerequisites installed on a CentOS/RHEL-based system (this was tested on a CentOS 6.5 machine):

# yum -y update
# yum -y install java-1.7.0-openjdk
# yum -y install java-1.7.0-openjdk-devel
# yum -y install mysql-server
# yum -y install git
# yum -y install genisoimage

MySQL should be stopped. You can check its status with service mysqld status and start it with service mysqld start.

Let’s now install Maven to build CloudStack. It is a bit more complex than on Ubuntu 14.04. Grab the 3.0.5 release from the Maven website:

# wget http://mirror.cc.columbia.edu/pub/software/apache/maven/maven-3/ \
3.0.5/binaries/apache-maven-3.0.5-bin.tar.gz
# tar xzf apache-maven-3.0.5-bin.tar.gz -C /usr/local
# cd /usr/local
# ln -s apache-maven-3.0.5 maven

You can set up Maven system-wide by creating a /etc/profile.d/maven.sh file with the following content:

# export M2_HOME=/usr/local/maven
# export PATH=${M2_HOME}/bin:${PATH}

Run the following, and you will have Maven in your PATH (the preceding steps should have installed Maven 3.0; you can check the version number with mvn --version):

# source /etc/profile.d/maven.sh
# mvn --version

A little bit of Python can be used (see Recipe 1.4), so install the Python Package Index utility (pip):

# yum -y install python-pip

Note

CentOS 6.5 is using Python 2.6.6. To use the simulator and the CloudStack Marvin package, we will need Python 2.7 or later. Setting up Python 2.7 is left out of this recipe.

1.3. Installing from Source

Problem

With prerequisites installed (see Recipe 1.1 or Recipe 1.2), you want to build CloudStack from source and run the management server locally.

Solution

You clone the Git repository of CloudStack and use several Maven profiles to build from source, set up the database, and run the management server with Jetty.

Discussion

If you have gone through the prerequisite steps on Ubuntu or CentOS, then the following build steps should be identical on both systems. CloudStack uses Git for source version control; if you’re not familiar with Git, the online GitHub tutorial is a good start.

Warning

The steps highlighted in this section are the minimal steps required to get a successful build of Apache CloudStack. Setting up a hypervisor, setting up storage, and running the CloudStack management server in a nondebug and production mode will require additional packages.

Once Git is set up on your machine, pull the source from the Apache repository with:

git clone -b 4.4 https://git-wip-us.apache.org/repos/asf/cloudstack.git

Tip

The Apache CloudStack repository is also mirrored on GitHub. You might want to clone from there:

git clone -b 4.4 https://github.com/apache/cloudstack.git

Although I am an Apache committer, I admit that the Apache Git repo tends to be a bit slow. You will clone faster by using the GitHub mirror.

Now that you have installed the prerequisites and cloned the source code, you are ready to build the 4.4 release (which, at the time you are reading this, should be the latest stable release). To compile CloudStack, go to the CloudStack source folder and use Maven commands (if you want to skip running the unit tests, add -DskipTests to this command):

cd cloudstack
mvn -Pdeveloper,systemvm clean install

Next, create all the proper MySQL tables with:

mvn -Pdeveloper -pl developer -Ddeploydb

You can check what tables have been created by opening an interactive MySQL shell and looking at the cloud database. Runing the Apache CloudStack management server is only one command away. We’ll use Jetty for testing (note that if you installed tomcat, it may be be running on port 8080, so you’ll need to stop it before you use Jetty):

mvn -pl :cloud-client-ui jetty:run

This will run in the foreground and you will see the logs in stdout. To access the dashboard, open your web browser to http://localhost:8080/client (replace localhost with the IP of your management server if need be).

Note

If you have iptables enabled, you may have to open the ports used by CloudStack (i.e., ports 8080, 8250, and 9090). For testing, you might want to disable the firewall with ufw disable on Ubuntu or service iptables stop on CentOS, but don’t forget to turn it back on if you open this machine to the public Internet.

You can now start exploring the dashboard and play with the API. Of course, we did not set up any infrastructure and there is no storage, no hypervisors, and no network defined. At this stage, you will not be able to start instances. However, you are a couple steps away from using the simulator. The next recipe shows you how to use the simulator so that you don’t have to set up a physical infrastructure, which will allow you to start developing and playing with a virtual data center on your local machine.

1.4. Using the CloudStack Simulator

Problem

You want to run some functionality tests against the CloudStack management server, but you do not want to (or cannot) deploy a complete CloudStack cloud on a physical infrastructure.

Solution

Use the CloudStack simulator to set up a virtual data center. You build CloudStack with the simulator profile and set up some specific database tables with another Maven profile. Then you install Marvin, a Python-based testing framework for CloudStack. Once you start the management server again, you can use a Marvin script (deployDataCenter.py) to configure a simulated infrastructure.

Discussion

CloudStack comes with a simulator based on Python bindings called Marvin. Marvin is available in the CloudStack source code or on PyPI. With Marvin, you can simulate your data center infrastructure by providing CloudStack with a configuration file that defines the number of zones/pods/clusters/hosts, types of storage, and so on. You can then develop and test the CloudStack management server as if it were managing your production infrastructure. To use the simulator, we need to alter some of our build steps and use Marvin to configure the simulated data center.

First, do a clean build and add the simulator profile:

mvn -Pdeveloper -Dsimulator -DskipTests clean install

Then deploy the database and set up some simulator-specific tables and configurations using the following:

mvn -Pdeveloper -pl developer -Ddeploydb
mvn -Pdeveloper -pl developer -Ddeploydb-simulator

Warning

As mentioned previously, the Marvin package used to configure the data center requires Python 2.7 or later, so if you are using CentOS 6.5, you will need to install it. Because it can involve building Python from source, we are not covering this step.

Next, install Marvin (note that you will need to have installed pip properly in the prerequisites step; the python-dev package is needed to install the paramiko module, and the --allow-external flag helps install the mysql-connector-python package):

sudo apt-get -y install python-dev
sudo pip install --allow-external mysql-connector-python mysql-connector-python
sudo pip install tools/marvin/dist/Marvin-0.1.0.tar.gz

Stop Jetty (from any previous runs) and start a new management server with a simulator profile:

mvn -pl :cloud-client-ui jetty:stop
mvn -pl client jetty:run -Dsimulator

With the management server running in the foreground, open a separate shell to set up a basic zone with Marvin:

python ./tools/marvin/marvin/deployDatacenter.py -i setup/dev/basic.cfg

At this stage, log in to the CloudStack management server at http://localhost:8080/client with the credentials admin/password; you should see a fully configured basic zone infrastructure. To simulate an advanced zone, replace basic.cfg with advanced.cfg. You can now start a simulated instance and take snapshots of it, in addition to running most operations that a production system would allow you to do. Using the simulator is a good way to test new features, test API clients, and run integration tests.

1.5. Using the CloudStack Sandbox: DevCloud

Problem

The simulator is not enough for your testing or demonstrations. You want to take advantage of nested virtualization to run a Xen-based hypervisor locally, and use CloudStack to start virtual machines within this local hypervisor.

Solution

Use DevCloud, a VirtualBox image, to run a Xen hypervisor on your local machine. Using Maven, you set up the database for the special DevCloud use case, and run Marvin to configure CloudStack with DevCloud. You will have a cloud with one zone, one pod, one cluster, and one host: DevCloud.

Discussion

Installing from source (see Recipe 1.3) will get you to the point of running the management server, but it does not get you any hypervisors. The simulator (see Recipe 1.4) gets you a simulated data center for testing. With DevCloud, you can run at least one hypervisor and add it to your management server the way you would a real physical machine.

DevCloud is the CloudStack sandbox. The standard version is a VirtualBox-based image, though there is also a KVM-based image for it. Here we only show steps with the VirtualBox image. For KVM, there are good instructions on the CloudStack wiki.

With DevCloud, you will run the management server on your local machine and Xen hypervisors in the DevCloud VirtualBox image. DevCloud and localhost will be connected via a host-only interface available through the VirtualBox. DevCloud also has a NAT interface to get access to the public Internet.

Note

You could also run the management server within DevCloud itself, avoiding the need to set up your local environment to compile CloudStack from source.

DevCloud prerequisites

To get started, we need to install a few prerequisites:

1. Install VirtualBox on your machine.
2. Run VirtualBox and, under Preferences, create a host-only interface on which you disable the DHCP server.
3. Download the DevCloud image.
4. In VirtualBox, under File → Import Appliance, import the DevCloud image.
5. Verify the settings under Settings, and check the “enable PAE” option in the processor menu.
6. Once the VM has booted, try to SSH to it with credentials: root/password and ssh root@192.168.56.10.

If successful, you can move to the machine running the management server and configure a basic zone that will have one zone, one pod, one cluster, and one hypervisor: DevCloud.

Adding DevCloud as a hypervisor

To get the management server running, we do a clean build, but when we set up the database, we use some DevCloud-specific Maven profiles that are going to fill up some tables with values that match this particular setup:

mvn -Pdeveloper,systemvm clean install
mvn -Pdeveloper -pl developer,tools/devcloud -Ddeploydb

At this stage, install Marvin like you did in Recipe 1.4:

pip install tools/marvin/dist/Marvin-0.1.0.tar.gz

Start the management server with Jetty:

mvn -pl client jetty:run

You will have a running CloudStack management server but an empty infrastructure. You are going to configure CloudStack, defining a data center with a single hypervisor. To do this, we use a Python script in the Marvin directory called deployDataCenter.py. This script takes a JSON file as input and makes the required CloudStack API calls to create the zone, pod, cluster, host, and storage components of this single hypervisor data center. Here’s how to do it:

cd tools/devcloud
python ../marvin/marvin/deployDataCenter.py -i devcloud.cfg

If you are curious, check the devcloud.cfg file and see how the data center is defined in a JSON format.

You can now log in to the management server at http://localhost:8080/client and start experimenting with the UI. If the configuration went well, you should see the infrastructure defined in the Infrastructure tab in the dashboard. With the zone enabled and all components set up, you can head to the Instances tab and start an instance. The default template is a ttylinux template that you will be able to SSH into.

Note

The management server is running in your local machine, and DevCloud is used only as a hypervisor. You could potentially run the management server within DevCloud as well, or memory granted, run multiple DevClouds.

Using DevCloud is a good way to get started with CloudStack and start real instances. You can use it to learn the API and learn the CloudStack networking setup.

Warning

As of this writing, DevCloud is broken for use with the yet to be released CloudStack 4.4. DevCloud should be fixed when 4.4 is out. There is an alternative solution being developed by a Google Summer of Code 2014 project (see Recipe 1.6).

1.6. Vagrant-Based CloudStack Testing Deployment

Problem

You like DevCloud Recipe 1.5, but you would like to use a more configurable and manageable solution based on Vagrant (Recipe 5.4) and Chef (Recipe 5.9) to start a CloudStack development environment.

Solution

Use a Vagrant-based project currently under development through the Google Summer of Code (GSoC). It will use Vagrant boxes to act as a hypervisor and as an NFS and MySQL server. You will run the CloudStack management server on your local machine and it will connect to the remote database server. You will configure the data center using Marvin, just like with DevCloud (Recipe 1.5).

Discussion

This recipe assumes that you have some knowledge of Vagrant. If not, go through Recipe 5.4 first. The configuration of the NFS and MySQL server, as well as the NAT routing, is done via Chef recipes. This GSoC project aims to provide complete Chef recipes to install CloudStack.

Warning

For this recipe, you will need VirtualBox installed on your machine. You will also need to set up VirtualBox with a host-only interface that has the DHCP server disabled.

To try this work in progress, clone what is currently called GSoC-2014 and use Vagrant to start the boxes. The project makes use of Git submodules and you will need the --recursive option when cloning to get the code from these subprojects:

git clone --recursive https://github.com/imduffy15/GSoC-2014.git
cd GSoC-2014
cd MySql_NFS_XenServer
vagrant up

This will start a management machine based on CentOS 6.5 and using Chef (Recipe 5.9). A xenserver machine will also be brought up to act as a hypervisor. Go back to the cloudstack directory, build and run the CloudStack management server on your local machine and use Marvin to configure the data center programmatically (if you need help with any of these steps, refer back to Recipe 1.3):

wget http://download.cloud.com.s3.amazonaws.com/tools/vhd-util \
     -P scripts/vm/hypervisor/xenserver/
chmod +x scripts/vm/hypervisor/xenserver/vhd-util
mvn -P developer,systemvm clean install -DskipTests=true
mvn -P developer -pl developer,tools/devcloud -Ddeploydb
mvn -pl :cloud-client-ui jetty:run

With the management server running, you can access the dashboard at http://localhost:8080/client. On another shell, install Marvin and deploy the devcloud configuration:

pip install tools/marvin/dist/Marvin-0.1.0.tar.gz
python tools/marvin/marvin/deployDataCenter.py -i ../devcloud.cfg

To check on the status of the system VMs (Recipe 2.8), use vagrant ssh and once logged in on the hypervisor, use the xe toolstack to check the running VMs:

cd ../MySql_NFS_XenServer
vagrant ssh xenserver
sudo su
xe vm-list

Once the system VMs are up and running, the ttylinux template will get downloaded and installed and you will be able to start an instance, do all the testing that you want, and develop more CloudStack features. Enjoy!

1.7. Building CloudStack Binary Packages

Problem

Instead of using the convenience binaries available through a community-maintained repository, you want to build your own CloudStack packages from source.

Solution

Install a few more packages, which were not required for building from source. On Ubuntu, use the dpkg-buildpackage command, and on CentOS/RHEL systems, use the script package.sh located in the packaging/centos63/ directory.

Discussion

Working from source is necessary when developing CloudStack. As mentioned earlier, this is not primarily intended for users. However, some may want to modify the code for their own use and specific infrastructure. They may also need to build their own packages for security reasons and due to network connectivity constraints. This recipe shows you the gist of how to build packages. We assume that you will know how to create a repository to serve these packages. The complete documentation is available on the website.

To build Debian packages, you will need a couple extra packages that we did not need to install as prerequisites for source compilation:

# apt-get -y install python-mysqldb
# apt-get -y install debhelper
# apt-get -y install tomcat6

Then build the packages with:

# dpkg-buildpackage -uc -us

One directory up from the CloudStack root dir, you will find:

cloudstack_4.4.0_amd64.changes
cloudstack_4.4.0.dsc
cloudstack_4.4.0.tar.gz
cloudstack-agent_4.4.0_all.deb
cloudstack-awsapi_4.4.0_all.deb
cloudstack-cli_4.4.0_all.deb
cloudstack-common_4.4.0_all.deb
cloudstack-docs_4.4.0_all.deb
cloudstack-management_4.4.0_all.deb
cloudstack-usage_4.4.0_all.deb

Of course, the community provides a repository for these packages and you can use it instead of building your own packages and putting them in your own repo. Instructions on how to use this community repository are available in the installation guide.

On CentOS/RHEL systems, add the following packages:

# yum -y install rpm-build
# yum -y install tomcat6
# yum -y install ws-commons-util
# yum -y install gcc
# yum -y install glibc-devel
# yum -y install MySQL-python

You can then build the packages by running ./packaging/centos63/package.sh from the cloudstack directory. The rpms will be located in ./dist/rpmbuild/RPMS/x86_64. CloudStack features some plug-ins (e.g., networking, storage) that may use software with licenses that may conflict with the Apache license or that may only be made available as binaries. These plug-ins are not distributed by Apache but can be built by users with the noredist flag (e.g., in CentOS, use package.sh -p noredist).