Extending Private PaaS Cartridge Agent

WSO2 Private PaaS Cartridge Agent (CA) can be extended to perform various cartridge specific configurations on the cartridge instances. This can be done in two ways: either by using Cartridge Agent extension points, or by extending CartridgeAgent Java class and implementing a custom Cartridge Agent execution flow.

Using Cartridge Agent extension points

Extension points can be considered as 'hooks' that are provided by the Cartridge Agent, to allow user’s scripts to ‘hook into’ the Cartridge Agent at specific times. These extension points (or hooks) allow users to capture events and execute any cartridge specific logic. Users can attach shell, bash or batch scripts into these extension points, which will be executed by Cartridge Agent.

Cartridge Agent will search for these extension shell scripts in the directory path set by the environment variable extensions.dir. This variable is by default set to <CA_HOME>/extensions/ directory, where <CA_HOME> is the path, in which Cartridge Agent is deployed. You can change this value by modifying extensions.dir environment variable, which is defined in the <CA_HOME>/bin/stratos.sh file.

Available extension points

Following is a list of available extension points with the associated extension key, and a description of when each extension would occur during the lifecycle of Cartridge Agent:

The mapping of the extension key to the script name is included in <CA_HOME>/bin/stratos.sh file.

Extension point	Extension key	Description
Instance Started	extension.instance.started	This is executed just after the Cartridge Agent process is started. This extension point can be used to set any cartridge specific environment variables, install required packages and perform any initial configurations on the cartridge instance.
Start Servers	extension.start.servers	This is executed just after executing the Instance Started extension script. This extension point can be used to perform any product or component configurations, and start any application servers deployed in the cartridge instance. For example: to start WSO2 ESB server in a WSO2 ESB cartridge.
Instance Activated	extension.instance.activated	This is executed after all ports are activated and the Instance Activated event is published. This extension point can be used to send any configuration service calls to the cartridge server. Instance activated extension script is executed only after all ports taken by the cartridge instance (as defined in the cartridge defintion) become active.
Artifacts Updated	extension.artifacts.updated	This is executed whenever Artifact Updated event is published by ADC to Instance Notifier topic. This extension script will be executed after artifacts are deployed to `<APP_PATH>`. This is useful if you need to perform any action after deploying artifacts. For example: to restart Tomcat server with updated artifacts.
Clean	extension.clean	This is executed whenever Instance Cleanup Member event or Instance Cleanup Cluster event is published by ADC to Instance Notifier topic. Cartridge Agent will execute clean extension script before publishing the Instance Ready To Shutdown event to Instance Notifier topic. This is useful if you need to perform any cleanup operations before the cartridge instance is terminated. For example: to gracefully shutdown Tomcat server without affecting current requests in queue.
Mount Volumes	extension.mount.volumes	This is executed if persistence volume mapping is defined in the cartridge definition. This extension script will receive persistence mapping parameters as a command line argument in the format of `device\|volumeID\|mountPoint`. Private PaaS Cartridge Agent by default provides a generic implementation of this extension script.
Member Started	extension.member.started	This is executed whenever a new cartridge instance is spawned and when the Instance Started event is sent by Cartridge Agent to Topology topic by Cloud Controller.
Member Activated	extension.member.activated	This is executed whenever a new cartridge instance is started and ports are activated, Member Activated event is sent by Cloud Controller to Topology topic.
Member Terminated	extension.member.terminated	This is executed whenever a cartridge instance is terminated and the Member Terminated event is published by Cloud Controller to Topology topic.
Complete Topology	extension.complete.topology	This is executed whenever a Complete Topology event is published by Cloud Controller to Topology topic. Cloud Controller will publish the Complete Topology event periodically.
Complete Tenant	extension.complete.tenant	This is executed whenever Complete Tenant event is published by Cloud Controller to Tenant topic. Cloud Controller will publish the Complete Topology event periodically.
Subscription Domain Added	extension.subscription.domain.added	This is executed whenever Subscription Domain Added event is published by Stratos Manager to the Tenant topic.
Subscription Domain Removed	extension.subscription.domain.removed	This is executed whenever Subscription Domain Removed event is published by Stratos Manager to the Tenant topic.

For more information on topics and events of WSO2 Private PaaS, see Private PaaS Communication.

Extension script samples

Following are two samples of start-servers.sh and clean.sh extension scripts:

Sample start-servers.sh script to start Tomcat server

#!/bin/bash
log=/var/log/apache-stratos/cartridge-agent-extensions.log
echo "Starting Apache Tomcat server..." | tee -a $log
nohup runuser tomcat -c “/opt/tomcat/bin/startup.sh” &

Sample clean.sh script to gracefully shutdown Tomcat server

#!/bin/bash
log=/var/log/apache-stratos/cartridge-agent-extensions.log
echo "Shutting down Apache Tomcat server..." | tee -a $log
nohup runuser tomcat -c “/opt/tomcat/bin/shutdown.sh” &

Extending CartridgeAgent Java class

This method must be used only if the extension points are not sufficient to achieve the level of extendability that is required for the cartridge type. In that case provide your custom implementation of Cartridge Agent by extending the CartridgeAgent Java class. Using this method requires that you build the Cartridge Agent product. For a reference on the implementation, see the org.apache.stratos.cartridge.agent.CartridgeAgent class in the source. Ensure that all main functionalities of the Cartridge Agent are captured in your custom implementation according to Cartridge Agent Lifecycle.

Take the following steps to extend the WSO2 Private PaaS Cartridge Agent by extending the CartridgeAgent Java class:

Create a new Java class and extend the org.apache.stratos.cartridge.agent.CartridgeAgent class. For an example, create a class named MyCartridgeAgent as below:
```
class MyCartridgeAgent extends CartridgeAgent{
    // your custom cartridge agent implementation here.
}
```

Build Cartridge Agent product using Maven as follows:

$ cd <STRATOS_HOME>/products/cartridge-agent
$ mvn clean install

Deploy the product archive file to Puppet Agent module using the command below:

$ cp <STRATOS_HOME>/products/cartridge-agent/modules/distribution/target/apache-stratos-cartridge-agent-4.0.0.zip /etc/puppet/modules/agent/files

When starting the Cartridge Agent process, pass the new custom cartridge agent’s Java class name as an argument to Main class. Following command should be modified in the <CA_HOME>/bin/stratos.sh file.
```
java -cp "${class_path}" ${properties} ${debug} org.apache.stratos.cartridge.agent.Main org.apache.stratos.cartridge.agent.MyCartridgeAgent
```