Getting started with the CloudFoundry Client in Ubuntu

(the client)

I'm pleased to introduce a powerful new cloud computing tool available in Ubuntu 11.10 (Oneiric), thanks to the hard work of my team (Brian Thomason, Juan Negron, and Marc Cluet), as well as our partners at VMWare -- the cloudfoundry-client package, ruby-vmc and it's command line interface, vmc.

CloudFoundry is a PaaS (Platform as a Service) cloud solution, open sourced earlier this year by VMWare.  Canonical's Systems Integration Team has been hard at work for several weeks now packaging both the client and server pieces of CloudFoundry for Ubuntu 11.10 (Oneiric).  We're at a point now where we'd love to get some feedback from early adopting Oneiric users on the client piece.

PaaS is a somewhat new area of Cloud Computing for Ubuntu.  Most of our efforts up to this point have been focused on IaaS (Infrastructure as a Service) solutions, such as Eucalyptus and OpenStack.  With IaaS, you (the end user of the service) run virtual machine instances of an OS (hopefully Ubuntu!), and build your solutions on top of that infrastructure layer.  With PaaS, you (the end user of the service) develop applications against a given software platform (within a few constraints), but you never actually touch the OS layer (the infrastructure).

CloudFoundry is one of the more interesting open source PaaS offerings I've used lately, supporting several different platforms already (Ruby, NodeJS, Spring Java), and several backend databases (MySQL, MongoDB, Redis), and support for other languages/databases under rapid development.

VMWare is hosting a free, public CloudFoundry server at cloudfoundry.com (though you need to request an invite; took mine less than 48 hours to be arrive).  However, we're rapidly converging on a cloudfoundry-server package in a PPA, as well as an Ensemble formula.  Stay tuned for a subsequent introduction on that, and a similar how-to in the next few days...

In the mean time, let's deploy a couple of basic apps to CloudFoundry.com!

Installing the Tools

The tool you need is vmc, which is provided by the ruby-vmc package.  We in the Canonical SI Team didn't find that package name very discoverable, so we created a meta package called cloudfoundry-client.

sudo apt-get install cloudfoundry-client

Setting the Target

First, you'll need to set the target server for the vmc command.  For this tutorial, we'll use VMWare's public server at cloudfoundry.com.  Very soon, you'll be able to target this at your locally deployed CloudFoundry server!

$ vmc target https://api.cloudfoundry.com
Succesfully targeted to [https://api.cloudfoundry.com]

Logging In

Next, you'll log in with your credentials.  As I said above, it might take a few hours to receive your credentials from CloudFoundry.com, but once you do, you'll log in like this:

$ vmc login
Email: kirkland@example.com
Password: **********
Successfully logged into [https://api.cloudfoundry.com]

Deploying Your First Applications

Your friendly Canonical Systems Integration Team have developed and tested a series of simple hello-world applications in each of CloudFoundry's supported languages.  Each of these applications simply print a welcome message, and display all of the environment variables available to the application.  The latter bit (the environment variables) are important, as several of them, those starting with VCAP_*, serve as a sort of metadata service for your applications.

Our sample apps are conveniently placed in /usr/share/doc/ruby-vmc/examples.

Deploying a Ruby Application

To deploy our sample Ruby application:

$ cd /usr/share/doc/ruby-vmc/examples/ruby/hello_env
$ vmc push
Would you like to deploy from the current directory? [Yn]: y
Application Name: example101
Application Deployed URL: 'example101.cloudfoundry.com'? 
Detected a Sinatra Application, is this correct? [Yn]: y
Memory Reservation [Default:128M] (64M, 128M, 256M, 512M or 1G) 128M
Creating Application: OK
Would you like to bind any services to 'example101'? [yN]: n
Uploading Application:
  Checking for available resources: OK
  Packing application: OK
  Uploading (0K): OK   
Push Status: OK
Staging Application: OK                                                         
Starting Application: OK                                                        

And now, I can go to http://example101.cloudfoundry.com/ and see my application working.

Deploying a NodeJS Application

Next, I'm going to deploy our sample NodeJS application:

$ cd /usr/share/doc/ruby-vmc/examples/nodejs/hello_env
$ vmc push
Would you like to deploy from the current directory? [Yn]: y
Application Name: example102
Application Deployed URL: 'example102.cloudfoundry.com'? 
Detected a Node.js Application, is this correct? [Yn]: y
Memory Reservation [Default:64M] (64M, 128M, 256M, 512M or 1G) 64M
Creating Application: OK
Would you like to bind any services to 'example102'? [yN]: n
Uploading Application:
  Checking for available resources: OK
  Packing application: OK
  Uploading (0K): OK   
Push Status: OK
Staging Application: OK                                                         
Starting Application: OK                                                       

And now, I can go to http://example102.cloudfoundry.com/ and see my simple NodeJS application running.

Deploying a Java Application

Now, we'll deploy our sample Java application.

$ cd /usr/share/doc/ruby-vmc/examples/springjava/hello_env

As with anything that involves Java, it's hardly as simple as our other examples :-) First we need to install the Java tool chain, and compile our jar file. I recommend you queue this one up and go brew yourself a gourmet pot of coffee. (You might even make it to Guatemala and back.) Also, note that we'll make a copy of this directory locally, because the maven build process needs to be able to write to the local directory.

$ sudo apt-get install openjdk-6-jdk maven2
...
$ cd $HOME
$ cp -r /usr/share/doc/ruby-vmc/examples/springjava .
$ cd springjava/hello_env/
$ mvn clean package
...
$ cd target
$ vmc push
Would you like to deploy from the current directory? [Yn]: y
Application Name: example103
Application Deployed URL: 'example103.cloudfoundry.com'?  
Detected a Java Web Application, is this correct? [Yn]: y
Memory Reservation [Default:512M] (64M, 128M, 256M, 512M or 1G) 512M
Creating Application: OK
Would you like to bind any services to 'example103'? [yN]: n
Uploading Application:
  Checking for available resources: OK
  Packing application: OK
  Uploading (4K): OK   
Push Status: OK
Staging Application: OK                                                         
Starting Application: OK

All that for a Java hello-world ;-) Anyway, I now have it up and running at http://example103.cloudfoundry.com/.

Deploying a More Advanced Application

Hopefully these hello-world style applications will help you get started quickly and effortlessly deploy your first CloudFoundry apps. But let's look at one more complicated example -- one that requires a database service!

In digging around the web for some interesting NodeJS applications, I came across the Node Knockout programming competition. I found a few interesting apps, but had a lot of trouble tracking down the source for some of them. In any case, I really liked a shared-whiteboard application called Drawbridge, and I did find its source in github. So I branched the code, imported it to bzr and made a number of changes (with some awesome help from my boss, Zaid Al Hamami). I guess that's an important point to make here -- I've had to do some fairly intense surgery on pretty much every application I've ported to run in CloudFoundry, so please do understand that you'll very likely need to modify your code to port it to the CloudFoundry PaaS.

In any case, let's deploy Drawbridge to CloudFoundry!

$ cd $HOME
$ bzr branch lp:~kirkland/+junk/drawbridge
$ cd drawbridge
$ vmc push
Would you like to deploy from the current directory? [Yn]: y
Application Name: example104
Application Deployed URL: 'example104.cloudfoundry.com'? 
Detected a Node.js Application, is this correct? [Yn]: y
Memory Reservation [Default:64M] (64M, 128M, 256M or 512M) 128M
Creating Application: OK
Would you like to bind any services to 'example104'? [yN]: y
Would you like to use an existing provisioned service [yN]? n
The following system services are available::
1. mongodb
2. mysql
3. redis
Please select one you wish to provision: 2
Specify the name of the service [mysql-4a958]: 
Creating Service: OK
Binding Service: OK
Uploading Application:
  Checking for available resources: OK
  Processing resources: OK
  Packing application: OK
  Uploading (77K): OK   
Push Status: OK
Staging Application: OK                                                         
Starting Application: OK

Note that vmc provisioning and linked a new MySQL instance with the app!

Now, let's see what Drawbridge is all about. Visiting http://example104.cloudfoundry.com in my browser, I can work on a collaborative whiteboard (much like Gobby or Etherpad, except for drawing pictures). Brian Thomason helped me create this Pulitzer-worthy doodle:

Listing Apps and Services

Now that I have a few apps and services running, I can take a look at what I have running using a few basic vmc commands.

Here are my apps:

$ vmc apps 
+-------------+----+---------+-----------------------------+-------------+
| Application | #  | Health  | URLS                        | Services    |
+-------------+----+---------+-----------------------------+-------------+
| example102  | 1  | RUNNING | example102.cloudfoundry.com |             |
| example103  | 1  | RUNNING | example103.cloudfoundry.com |             |
| example101  | 1  | RUNNING | example101.cloudfoundry.com |             |
| example104  | 1  | RUNNING | example104.cloudfoundry.com | mysql-4a958 |
+-------------+----+---------+-----------------------------+-------------+

And my services (available and provisioned):

$ vmc services 
============== System Services ==============
+---------+---------+-------------------------------+
| Service | Version | Description                   |
+---------+---------+-------------------------------+
| redis   | 2.2     | Redis key-value store service |
| mongodb | 1.8     | MongoDB NoSQL store           |
| mysql   | 5.1     | MySQL database service        |
+---------+---------+-------------------------------+
=========== Provisioned Services ============
+-------------+---------+
| Name        | Service |
+-------------+---------+
| mysql-4a958 | mysql   |
| mysql-5894b | mysql   |
+-------------+---------+

In this post, I've demonstrated a couple of frameworks (Ruby/Sinatra, NodeJS, Spring/Java), but here I can see that there are several others supported:

$ vmc frameworks 
+---------+
| Name    |
+---------+
| rails3  |
| sinatra |
| lift    |
| node    |
| grails  |
| spring  |
+---------+

Scaling Instances

One of the huge advantages of PaaS deployment is how trivial application resource scalability can actually be. Let's increase the memory available to one of these applications:

$ vmc mem example101
Update Memory Reservation? [Current:128M] (64M, 128M, 256M or 512M) 512M
Updating Memory Reservation to 512M: OK
Stopping Application: OK
Staging Application: OK                                                         
Starting Application: OK   
$ vmc stats example101
+----------+-------------+----------------+--------------+--------------+
| Instance | CPU (Cores) | Memory (limit) | Disk (limit) | Uptime       |
+----------+-------------+----------------+--------------+--------------+
| 0        | 0.1% (4)    | 16.9M (512M)   | 40.0K (2G)   | 0d:0h:1m:22s |
+----------+-------------+----------------+--------------+--------------+

Done! Wow, that was easy!

Now, let's add some additional instances, as I suspect they'll crash once my billions of blog readers start pound Drawbridge, maybe it'll stay up a bit longer :-)

$ vmc instances example104 4
Scaling Application instances up to 4: OK
$ vmc stats example104
+----------+-------------+----------------+--------------+---------------+
| Instance | CPU (Cores) | Memory (limit) | Disk (limit) | Uptime        |
+----------+-------------+----------------+--------------+---------------+
| 0        | 0.0% (4)    | 21.0M (128M)   | 28.0M (2G)   | 0d:0h:19m:33s |
| 1        | 0.0% (4)    | 15.8M (128M)   | 27.9M (2G)   | 0d:0h:2m:38s  |
| 2        | 0.0% (4)    | 16.3M (128M)   | 27.9M (2G)   | 0d:0h:2m:36s  |
| 3        | 0.0% (4)    | 15.8M (128M)   | 27.9M (2G)   | 0d:0h:2m:37s  |
+----------+-------------+----------------+--------------+---------------+

In Conclusion

I hope this helps at least a few of you with an introduction to PaaS, CloudFoundry, and the CloudFoundry-Client (vmc) in Ubuntu.  As I said above, stay tuned for a post coming soon about hosting your own CloudFoundry-Server on Ubuntu!

:-Dustin