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

Depolying a Camel-based application to a Fabric8 cluster hosted on an OpenShift cloud

This article describes, and demonstrates the use of, the OpenShift JBoss Fuse cartridge, which allows integration applications based on Apache technologies such as Camel and CXF to be hosted in a cloud environment. It provides a very brief overview of the OpenShift architecture and the Fuse cartridge, followed by a number of step-by-step exercises that demonstrate how to set up a Fabric8 cluster on OpenShift, deploy an application to it, and manage it using Web-based and command-line tools.

In this article I assume no particular prior knowledge of OpenShift or cloud computing, although my description of the OpenShift technology will necessarily be brief (readers who want a more detailed exposition of the technical implementation could look here.) However, I do assume some experience with Fuse/Fabric8. In particular, I expect that the reader will understand:

You don't need to know much, or indeed anything, about Apache Camel, XLST stylesheet transformation, or servlets to be able to follow the exercises in this article, although the sample application is based on these technologies. If you're interested in finding out more about such things, there are many more articles in my Apache integration pages.

Note:
There are many screenshots in this article, shown reduced in size for reasons of space. To see the full-size versions, please use your Web browser's facility to show the images outside the page

OpenShift concepts

This section outlines the key OpenShift concepts of Application, Cartridge, and Gear. For a more detailed description of the OpenShift architecture, please refer to the OpenShift documentation.

OpenShift is an application hosting platform, with a particular focus on Web applications. Red Hat offers a public service — OpenShift Online — which is available free-of-charge for small deployments, and by subscription for larger ones, but the OpenShift infrastructure itself is also available for enterprise deployments. OpenShift Online and OpenShift Enterprise are both based on the open-source OpenShift Origin project.

The key feature of OpenShift, as with any Platform-as-a-Service offering, is that it separates the administration of the platform from the administration of the applications deployed on it.

The administrative kernel of OpenShift is the broker (not to be confused with a message broker). The broker provides an administrative interface to OpenShift applications (both Web-based and command-line), and allocates applications to particular physical hosts.

In OpenShift, a gear is the basic unit of hosting. In implementation, a gear is a Linux user account with a certain amount of resource (disk, RAM, etc) allocated to it. Each gear has a virtual IP interface to connect it with the OpenShift network infrastructure, and ordinary Linux security policies (SELinux) isolate one gear from another.

A particular OpenShift node (real or virtual machine) may be hosting a large number of gears, and application developers ought not to rely on any specific geographical location of their applications (particularly on the public service).

Administrators need to understand, but developers largely do not, that a gear is not a container or a true virtual machine. That might change in future but, right now, administrators should appreciate that gears do not have any exclusivity of access to system resources — not even an illusion of exclusivity provided by virtualization. Instead, a particular gear is rooted at a particular filesystem location, and shares access to common system directories (/proc, /usr, etc) with other gears.

Because a gear is a user account, administrators and developers can log into it using SSH, copy files in and out of it, and start and stop processes, using ordinary Linux techniques. In general, such operations are discouraged, and it would be a bad idea to deploy an application on OpenShift that relied on manipulations of this sort. However, logging into the gear can be very useful for troubleshooting.

An Application is whatever code runs on the gear. The application usually consists of some sort of runtime container (e.g., an application server or webserver), and the specific application code contributed by the application developers. An application is assigned to at least one gear of some specific size; it will have at least one operating system process, but possibly more.

A cartridge is a recipe for creating the application's runtime environment. In implementation a cartridge is a simple text file (a YML file), which contains entries that indicate to the OpenShift broker where to obtain the software needed to build the runtime environment. The cartridge interfaces with OpenShift by means of hooks — scripts that install the runtime, tear it down, start it, configure it, and stop it.

Cartridges have been created for many different runtime environments. Many of these are Java-based, but there are cartridges for Perl, PhP, WordPress, and others. The first step in creating an OpenShift application is generally to select a cartridge. However, there is a blank, 'DIY' cartridge that can be populated with whatever runtime components are required.

Overview of the Fuse cartridge

The Fuse cartridge offers an installation of Fabric8 that can be applied to an OpenShift gear. In many ways the Fuse cartridge is atypical of OpenShift cartridges — it does not use git for application deployment, for example, as most cartridges do. This could be a little confusing to developers who are familiar with other Java-based OpenShift cartridges — Tomcat, Wildfly, etc. However, the Fuse cartridge will look very familiar to developers and administrators who are familiar with Red Hat JBoss Fuse 6.1 or Fabric8, particularly those who mostly use the Web console for administration. Although OpenShift provides a sophisticated command-line management tool (rhc), there is less scope for use of this tool with the Fuse cartridge than there is for most other cartridges. This is because such tasks as scaling and managing application containers is carried out largely by Fabric8's own administration services (Fabric8 is, after all, a system for managing containers), rather than by the OpenShift broker.

At the time of writing, the OpenShift Fuse cartridge available on the public OpenShift service is aligned with version 6.1.0 of the RedHat JBoss Fuse product, which is based on version 1.0.0 of Fabric8.

About the exercises in this article

The exercises in this article are based around a simple Camel application, which provides a weather forecast for the London area. The application works by periodically invoking a weather feed provided by the BBC. This feed returns XML data, which the application transforms into HTML using an XSLT stylesheet. Requests made by a Web browser invoke the Camel servlet, which invokes a Java class that reads and caches the HTML data.

This application is perhaps not typical of Fabric8/Fuse applications, but has the advantage of being very easy to test, and requires no supporting infrastructure (other than the BBC service).

The exercises demonstrate the following features of Fabric8 on OpenShift:

  • Registering for an OpenShift online account (if necessary) and configuring certificate-based SSH authentication for access to the gears
  • Installing Fabric8 through the Fuse cartridge
  • Using OpenShift-specific methods for building a Fabric8 cluster (of just two containers, in this example)
  • Deploying an application to the cluster using the Fabric8 Maven deployment plugin (which, as you'll see, is no different from deploying code this way outside of OpenShift
  • Using the rhc tool for operations such as port forwarding
In practice, it will usually not be desirable to host an application on the same Fabric8 instance that is providing administration services to the cluster. So in these exercises we will first create a Fabric8 container for the administration console, and then another container on a different gear to host the application itself.

Exercise prerequisites

To be able to carry out the exercises in this article, you will need the following software:
  • Maven
  • An ssh client
  • Java 7 JDK (not just a Java runtime)
The rhc command-line tool, used in the later exercises, has additional pre-requisites, described in the relevant section.

For simplicity, I all the steps in this article are documented for a Linux system. OpenShift is Linux-based, but there is no reason why development and administration have to be done on a Linux system — the tools required are available for most platforms. Nevertheless, I have to choose something to document the exercises, and Linux is what I'm most familiar with. Where practiable, I provide links to instructions on the use of other platforms.

Exercise 1: prepare to use OpenShift

1.1 Sign up for an OpenShift online account (if necessary)

If you don't have an OpenShift installation to experiment with, you can sign up for the free public service at OpenShift on-line: point your Web browser at http://openshift.redhat.com, and click on the "SIGN UP" button. The free service provides three small gears which is (just about) sufficient resource to run the exercise in this article.

If you want to use a different OpenShift service then this exercise should still work. However, because the Fuse cartridge is a relatively new thing, you might find that it isn't installed already. In that case you'll need to set up the cartridge using its definition file on github, as explained later.

1.2 Generate and upload public key

Overview

OpenShift uses SSH with client certificate authentication for all administration operations other than those that use the Web console. You will need to create an SSH client certificate and upload the public key to OpenShift for each workstation that you use for administering your OpenShift applications using command-line tools, including looging into your gears using SSH. You don't necessarily need to do this for administering OpenShift using the Web console, or for deploying applications using the Maven plug-in. In fact, there is less good reason to use command-line tools with the Fuse cartridge than with other OpenShift cartridges, as discussed later. Nevertheless, it's useful to be able to do so, at least for education purposes.

The following brief description is for Linux systems. Other methods for obtaining and registering a public key, which are suitable for other plaforms, are outlined on the OpenShift Web site. Note that setting up the rhc command-line tool will also create and upload a public key, as will be discussed later. However, this manual procedure is very quick and convenient, particularly for systems where there is no need to install rhc.

Generate the client certificate

Use ssh-keygen as follows:
$ ssh-keygen -t rsa
This will create the files $HOME/.ssh/id_rsa and $HOME/.ssh/id_rsa.pub. The latter contains the public, which you will need to provide to OpenShift using its management console.

Upload the public key

Open the OpenShift console using a Web browser, log in, and select the Settings tab. The top section should show a list of installed public keys (which will probably be empty if this is a new OpenShift account):


screenshot

Click "Add a new key...", and then paste in the contents of id_rsa.pub. Give the key a meaningful name that identifies the machine where it was created, as you might need to delete public keys later, and it's hard to identify the source of a public key just from its contents.

Exercise 2: Create the Fuse/Fabric cluster on OpenShift

The first application (that is, first installation of the Fuse cartridge) will host the administration console only. A second installation of the cartridge will host the application itself, but that installation will be performed using the Fabric8 administration console, rather the OpenShift console.

2.1 Create the first application from the Fuse cartridge

Go back to the start page of the OpenShift Online Web site (or the start page for whichever other OpenShift service you're using). If you have not yet created any application, click the link "Create your first application now". If you already have applications, click "Add Application..."

If you're using the public OpenShift service, the Fuse cartridge should be automatically available from the list of cartridges. In that case, just select it from the list:


screenshot

If you're working on an OpenShift installation that does not have the Fuse cartridge pre-installed, you can tell OpenShift to install it from the cartridge specification YML file, which is currently held on github. From the list of cartridges, go to the "Code Anything" section (probably at the bottom of the page) and enter the github URL https://raw.github.com/jboss-fuse/fuse-openshift-cartridge/jboss-fuse-6.1.x-379/metadata/manifest.yml. Then click Next.


screenshot

In either case, you should then move on to the next stage.

2.2 Enter basic application data

At this stage you'll need to enter a name for application and, optionally select a gear size. The application name will become the first part of the application's Web URL; the rest of the URL is derived from the name of the account.

I have unimaginatively chosen the name "fuse" here:


screenshot

Ideally, if you can select a gear size greater that "Small" you probably should but, since this particular gear will only be used for administration, it's not as important here as it is for the gears that will host applications.

It may take a little while for the gear to be created; eventually you should see the following screen:


screenshot

The Console Password is what you'll need to log into the administration console, and to deploy applications using the Maven plugin, so make a note of that. Naturally, you wouldn't put it up on a public Web site as I have here :)

2.3 Check application status

In the OpenShift Web console you can click the Application tab, and you should see that an application called fuse has been created. Click on this application name to see the status of the application:


screenshot

On this page the "Source Code" entry is the URL of the cartridge git repository. With most cartridges, this repository can have code pushed to it, which will be built and deployed by the cartridge. However, this git repository has no part to play in the Fuse cartridge. Fuse (or, rather, Fabric8) does use git, but it's for storing configuration, not code, and this use of git is not (at present) connected with the OpenShift cartridge.

Click the link "Want to log into your application?" This will expand to show the ssh command-line that you'll need to log into your gear (should you need to). The user ID will be a long, randomly-generated string, so the ssh command will be of the form:

ssh {long_string}@fuse-kevinboone.rhcloud.com
If you have access to an SSH client, it's worth checking that you can log into the gear at this point because, among other things, this will confirm that you have uploaded your public key correctly.


screenshot

2.4 Open the administration console

The URL that you gave when you created the application becomes the URL of the adminstration console. Enter that URL in a Web browser now. In the menu bar at the very top of the Window is a drop-down menu that can select between "Fabric" and "Container" perspective. Select "Fabric" perspective if it is not already selected, and you should see that one Fabric8 container has been created (it's the one you're currenly looking at) and it is running.


screenshot

2.5 Create a new container

On the container list page on the Fabric8 administration console, click the button "+Create". On the Create New Container page, select the Container Type "openshift" (none of the other possible settings will work in an OpenShift environment).

The new container is created by installing the Fuse cartridge on a new OpenShift gear. This operation is mediated by the OpenShift broker, which is why you need to enter your OpenShift service credentials to create the new container. If possible, choose a gear size larger than "small" here (this will not be allowed on the free service).

I have unimaginatively called the new container test1:


screenshot

If you now return to the OpenShift console, and look at the summary of applications (click the Applications tab), you should see that a new OpenShift application has been created, whose name matches the container name. Notice that the cartridge type is the same as that of the container that you created initially.


screenshot

Exercise 3: Deploy and test a simple application on OpenShift

This exercise will use the Maven deployment plug-in, which pushes code to the Fabric8 Maven proxy, and creates a new profile in the repository. There is nothing OpenShift-specific about this process, which should be entirely familiar to anybody familiar with developing for Fabric8.

3.1 Deploy the application as a Fabric8 profile

Obtain and build the sample application

Obtain the application source code bundle from here. Unpack this application into any convenient directory, and check that you can build it using Maven:
$ mvn package
The first build will probably take some time, as Maven will need to retrieve a heap of dependencies and populate its local repository. All being well, you should end up with a file target/londonweather-0.0.0.1.jar; however, this file won't be used directly for deployment.

Configure the Maven plug-in's fabric credentials

To deploy to the fabric you will need to specify the credentials for the administration container. These settings are usually stored in $HOME/.m2/settings.xml:
 <servers>
    <server>
      <username>admin</username>
      <password>NSuvxke44rr7</password>
      <id>fabric8.upload.repo</id>
    </server>
 </servers>
Note that if this file does not exist, then the Fabric8 deployment plugin will create it, and prompt for the password. However, if it does exist, and you've used the deployment plugin for some other Fabric8 installation, it won't overwrite the credentials automatically — you'll need to edit the file.

Specify the fabric administration server in pom.xml

Edit the pom.xml file to indicate the URL of your administration container:
 <jolokiaUrl>http://fuse-kevinboone.rhcloud.com/jolokia</jolokiaUrl>
Note that we're using the default HTTP port 80 here, although the container will not be listening on that port. The OpenShift reverse proxy infrastructure takes care of mapping conventional HTTP port numbers to whatever ports the cartridge is using for HTTP (typically 8080).

Deploy as a Fabric8 profile

Use this Maven command:
$ mvn fabric8:deploy
The profile created by this process will have by default a name derived from the Maven coordinates of the application (as specified in pom.xml). In this case, the profile name will be net.kevinboone.apacheintegration-londonweather (this name is shown with initial capital letters in the administration console).

Deploy and run the application by assigning the profile to a container

In the Fabric8 console, go to the container list page and then select the container test1. In the section Associated Profiles click "+Add" then scroll down the list of profiles to find Net.Kevinboone.Apacheintegration, and check the box alongside londonweather. Click the Add button.


screenshot

This will add the profile, including its application code, to the container test1, and start the application bundles. The process should be relatively fast in this simple example, as the application has few dependencies. However, in practice there might be a delay here as dependencies are downloaded.

Test the application using a browser

The application exposes a Web interface at the URL /camel/londonweather. Test this by pointing a browser at that URL on your test1 container. In my case the full URL is http://test1-kevinboone.rhcloud.com/camel/londonweather. You should see output like this:


screenshot

Exercise 4: Manage the OpenShift cluster using the rhc command-line tool

In general, the command-line tool is less useful with the Fuse cartridge than with most other cartridge types. The reason for this is that one of the most common operations, creating new gears with specific characteristics, will usually be more easily dealt with use Fabric8-specific administration techniques. However, there are few features that make it worth knowing how to use the command-line tool, some of which are demonstrated in this section.

4.1 Obtain the rhc tool

In the examples that follow, I assume that you will be running rhc on a Red Hat Linux system (RHEL, Fedora). However, versions are available for most platforms. For full details on installing this tool, see here. On most Red Hat Linux systems, you should just be able to do
$ sudo yum install rubygem-rhc
rhc is a Ruby application, so it has the Ruby runtime environment as a dependency. yum should take care of installing Ruby and other dependencies automatically. On other platforms you'll probably need to obtain Ruby explicitly, and then use it to obtain rhc.

It's worth bearing in mind that the version of rhc in the standard repositories for RHEL versions earlier than Fedora 19 is likely to be quite out-of-date, and you might be better to install manually as described in the documentation referenced earlier.

4.2 Configure the rhc tool

rhc stores a lot of configuration, presumably so it doesn't need a whole host of command-line arguments each time you run it. To configure it for the first time, just run:
$ rhc setup 
The configuration is stored in $HOME/.openshift/express.conf To set up rhc to use a particular OpenShift broker, use the form
$ rhc setup --server {openshift_broker_hostname}
Note that rhc setup will create and uplod a public key on compatible systems, but you might already have done this (it won't hurt if it gets done again).

4.3 Use rhc for basic administration operations

A common use for rhc is to tail the container log file, that is, to display new log output as it is generated. Do this by using
$ rhc tail {application_name}
For example:


screenshot

Note that this operation does not require any credentials, nor does the OpenShift broker or container location need to be specified — the broker hostname was configured and stored when rhc was set up, and the broker knows where the applications are deployed.

4.4 Use rhc to get to the console's SSH port

It can be useful to get into the Fuse console using SSH, and use commands like profile-edit to manage the installation. However, the SSH port is not exposed to the Internet. You can get around this problem — and many similar problems — using the port forwarding mechanism offered by rhc.

First, log into the fuse application using SSH, as described earlier (hint: use the OpenShift console to find the SSH command line). Once logged in, examine the file fuse/fabric8-karaf-1.0.0.redhat-379/etc/org.apache.karaf.shell.cfg — you need the line:

org.apache.karaf.shell.cfg:sshPort=23101
Of course, your port number might be different.

Set up the port forwarding apparatus using rhc:

$ rhc port-forward fuse

To connect to a service running on OpenShift, use the Local address

Service Local                OpenShift
------- --------------- ---- ----------------
java    127.0.0.1:15001  =  127.5.68.1:15001
java    127.0.0.1:16099  =  127.5.68.1:16099
java    127.0.0.1:23101  =  127.5.68.1:23101
java    127.0.0.1:3128   =  127.5.68.1:3128
java    127.0.0.1:8080   =  127.5.68.1:8080
Note that the SSH port 23101 is forwarded as localhost:23101. So connect an SSH client to that port:
$ ssh -p 23101 admin@localhost
The password corresponding the user ID admin is the one you used earlier to configure the Maven deployment plug-in (so it should be in $HOME/.m2/settings.xml).

Verify that console commands like profile-list and version-list work in this environment.

4.4 Use rhc to back up a complete application

You can use rhc to copy the entire gear to a tarball, so that it can be restored later. To dowbload a copy of the fuse application's gear, for example:
$ rhc snapshot save fuse
There is a corresponding restore command for pushing a tarball to a gear.
Copyright © 1994-2013 Kevin Boone. Updated Oct 02 2014