This documentation is for WSO2 Stratos 2.0.0. View the latest Apache Stratos documentation.
Cartridge Development Guide - Stratos 2.0.0 - WSO2 Documentation
Skip to end of metadata
Go to start of metadata

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

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

Step 2 - Setup S2 and Puppet in the IaaS.

  1. Download and extract wso2s2-<iaas> 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>

    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:
      • get-launch-params.rb


      • thrift-0.8.0.tar.gz  

  4. Extract the,, and thrift-0.8.0.tar.gz

  5. Appropriately change the
    • Under the section with the comment '# If repo is available do a git pull, else clone”, there is a section to build the 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 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. 

The method of creating the image from the current instance will depend on the IaaS.


Setting up Puppet agent

  1. Install packages.

    $apt-get install puppet


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

    $puppet cert --generate

    Copy the generated key in /var/lib/puppet/ssl/private_keys/ to clients (Puppet agent) /var/lib/puppet/ssl/private_keys/  

    Copy the generated key in /var/lib/puppet/ssl/ca/signed/ to clients /var/lib/puppet/ssl/certs/

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

    certname =
    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:

In XML versions later than XML1.1 ensure to always follow the sequential order of the elements in the configuration files.

To view a sample file see Sample Cartridge XML Files.


You can even configure an IaaS provider in the Cartridge configuration file. This can be done by adding a Cartridge with a IaaS provider definition and then if that IaaS provider has not already been added it will be added to Stratos2; thereby allowing IaaS provider configuration to be dynamically added to Stratos2.

  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.

  • No labels