Cartridge Development Guide

Stratos2 is shipped with some built-in Cartridge types that are namely, WSO2 Product Cartridges, PHP and MySQL. If you want to deploy your own Cartridge type in Stratos 2.0, you need to develop your Cartridge first. Stratos 2.0 Cartridge is a Virtual Machine running on the Stratos 2.0 underlying IaaS, together with some Stratos 2.0 specific configurations. A new Cartridge can be added to Stratos 2.0 dynamically without stopping the Cloud Controller. 

Developing a Cartridge

1. Create a virtual machine image, included with the necessary software and configurations for each IaaS configured in Stratos2 Cloud Controller (CC). For more information, see Creating a Cartridge image.
2. Add the Cartridge specific configuration to Stratos2 CC, by copying the Cartridge configuration XML file to the right place.
   The image ID of the VM image you created for the IaaS is included in the Cartridge configuration file.
3. In addition create a service.xml for WSO2 Carbon Cartridges to maintain domain information in the CC.
   Puppet is currently used to automate the latter mentioned process. In Stratos2 setup the Stratos Controller (SC) is used to maintain these Puppet scripts and the automation process. The  SC will act as the Puppet master instance. 
   

Creating a Cartridge image

You need to create an Operating System (OS) image of the Cartridge, for each IaaS you plan to run Stratos2 Cartridges. In this guide we describe how to do this for any IaaS. The following sections explain the various steps that should be followed to create a Cartridge based on its type (Carbon or Non-carbon):

• Carbon Cartridges
• Non-Carbon Cartridges

Carbon Cartridges

WSO2 product Cartridge creation is automated using a Puppet. Defining a new Cartridge type can be done as follows:

Step 1 - Define a new Cartridge type using Puppet.   

For more information go to http://docs.puppetlabs.com/puppet/2.7/reference/

Step 2 - Setup S2 and Puppet in the IaaS.

1. Download and extract wso2s2-<iaas>-1.0.0.zip to the server.
   s2demo-single-node-installer-<iaas> is inside wso2s2-<iaas>

2. Execute the following commands, to run the automated installer:

   chmod +x s2demo-single-node-installer-<iaas>
   ./s2demo-single-node-installer-<iaas>

   This will create /mnt/puppet/stratos2 folder.
   
   

Step 3 - Add definitions and configurations of the new Cartridge type in the Puppet master.

1. Define a new puppet class extending the stratos.pp (/mnt/puppet/stratos2/manifests/classes/stratos.pp).
   stratos.pp contains all the common functionalities related to Carbon servers.
2. Create a modules and template directory in /mnt/puppet/stratos2/{modules,templates}
   

   • modules directory should contain the static files (e.g.,static configuration files, external JARs.), in the folder location defined in the corresponding .pp class.

   • template directory should contain files with variables that can be submitted to changes (e.g., carbon servers axis2.xml, carbon.xml etc.), in the folder location defined in the corresponding .pp class.

    
3. Create a node definition in the nodes.pp file.
4. Add the new class to the node definition.

Step 4 - Install the Puppet agent in an IaaS instance and create an AMI.

For more information see Setting up Puppet Agent.

Non-carbon Cartridges

The steps involved in creating a Cartridge image for non-carbon Cartridges is the same irrespective of the IaaS it is created on. The user can start with basic Linux cloud image (e.g:, Ubuntu cloud image) to create the new Cartridge image. By spawning an instance from a basic image and thereafter installing software and necessary configurations.

Carryout the following steps to create a non-carbon Cartridge image:

1. Install the necessary software that needs to be in the Cartridge on the Linux cloud image.

2. Run the following command to install the required software for a Stratos 2 Cartridge image:
   

   sudo apt-get install git libboost-all-dev ruby xml-twig-tools

3. Upload following files to the /opt directory in the spawned instance using scp:
• • cartridge_data_publisher_1.0.2.zip

  • get-launch-params.rb

  • security.zip

  • thrift-0.8.0.tar.gz  

  • wso2-cartridge-init.sh

4. Extract the cartridge_data_publisher_1.0.2.zip, security.zip, and thrift-0.8.0.tar.gz

5. Appropriately change the wso2-cartridge-init.sh
   • Under the section with the comment '# If repo is available do a git pull, else clone”, there is a section to build the git.sh file clone and pull the Git repository.
     Make the  appropriate changes.
     
     
   • Add log files to the configurations as mentioned below:

     • Find the following line and replace <logging_files_of_cartridge_application> with application log files. Note that you can give more than one file separated by spaces.
       

       nohup ./cartridge_data_publisher_1.0.2 <logging_files_of_cartridge_application> >> /var/log/wso2-data-publisher.log  &

        

     • Change the port of the application, under the comment "# section to wait until the application is active ”. 
       Note that if you have several ports of the running application, you have to add several sections like this.
       
       

     • Change the section to get the public IP, under the comment "# getting public ip from metadata service ” as appropriate to the IaaS.
       The provided  wso2-cartridge-init.sh has been written for EC2.
       
       

     • If new key pairs are copied to facilitate ssh access of the applications, remove the comment the commands under comment  “ #restart apache if the new keypairs copied using payload, if so uncomment following ”.
6. Create the image using the current instance.
7. Find the image ID and configure that ID in the Cloud Controller. 

Setting up Puppet agent

1. Install packages.
   

   $apt-get install puppet

    

2. Generate the keys in the server (Puppet master)
   

   $puppet cert --generate star.s2.wso2.com

   Copy the generated key in /var/lib/puppet/ssl/private_keys/star.s2.wso2.com.pem to clients (Puppet agent) /var/lib/puppet/ssl/private_keys/  

   Copy the generated key in /var/lib/puppet/ssl/ca/signed/star.s2.wso2.com.pem to clients /var/lib/puppet/ssl/certs/

      

3. Change the /etc/puppet/puppet.conf as follows:
   

   [main]
   logdir=/var/log/puppet
   vardir=/var/lib/puppet
   ssldir=/var/lib/puppet/ssl
   rundir=/var/run/puppet
   factpath=$vardir/lib/facter
   templatedir=$confdir/templates
   server=s2demo.s2.wso2.com
   waitforcert=60
   report=false
   
   [master]
   environment=stratos2
   modulepath=/etc/puppet/$environment/modules
   templatedir=/etc/puppet/$environment/templates
   manifest=/etc/puppet/$environment/manifests/site.pp
   manifestdir=/etc/puppet/$environment/manifests/
   
   [agent]
   environment=stratos2
   certname = star.s2.wso2.com
   node_name = facter
   node_name_fact = fqdn

Configuring Cloud Controller to support new Cartridges

Once the Cartridge developer creates the Cartridge image, the cartridge has to be registered with Stratos2. This is normally done by a operation team person who maintains Stratos2 deployments.

For this to work the Cloud Controller configurations need to be done. Please see Cloud Controller Configurations for more information.

Registering your Cartridge with Cloud Controller

The Cartridges that the system going to support should be defined in the Cloud Controller. This can be done easily by dropping a XML file that defines your Cartridge , into the ${WSO2-CC}/repository/deployment/server/cartridges/ folder. You can do this either before starting the server or while the server is running .

The following are the guidelines that a Cartridge XML file should follow:

• Unique file name.
• Adhere to one of the given XML schemas.
  
  • Cartridge Schema for Single Cartridge
  • Cartridge Schema for Multiple Cartridges

To view a sample file see Sample Cartridge XML Files.

  This reveals very strong feature of Stratos2. Not only that it can support different IaaS’s, but that support can be added dynamically to Stratos2.