Getting Started

This guide will get you up and running with Brooklyn quickly. You will become familiar with launching Brooklyn from the command line, using the web interface and deploying an application (to a public cloud).

Before We Start

You are going to need some basic tools (that are normally installed by default). You will need curl, wget, tar, ssh and ssh-keygen.

Download Brooklyn

Download the Brooklyn distribution. This contains Brooklyn, ready to run.

Save the distro tgz file to your home directory ~/, or a location of your choice. (Other download options are available.)

Expand the tar.gz archive.

$ tar -zxf brooklyn-dist-0.6.0-dist.tar.gz

This will create a brooklyn-0.6.0 folder.

Let's setup some paths for easy commands.

$ cd brooklyn-0.6.0
$ BROOKLYN_DIR=$(pwd)
$ export PATH=$PATH:$BROOKLYN_DIR/bin/

A Quick Test Drive

Running Brooklyn now will launch the web interface, but there will be little to do, as we haven't configured any deployment locations or added a service catalog. Check your progress by running:

$ brooklyn launch

Brooklyn will output the address of the management interface:

... Started Brooklyn console at http://127.0.0.1:8081/ (link)

Stop Brooklyn with ctrl-c.

Setting up Locations and Applications

By default Brooklyn loads configuration parameters from ~/.brooklyn/brooklyn.properties and a service catalog from ~/.brooklyn/catalog.xml.

Create a .brooklyn folder in your home directory:

$ mkdir ~/.brooklyn

Note: ~/.brooklyn is an important directory, as this is where Brooklyn looks for configuration files and resources. It is not the same as the directory where Brooklyn is located ($BROOKLYN_DIR = ~/brooklyn-0.6.0, if you followed the commands above).

Next, set up the following default/template files in that directory:

brooklyn.properties: Download the template brooklyn.properties and place this in ~/.brooklyn. This is a standard java .properties file, which you can edit in your favourite text editor to add credentials for your favourite clouds.
catalog.xml: Download the template catalog.xml (also to ~/.brooklyn). This is a catalog of application blueprints. The example file contains some blueprints which will be automatically downloaded from the web if you run them. You may need to edit this file (text editor) to ensure that the links to the demo application .jar files are correct for your version of Brooklyn.

Finally, Brooklyn requires SSH keys to access your local machine, and to set-up and access cloud machines.

By default Brooklyn will look for an SSH key at ~/.ssh/id_rsa and ~/.ssh/id_dsa.

If you do not already have an SSH key installed, create a new id_rsa key:

$ ssh-keygen -t rsa -N "" -f ~/.ssh/id_rsa

Your SSH key (new or existing) must be added to your authorized_keys to allow Brooklyn to access localhost.

# _Appends_ id_rsa.pub to authorized_keys. Other keys are unaffected.
$ cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys

(MacOSx user?: In addition to the above, enable 'Remote Login' in System Preferences > Sharing.)

(Existing or custom SSH keys?: If you wish to use an existing key SSH, or an SSH key that has a passphrase, or a location other than ~/.ssh, you can specify this in brooklyn.properties using brooklyn.location.localhost.privateKeyFile and brooklyn.location.localhost.privateKeyPassphrase)

3-2-1 Go!

Now when we launch Brooklyn:

$ brooklyn launch

Brooklyn will use the brooklyn.properties and catalog.xml files. The new locations will be available in the management interface at localhost:8081, and the blueprints from the service catalog will be available for deployment.

The "Create Application" dialog will open automatically when you first login. (If not, click "Add Application".)

Select the "Demo Web Cluster with DB", then "Next".

For the time being we'll use "localhost" as our deployment location. Click "Finish" and the Create Application dialog will close.

You will see Brooklyn create an Application with status "STARTING".

It make take some time for Brooklyn to download everything and configure the application's initial topography, so lets have a look at the web interface while we wait.

Exploring the Hierarchy of Web Cluster with DB

Clicking on an application listed on the home page, or the Applications tab, will show you the management hierarchy.

Exploring the hierarchy tree, you will see that the Demo Web Cluster with DB is a classic three tier web application, consisting of a ControlledDynamicWebAppCluster and a MySqlNode. The ControlledDynamicWebAppCluster contains an nginx software loadbalancer (NginxController) and as many JBoss7Servers as required (it autoscales).

Clicking on the ControlledDynamicWebAppCluster and then the Sensor tab will show if the cluster is ready to serve and, when ready, will provide a web address for the front of the loadbalancer.

If the service.isUp, you can view the demo web application in your browser at the webapp.url.

Testing the Policies

Brooklyn at its heart is a policy driven management plane. After codifying your technical and business policies, Brooklyn can implement them automatically.

Brooklyn's policies work autonomically: they are like a nervous system. The need for action, and the correct action to take, are observed, decided and implemented as low down the management hierarchy (as close to the 'problem') as possible.

The Web Cluster with DB demo comes pre-configured with an AutoScalerPolicy, attached to the cluster of JBoss7 servers and a targets policy attached to the loadbalancer. You can observe policies this in the management console using the Policy tab of the relevant entity (e.g. DynamicWebAppCluster shows the AutoScalerPolicy.

The cluster autoscaler policy will automatically scale the cluster up or down to be the right size for the current load. ('One server' is the minimum size allowed by the policy.) The loadbalancer will automatically be updated by the targets policy as the cluster size changes.

Sitting idle, your cluster will only contain one server, but you can check that the policy works using a tool like jmeter pointed at the nginx endpoint to create load on the cluster.

Brooklyn's policies are configurable, customizable, and can be completely bespoke to your needs. As an example, the AutoScalerPolicy is tunable, can be applied to any relevant metric (here, average requests per second), and is a sufficiently complex piece of math that it understand hysteresis and prevents thrashing.

REST API Browser

Click on the Script tab at the top of the web interface and select REST API. Brooklyn supports a REST, JSON and Java API to allow you to integrate it with (pretty much) anything.

The Script tab allows you to explore the API.

Try: Locations > GET:/v1/locations > Try it out!

You will be presented with a json response of the currently configured locations.

Stopping the Web Cluster with DB

By now the Web Cluster with DB should have started, and you will have been able to view the application in your browser.

Returning to the "Applications" tab, and selecting the WebClusterDatabaseExample's Effectors, we can Invoke the Stop Effector. This will cleanly shutdown the Web Cluster with DB example.

Deploying to Cloud

The user experience of using the service catalog to deploy an application to a cloud is exactly the same as deploying to localhost. Brooklyn transparently handles the differences between locations and environments.

Return to the Create Application dialog, reselect the Web Cluster with DB Demo, and select your public cloud of choice.

(If you have added credentials to your brooklyn.properties file,) Brooklyn will request VMs in the public cloud, provision the application components, and wire them together, returning a cloud IP from which the demo application will be available.

Remember to invoke the stop method when you are finished.

Closing Thoughts

This guide has shown two aspects of Brooklyn in action: policy driven management capability, and the service catalog/web interface. Additionally, we briefly explored Brooklyn's API.

It is worth noting that Brooklyn could be included as a library in your own applications (no command line required), or it could be used just as a management plane (without a service catalog).

During this guide we have been using Brooklyn's web interface, but Brooklyn's APIs are extensive and powerful. Brooklyn can be used with (controlled by and make data available to) your existing management UI. Brooklyn is intended to complement (not replace) your existing technologies and tooling.

The Elastic Web Cluster Example page details how to build the demo application from scratch. It shows how Brooklyn can complement your application with policy driven management, and how an application can be run without using the service catalog.