The cartridge agent is a component that resides within a cartridge instance and handles the communication between the cartridge and WSO2 Private PaaS. This component is implemented using Java and Python. The cartridge agent communicates with the message broker (MB), Complex Event Processor (CEP), Business Activity Monitor (BAM) and the remote Git repository as depicted in the diagram below:
The cartridge agent is generic and can be used in any cartridge. A cartridge agent comprises of the following components as illustrated in the following diagram: Instance Notifier Event Receiver, Health Statistics Publisher, Artifact Distribution/Artifact Update event and Instance Status Event Publisher.
The use of the other components in cartridge agent have been explained as follows:
- Event listeneres
The event listener subscribes to message broker topics, relevant for the Cartridge agent. It then executes operations related to each event.
- Instance/Status topic publisher
All message broker events that are published by the Cartridge Agent are published under the "Instance/Status" sub topic. This includes events such as
- Artifact distribution manager
This component is triggered by the event listeners based on the events such as
InstanceCleanupClusterEvent. Its main responsibility is to clone, pull, push artifacts between a specified remote Git repository. This component is only activated for Cartridge instances that already has a configured repository URL.
- Health statistics publisher
Every instance is required to post its health statistics to the CEP in WSO2 Private PaaS, to determine autoscaling decisions. The Health Statistics Publisher collects statistics such as load average and memory usage, and sends them to a specified CEP via the Apache Thrift Protocol.
The Cartridge Agent's functionality can be extended by writing Shell Script extensions which are executed when their respective events are received.
A Bash Shell Script can be written to run when the CompleteTopologyEvent is received by the Cartridge Agent. In the Python implementation of the Cartridge Agent, an additional Python based plugin system is available which can be mapped to multiple events to be executed.
- Metadata service client
This component is available only in the Python implementation of the Cartridge Agent. It's responsibility is to write to and read from the Private PaaS Metadata Service via REST calls. The Metadata Service Client can be used by any Python based plugin to implement complex application scenarios by interacting with the Metadata Service.
- Log file publisher
The Cartridge Agent can be configured to enable the Log Publisher Component which will periodically check a given set of server log files for new entries and publish them to a given Thrift receiver. The purpose of this is to enable data analysis based on the server logs.
In addition, Cartridge Agent has some extension points: Instance Started Extension, Start Servers Extension, Artifacts Updated Extension, Instance Activated Extension and Clean Extension. Cartridge developers can use these extension points to extend the cartridges in WSO2 Private PaaS. For example, the Instance Started Extension can be used to customize the cartridge at the point an instance has started.
Failover in Python Cartridge Agent
When communicating with the Message Broker, the Python Cartridge Agent (PCA) will go through the provided URL list and connect to the first broker that is available.
The listening subscriber client always ensures to maintain a connection with one of the brokers. The PCA periodically checks if the connected Message Broker is in fact alive or not. If the connected broker goes down, the PCA will go through the Message Broker list and select the first available broker. If none of the provided message brokers are online, the subscribing client will keep retrying until one broker becomes available. This logic is separately executed for each topic subscription.
The publishing client will publish the events to the first broker available. If none of the brokers are available it will keep retrying to publish the event, until the provided mb.publisher.timeout value is exceeded. The default value for this is 15 minutes. After the latter mentioned timeout, if the event is still unpublished, the event is dropped.
It is possible for the events to be published to one broker and for the intended consumers to be connected to another broker. However, if the Master/Slave deployment is done correctly, data sharing happens without an issue and this situation is not of any concern.