Plugin Management APIs

Overview

Starting with Kill Bill 0.16.0, it is now possible to go through all the lifecycle (install, start, stop, uninstall and list status) of a plugin using APIs. These APIs have been designed to work on a Kill Bill deployment that consists of several instances.

APIs

A user provided key that will be used to identify this plugin when using the APIs. The user provided key must be unique and must contain a namespace (e.g MY_NAMESPACE:myKey). During the installation phase, and when using a user provided key, one must also specify additonal properties to specify the location of that plugin.

The following APIs are supported:

INSTALL_PLUGIN: Install a plugin. The following properties are supported:

pluginPackaging: optional (the Maven packaging, which will default to jar for java plugin and tar.gz for ruby plugins)

pluginClassifier: optional (the Maven classifier, which will default to null)

START_PLUGIN: Start a plugin. The following properties are supported:

pluginKey: required

pluginVersion: optional (will default to latest installed version of that plugin)

RESTART_PLUGIN: Restart a plugin. All classes will be unloaded and new classes/ruby files will be loaded and started. The following properties are supported:

pluginKey: required

pluginVersion: optional (will default to latest version)

STOP_PLUGIN: Stop a plugin. All classes will be unloaded. The following properties are supported:

pluginKey: required

pluginVersion: optional (will default to latest version)

UNINSTALL_PLUGIN: The command will disable the plugin so it will not be listed as an installed plugin, but the code will be kept on the filesystem (to optimize cases where one would want to re-install the same version of the plugin):

pluginKey: required

pluginVersion: optional (will default to latest version)

Installation

The installation of a plugin occurs through the KPM plugin (which itself relies on KPM) and consists of the following sequence:

Download the binaries and install them on the filesystem at the right place

Set that latest downloaded version as being the default one to start (isSelectedForStart)

Notify Kill Bill core to update its view of the existing plugins

Example of installing the paypal plugin with a specified version of 4.0.0:

Listing all the plugins

There is an API to retrieve the current view for each Kill Bill node. That API provides details about the running versions of a Kill Bill node along with all the plugins detail information (the json can be quite longm so for better readibility one can pipe the output to python -m json.tool to format it nicely):

pluginName: The name of the plugin as seen on the filesystem. It is used internally by Kill Bill to identify a plugin, but that name is only available after the plugin has been installed and could be changed from one installation to the next

bundleSymbolicName: The OSGI symbolic name (from the MANIFEST.mf)

isSelectedForStart: If this is the default version to be started for that plugin

Internals

Multi-node Implementation

Each Kill Bill node writes to the database the details about its versions and plugins right after it has started. When there is any change in the system, each node is notified through a broadcast mechanism: each node then updates its entry guaranting that at any time the info matches the current state.

The broadcast mechanism is based on a simple mechanism where each node polls periodically a database table shwoing the command to execute. When the system (each node) picks up a new entry, it then sends a special bus event, so that different Kill Bill components and plugins can react to the event and carry out the action.

Installation/Uninstallation

Installing/uninstalling a plugin using the API is slightly different than installing/uninstalling the plugin using KPM directly. The main reason has to do with the pluginKey:

When installing/uninstalling a plugin using the API, one must provide a pluginKey. KPM will update a configuration file under ROOT/plugins/plugin_identifiers.json to keep the mapping between that pluginKey and the pluginName which is the location on the filesystem where this plugin is being deployed (ROOT/plugins/{java|ruby}/pluginName/pluginVersion)

When installing/uninstalling a plugin directly through KPM, one does not need to provide a pluginKey and the mapping is not created.

KPM Plugin

Plugin installation and uninstallation is handled by the KPM plugin, whose role is to simply listen for bus events to then delegate the installation/uninstallation the the KPM gem and then notify Kill Bill about the result.

For all other operations (start/stop/restart), the KPM plugin is not involved.