Logo Computer scientist,
engineer, and educator
• Articles • Articles about computing • Articles about software development • Apache integration software

Deploying a Camel route on a Fabric8 cluster, step by step

This article describes step-by-step how to set up a cluster of three servers running Fabric8, and deploy on them a simple "Hello, World" Camel application. The servers will be centrally-managed from a single point, once the initial software installation has been performed, but each server will run independently.

If you are not familiar with the Fabric8 architecture at all, then I would recommend that you read Deploying an OSGi application on Apache Fabric8, from the ground up. If you're not familiar with OSGi, either, then before reading that I would recommend Creating OSGI bundles and services from the ground up using Apache Karaf. In this demonstration I'll be using the Camel example from my article Using the fabric8 Maven plugin to deploy a Camel route to a fabric, which also describes how to use the Maven Fabric8 plugin to deploy code to the fabric's Maven repository and create a new Fabric profile. I will describe how to perform the necessary steps in this article, but I won't describe any of the background again here.

Apart from the topics mentioned above, I assume some basic knowledge of clustered server operation.

Note:
The steps in this article have been tested on Fabric8 1.1.0 Beta 6. I know from experience that earlier versions will not work.

Preparing the machines

For experimental purposes, a Fabric8 cluster can be set up on virtual machines. However, network configuration can be quite challenging in such an environment, so I'm assuming three separate physical hosts, each with its own fixed IP number.

Note:
I tested the procedure in this article on a cluster of three machines running Ububtu Linux 12.1, although I don't foresee any problems with other Linux versions. Windows uses different methods of host naming and firewall configuration which, I'm afraid, are beyond my expertise, so I only give general comments.

Use cabled networking, if possible

Because Fabric8 is so sensitive to full and unrestricted network connectivity, I would suggest using wired networking if possible, and with the clustered machines connected to the same hub or switch. I'm sure that in a production system this would be the preferred approach anyway; but even for testing, removing wireless networking results in one fewer potential problem to worry about.

Configuring hostnames and IPs

It is absolutely crucial that each machine in the cluster knows each other machine by the same hostname and IP number. What's more, if you make mistakes in this area whilst setting up, it's hard to recover, and generally easier just to delete the entire Fabric8 software installation and start again.

If you're using DNS name resolution then its easy to get this right — just make sure each machine has an entry in DNS. If you're using hosts files, then it's important that each machine has exactly the same hosts entries. Each machine should have a hostname that is not localhost, and that hostname should map onto a real IP number, not a loopback.

My three machines are called root, toot, and zoot, and the relevant entries in /etc/hosts, on all three machines are:

192.168.1.50 root 
192.168.1.200 toot
192.168.1.201 zoot
In a sense, the use of the name 'root' is a bit unfortunate, but it's the name that Fabric8 uses for the first container by default, so I decided to leave it. I've chosen to use Fabric8 container names that match the machine hostnames, simply to make it easy to find things. So the machine 'root' will host containers called 'rootXXX,' 'toot' will have 'tootXXX,' and so on. There's no technical reason to follow this convention, but you've got to have some kind of naming convention, if you have a large installation and want to preserve your sanity.
Note:
In the description that follows, all the administration apart from software installation is done from the machine called root.

If you're at all unsure about the naming, then ensure that each machine can ping each other machine using the names allocated.

Microsoft Windows, at least up to and including version 7, also provides a hosts file, and its format is as in Linux/Unix. However, it's fiddly to find, and is often subject to odd security constraints. The default location is c:\windows\system32\drivers\etc\hosts.

Disable firewalls

Fabric8 uses a fair number of IP ports for inter-container communication; and, of course, you'll probably want to connect a Web browser to the Web administration GUI (by default on port 8181). Some of the port numbers it uses are hard to guess, so I would suggest that for initial tests you disable firewalls completely. The method for doing this will vary from one Linux distribution to another. In most cases you should be able to use one (or more) of these:
# systemctl stop iptables.service
# sh /etc/init.d/iptables stop
# iptables -F
On Windows, you can shut down the firewall using the Control Panel application; some Linux distributions also provide a graphical tool for firewall management.

Installing and setting up Fabric8

Installing the software

All Fabric8 versions can be obtained here. Because the software is developing so rapidly, I would recommend using the latest version available.

Installation consists of unzipping the archive in any convenient directory. There is no particular reason to use the same directory on each machine in the cluster, but no particular reason not to, either.

Before starting Fabric, set the root container name in etc/system.properties:

karaf.name=something
It doesn't matter what these names are, so long as they are distinct. As I mentioned before, I find it helpful to set these names the same as the hostname.

Now you can run bin/fabric8 (or fabric8.bat on Windows) on each machine, and you should see the Karaf prompt:

Fabric8:karaf@root> 

Creating the fabric

The initial creation step should be done on one machine in the cluster. In this example, I am using the machine root.
Fabric8:karaf@root> fabric:create --zookeeper-password admin
The password you specify here will be used by other instances to join the cluster.

Joining the fabric

From each of the other machines in the cluster, use fabric:join to join them to the running cluster.
Fabric8:karaf@root> fabric:join --zookeeper-password admin root
The last argument here is the hostname 'root'. You can specify all the hostnames of the other cluster members here, if you are unsure which instances will be running at a given time. Note that the default port for inter-cluster communication is 2121; you don't need to give a port number when you join the fabric if that default has not been changed.
Note:
Creating and joining the cluster are one-time operations. Fabric8 remembers its cluster configuration, and a machine that is restarted will automatically attempt to rejoin the cluster when Fabric8 is restarted.
If the cluster is working correctly, then you should be able to point a Web browser at any instance in the cluster and see all the root containers in the cluster (which have the same names as the hostnames in this example):

screenshot

Creating containers

We now need to create a container on each machine to host the actual application — it's probably best not to use the top-level container for this. This administration can be done on any instance in the cluster; again, I am using root.
Fabric8:karaf@root> container-create-child root root1
Fabric8:karaf@root> container-create-child toot toot1
Fabric8:karaf@root> container-create-child zoot zoot1
If successful, the Web GUI should now show the top-level and child containers on the three machines:

screenshot

Note:
On Linux — but probably not on Windows — the process of installing Fabric8 and creating containers can be carried out entirely from one central point using container-create-ssh. This runs a script on the remote machine using ssh, that retrieves and unpacks Fabric8 into a directory $HOME/containers, and sets up a container. As well as requiring ssh server support on the remote machines, they also need curl, which is not always installed by default.
That's it: the cluster is now set up, and ready to deploy software.

Deploying and testing the application

The process of deployment in Fabric8 is to create a profile that defines what software is to be installed, and from where it is to be obtained, and then assign that profile to one or more containers. In this example, we will assign the profile to root1, zoot1, and toot1.

In this example I will use the same simple application as in the article Using the fabric8 Maven plugin to deploy a Camel route to a fabric so if you want to follow along, get the software from the Download section at the end of that article, and unpack it on any machine in the cluster. Again, I am working on the machine called 'root'.

The software is set up to use the Fabric8 Maven plugin to deploy the application. This will automatically create a profile called net.kevinboone.apacheintegration-camelfabrictest (be careful of the odd name — it is a minus (-), not a full-stop (.) before camelfabrictest). Because the Fabric8 installations are clustered, this profile will become available immediately on every instance in the cluster.

To deploy the software at the command prompt, change to the directory where you unpacked the bundle, and run:

$ mvn fabric8:deploy
From the Fabric8 console you should now be able to see that the profile is available:
Fabric8:karaf@root> profile-list | grep fabrictest
net.kevinboone.apacheintegration-camelfabrictest 0              karaf
The '0' here indicates that the profile is assigned, so far, to no containers; this number will increase when the profile is in use.

To install the software to a container, use container-change-profile. However, because the application is based on Camel, you will also need to assign the feature-camel profile at the same time, to ensure that the Camel software is available:

Fabric8:karaf@root> container-change-profile root1 feature-camel net.kevinboone.apacheintegration-camelfabrictest
Fabric8:karaf@root> container-change-profile zoot1 feature-camel net.kevinboone.apacheintegration-camelfabrictest
Fabric8:karaf@root> container-change-profile toot1 feature-camel net.kevinboone.apacheintegration-camelfabrictest
At this point, the Camel route should be running on each of the three instances. Because it doesn't do anything useful, the only way to be sure is to look in the log file for each of the containers root1, etc.
119 - org.apache.camel.camel-core - 2.13.1 | The message contains Hi from Camel (new)  at 2014-05-24 17:20:53
If necessary, you can remove the software from a container simply by changing its profile to something else, e.g., default:
Fabric8:karaf@root> container-change-profile root1 default
If you shut down a machine, then as soon as Fabric8 is restarted, it should automatically rejoin the cluster and begin to run the application.

Summary

In this article I explained how to install Fabric8 on a three-machine cluster, and deploy an application onto each machine in the cluster. The same procedure applies, more or less, to larger clusters, and to more complex applications: create containers, create profiles defining the software to be installed, assign those profiles to the containers.

Download

The source code for this article can be found in the Download section of my article Using the fabric8 Maven plugin to deploy a Camel route to a fabric.
Copyright © 1994-2013 Kevin Boone. Updated May 24 2014