Cartridge Agent Lifecycle

The following diagram illustrates the Cartridge Agent lifecycle, which illustrates how to start Cartridge Agent, what is does and the protocols used to communicate with the real-time event processing engine bus and Message Broker:

1. Start the instance from a configured image. If the instance is started based on a fully configured cartridge image, the image will have Puppet Agent, Cartridge Agent and all the required software installed. However, if the instance is started based on a generic cartridge image, the instance will only have Puppet Agent installed.
2. When a instance is started, a initialization script (e.g.,  init.sh) will get triggered. 
3. When the initialization script (e.g., init.sh) gets triggered it will get the cartridge payload and also invoke Puppet Agent. Puppet Agent will use the SERVICE_NAME, which is a payload parameter that defines the service type, to communicate with Puppet Master and configure the cartridge.
4. If the cartridge is a fully configured cartridge, Puppet Agent will check for software updates,
   • If there are software updates, Puppet Agent will download and install the required software updates. Move to step 5.
   • If there are no software updates, move to 6.
5. If the cartridge is a generic cartridge, Puppet Agent will download and install the required software and Cartridge Agent.
6. Puppet Agent will extract the server package and update the config files in order to configure the server.
7. Puppet Agent will start Cartridge Agent.
8. After the Cartridge Agent has started up, it will initially subscribe to the "Instance Notifier" topic. Thereafter, the Cartridge Agent will publish the "Instance Started" event to the "Instance Status" topic, which is in Message Broker.
9. Cloud Controller and Stratos Manager will receive the "Instance Status" topic update from Message Broker. 
10. After Cloud Controller receives the "Instance Started" event, the following actions will take place:
    1. Cloud Controller will start the cartridge instance.
    2. Cartridge Agent will wait until the ports get active and the applications are started. 
       • If the cartridge needs artifact updates,
         • Cartridge Agent will wait for the "Artifact Update" event from Stratos Manager. Move to step 11(a).
       • If the cartridge does not need artifact updates, move to step 12. 
         Some cartridges (e.g., MySQL cartridge) will not have a Git repository. Therefore, such cartridges will not need artifact updates.
11. After Stratos Manager receives the  "Instance Started " event the following actions will take place: 
    1. Stratos Manager will publish the "Artifact Update" event to all the clusters created for the cartridge. The "Artifact Update" event will contain the cluster ID, status, repository username, repository URL, tenant ID and the encrypted repository  password.
    2. Stratos Manager will checkout the artifacts from the Git repository, which is the central location to manage the server artifacts.
    3. Stratos Manager will deploy the artifacts by copying the checked out files to the server, which is running inside the cartridge. 
       
12. Cartridge Agent will publish the "Instance Activated" event to the "Instance Status" topic,  with member information.
    • Cartridge Agent will start the Health Publisher, which is a sub-component within Cartridge Agent. Thereafter, Health Publisher will periodically publish health statistics to the real-time processing engine. Apache Stratos uses WSO2 Complex Event Processor (CEP) as its real-time event processing engine.
    • Cartridge Agent will monitor the logging process in real-time and publish the newly added logs to its monitoring engine. WSO2 Private PaaS uses WSO2 Business Activity Monitor (BAM) as its monitoring engine.
    • When an instance or a cluster needs to be shutdown, the following actions will take place in order to shut down the instance(s) gracefully:
      1. If an instance needs to be shut down, Artifact Distribution Controller (ADC), which is in Stratos Manager, will publish the "Instance Clean Up Member" event. If a cluster needs to be shut down, ADC will publish the "Instance Clean Up Cluster" event.
      2. Cartridge Agent will publish the "Member Maintenance Mode" event to the "Topology" topic, which is in Message Broker. When the instance(s) are in maintenance mode, the instance(s) will appear inactive to the Load Balancer (LB) and the LB will not send the instance(s) any requests.
      3. When an instance needs to be shut down, Cartridge Agent will clean up the respective instance. When a cluster needs to be shut down, all the instances in the cluster will be cleaned up. The cartridge provider can decide to execute any actions during the instance clean up process. For example, if the cartridge manages a data replication mechanism, this event can be used to update the data replication cluster.
      4. Cartridge Agent will publish the "Instance Ready to Shutdown" event to the "Instance Status" topic, which is in Message Broker.
      5. After Cloud Controller (CC) receives the "Instance Status" topic update, CC will publish the "Member Ready to Shutdown" event to the "Topology" topic, which is in Message Broker and also terminate the instance.
      6. Cloud Controller will publish the "Member Terminated" event to the "Topology" topic, which is in the Message Broker.