Cartridge Agent Lifecycle

The diagram illustrates the Cartridge Agent lifecycle, of how to start a Cartridge Agent (CA), and what it does:

If you want to see the diagram in detail click here.

Start the instance from a configured image. If the instance is started based on a fully configured cartridge image, the image will have the Puppet Agent, CA and all the required software installed. However, if the instance is started based on a generic cartridge image, the instance will only have the Puppet Agent installed.

Once the CA instance is created it goes through the Initialize, start, active, pending termination and obsolete states to reach the instance termination state. The following depicts the steps the CA follows at each stage:

Initialize state

The CA intializing stage will take place in the cartridge instance, and also with the Puppet Master.

Instance

1. When a instance is started, a initialization script (e.g., init.sh) will get triggered. 
2. 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.
3. If the cartridge is a generic cartridge, Puppet Agent will download and install the required software and Cartridge Agent.
4. If the cartridge is not generic, the steps shown under under puppet master will take place.
5. Puppet Agent will extract the server package and update the config files in order to configure the server.
6. Puppet Agent will start the CA.
7. After the CA has started up it will register to the Event Listeners. Thereafter it waits for the complete topology event and for the instance to reach the initialised state.
8. The agent will then publish the instance of the started event.
9. The InstanceActiveEvent state of the CA will then be notified to the Stratos Manager.

Puppet Master

If the cartridge is a fully configured cartridge, Puppet Agent will check for software updates,

1. If there are software updates, Puppet Agent will download and install the required software updates. Move to step 5 under instance
2. If there are no software updates, move to step 6 under instance.

Start state

 After publishing the InstanceStartedEvent the CA will check if any repository details are provided.

1. If repository details are not provided:
   1. The CA will immediately publish the InstanceActivatedEvent after checking if the service ports are active. It does not have to interact with any artifact repositories.
2. If repository details are provided:
   1. The CA will continue execution without publishing the InstanceActivatedEvent. If any repositories are provided, Stratos Manager will pick up those details and publish ArtifactUpdatedEvent, which the CA will listen to.
   2. After receiving the ArtifactUpdatedEvent the CA will clone the repository and publish InstanceActivatedEvent after checking if service ports are active. This is executed in the event listening thread.

Active state

The CA has 3 main activities in the active state as shown below:

Starting the log publisher

1. If the Repo URL is provided the CA instance will execute the volume mount extensions.
2. Next if log publishing is enabled in the instance it will start the log publisher process.
   
   1. If enabled, it will start the log publisher and check logs for each of the specified paths. Next it will move to publishing entries in BAM.
   2. If not enabled, the instance will move into the loop forever stage, which will then lead to the instance being terminated eventually.

Publishing entries to BAM

1. Once the CA finishes checking the logs for the specified paths, it will then check if the logs have new entries.
   1. If the logs have no new entries, the agent will go back and check the logs for the specified paths again. This step will keep repeating until new entires are found.
   2. If the log finds new entries, it will publish these entires to BAM. This step will repeat until all the new entires are published to BAM.

Publishing health statistics to CEP

1. Start the health statistics publisher of the instance. 
2. Publish the health statistics to CEP.
3. Wait for 15 seconds and repeat the process of publishing the health statistics.
   If the health statics are not published within 30seconds, then the agent is notified and it starts to check the reason for the delay and takes measures to resolve any issues found.

Cartridge Agent termination in the active state

The instance termination can be a result of several actions such as:

• Application undeployment.
• Termination of a dependent instance with a relationship of "terminate-dependents".
• Termination of an instance with the relationship of "terminate-all".

Any of the above executions results in the instance being moved to the pending termination state. 

Pending termination state

1. Upon receiving the InstanceCleanupMemberEvent or InstanceCleanupClusterEvent, the CA will publish the InstanceMaintenanceModeEvent, clean the instance and publish the InstanceReadyToShutdownEvent.
2. The Autoscaler, upon receiving MemberReadyToShutdownEvent will add the particular instance to a termination queue, which will ultimately result in the instance being terminated in the IaaS.