Tuesday, November 1, 2011

Apache Karaf Child Instances, what are they and why should I use them?

An often under used feature of Apache Karaf is its support for child instances. In this post I'll cover just what Karaf child instances are, and discuss some ways that you may use them.

Two child instances, Alpha and Beta,
created from base Karaf installation.
A Karaf child instance is a copy of Karaf that you can launch separately (its own system process) and deploy applications into. An instance does not contain the full copy of Karaf, but only a copy of the configuration files and data folder which contains all the runtime information, logs and temporary files. This concept is pretty neat in that you can deploy a Karaf distribution to your server, adjust your basic configuration, then spin up copies of this initial deployment for use - the ports used by these child instances are managed such that you don't have to manually set them as part of the setup process (much easier than trying to setup multiple separate installations on one machine). Each of the Karaf child instances will "live" in your KARAF_HOME/instances folder.

If the above description doesn't have you excited then don't worry, here are a couple of deployment scenarios that may help illustrate why using Karaf child instances can improve your Karaf experience.

Operating System level process isolation:

We've all encountered this - Suppose you have an application that is known to have less than desirable runtime characteristics (cores the system, or regularly encounters Out of Memory exceptions for example), it may be nice to have that application deployed in its own Karaf environment. If the process becomes unwieldily then the entire instance can be stopped, restarted, or else wise manipulated without affecting other applications deployed  in other Karaf child instances.

Failover protection:

Simple Master/Slave Failover.
I have to admit I like to use this setup when I need to have an extra level of assurance that my deployed application will be available. In this scenario two or more instances of Karaf are created on one server, with each instance making use of Karafs' JDBC lock mechanism to connect to local or remote DB. In this Master/Slave deployment if the instance acting as the Master was to become unavailable then an awaiting slave instance can spool up to take over (for faster switches I keep the slave instances hot loaded via container level locking).

Organizational Separation:

Keeping your user groups happy.
It's not uncommon for multiple departments or projects to reside upon the same server resource, it may be advantageous for the administrator to separate their Karaf deployments along these lines so that the operation of one group does not impact others. In example one may have an instance for supporting an application used by accounting, and another by marketing.


A more advanced concept is to create Karaf instances to join into a Cellar Cluster - Cellar being Apache Karaf's Hazelcast powered clustering solution. Creating Karaf child instances to join as cluster nodes allows for another degree of flexibility when allocating resources for Karaf deployments. Given a powerful server, an administrator may create child instances as required to add to the cluster. These additional cluster resources may be deallocated as required at a later time.

I hope that the above exploration of Karaf child instances helped clear up any general confusion about their purpose and perhaps provided some insight into how to improve your own Karaf deployments. For more information on Karaf child instances please visit the Karaf user guide Child Instance entry.


Nico said...

Thanks for this article. I was wondering if child instances have something to do with OSGi R5 subsystems and Aries implementation ? As I understand both, they are pretty closed, may be karaf could manage subsystems by deploying them on child instances.

icbts said...

Good question!

Child instances were introduced well before R5. It'll be interesting to see where the instances features will go in regards to R5 subsystems... The current Karaf 2.3.x and 3.0.x are based of OSGi R4.3, so perhaps a later revision will be able to take advantage of new capabilities.

Technote said...

As this is not currently documented, do you know whether it is possible to auto-start child instances when the parent instance is started (for instance after a failure)?

Unknown said...


I unable to get user defined bundles to be started up on a child instance. Though I did put the following properties in the etc/system.properties file:

All my user defined bundles are started at level 80. Any idea on what Im missing.