4.1.x Creating a New Cartridge

You can create a cartridge on a Virtual Machine (VM) or Docker. The following section describes the process involved in creating a cartridge:

Creating a cartridge on a Virtual Machine

The following section describes how to create a cartridge using Puppet, which is an open source configuration management utility. If required, you can use other tools, i.e, Chef, with Stratos, as the orchestration layer to automate the configuration process of all cartridges.

Step 1: Creating a Puppet Module

Create Puppet scripts based on the cartridge that is being created. The Puppet scripts will define the relevant cartridge software (i.e., server software and dependent software) that are required for the cartridge.
Deploy the Puppet scripts in Puppet Master. Puppet Master will be used by all the cartridges in a Stratos deployment.

Puppet Master needs to be configured prior to deploying the Puppet scripts.
If a Generic cartridge image already exists, move to step 3.

Step 2: Creating a base image

The init.sh and config.sh scripts are OS specific. Stratos ships config.sh for Debian/Ubuntu and CentOS operating systems. While, Stratos ships init.sh for Debian/Ubuntu. These scripts are accessible in the <STRATOS_SOURCE_HOME>/tools/init-scripts/ directory. The init.sh and config.sh scripts need to be customized for any other operation system.

Start up a virtual machine (VM) instance using a preferred OS, on a preferred IaaS. For more information, see Creating a Cartridge on a Preferred IaaS.

Run the config.sh setup script.

Copy the <STRATOS_SOURCE_HOME>/tools/puppet3-agent/puppetinstall/puppetinstall script into the /root/bin/puppetinstall/ directory.

Run the setup script.

sh config.sh

The following messages are prompted.

Prompted Message	Description
This script will install and configure puppet agent, do you want to continue [y/n]	Enter y to configure and install Puppet Agent in the cartridge.
Please provide stratos service-name:	If you need to create a fully configured cartridge, enter the Stratos service name, which refers to the cartridge name. If you wish to create a generic cartridge, simply leave this field empty by pressing enter.
Please provide puppet master IP:	Enter the Puppet Master IP.
Please provide puppet master hostname [puppet.stratos.org]:	Enter the Puppet Master hostname.
Please provide stratos deployment:	Enter the Stratos deployment, which refers to the Stratos domain name (e.g., stratos.apache.org).

Thereafter, if the cartridge is a fully configured cartridge, the Puppet Agent will communicate with the Puppet Master to install the Cartridge Agent and all the required software in the cartridge.

Copy the init.sh file to the above VM instance and configure it.
Create a cartridge image from the above VM instance.

Step 3: Creating a cartridge definition

The cartridge definition needs to be defined in a JSON file. For information on all the properties that can be used in a cartridge definition, see the Cartridge Resource Definition.

{
  "type": "php",
  "provider": "apache",
  "category": "data",
  "host": "php.stratos.org",
  "displayName": "php",
  "description": "php Cartridge",
  "version": "7",
  "multiTenant": "false",
  "portMapping": [
    {
	  "name": "http-80",
      "protocol": "http",
      "port": "80",
      "proxyPort": "8280"
    },
    {
      "name": "http-22",
      "protocol": "tcp",
      "port": "22",
      "proxyPort": "8222"
    }
  ],
  "deployment": {
    
  },
  "iaasProvider": [
    {
      "type": "mock",
      "imageId": "RegionOne/b4ca55e3-58ab-4937-82ce-817ebd10240e",
      "networkInterfaces": [
        {
          "name": "network-non-routable",
          "networkUuid": "b55f009a-1cc6-4b17-924f-4ae0ee18db5e"
        }
      ],
      "property": [
        {
          "name": "instanceType",
          "value": "RegionOne/aa5f45a2-c6d6-419d-917a-9dd2e3888594"
        },
        {
          "name": "keyPair",
          "value": "reka"
        },
        {
          "name": "securityGroups",
          "value": "default"
        }
      ]
    }
  ]
}

In Stratos 4.1.1, you can specify the kubernetesPortType as NodePort or ClusterIP in Port Mapping.

Access URLs are generated only for the NodePort service type.

{
  "type": "php",
  "category": "framework",
  "provider": "apache",
  "host": "stratos.org",
  "displayName": "PHP",
  "description": "PHP Cartridge",
  "version": "7",
  "multiTenant": true,
  "loadBalancingIPType": "private",
  "metadataKeys": [],
  "portMapping": [
    {
      "name": "http-80",
      "protocol": "http",
      "port": 80,
      "proxyPort": 8280,
      "kubernetesPortType": ""
    },
    {
      "name": "http-80",
      "protocol": "https",
      "port": 443,
      "proxyPort": 8243,
      "kubernetesPortType": ""
    }
  ],
  "iaasProvider": [
    {
      "type": "mock",
      "imageId": "ap-southeast-1/ami-2e0d5a7c",
      "property": [
        {
          "name": "instanceType",
          "value": "m1.medium"
        },
        {
          "name": "keyPair",
          "value": "xxxxxxxx"
        }
      ],
      "networkInterfaces": [
        {
          "networkUuid": "fb9c21f4-0672-48b2-8279-77334bb63a53"
        },
        {
          "networkUuid": "1e43f86f-4165-4f2e-8017-dd4cfb5548b0"
        }
      ]
    },
    {
      "type": "kubernetes",
      "imageId": "stratos/php:4.1.0",
      "property": [
        {
          "name": "KUBERNETES_CONTAINER_CPU",
          "value": "0"
        },
        {
          "name": "KUBERNETES_CONTAINER_MEMORY",
          "value": "0"
        },
        {
          "name": "KUBERNETES_SERVICE_SESSION_AFFINITY",
          "value": "ClientIP"
        },
        {
          "name": "payload_parameter.START_CMD",
          "value": "PCA"
        }
      ],
      "networkInterfaces": []
    }
  ]
}

Step 4: Adding a cartridge definition

A cartridge can be added via the API method, CLI tool or the Stratos Management Console (UI).

Adding a cartridge via the API method.
```
curl -X POST -H "Content-Type: application/json" -d @'<JSON_PAYLOAD>' -k -v -u admin:admin https://<STRATOS_HOST>:<STRATOS_HTTPS_PORT>/api/cartridges
```
The path to the JSON file that defines the cartridge needs to be defined as the <JSON_PAYLOAD> value.
- By default, <STRATOS_HOST> is localhost. However, if you are using a public IP, the respective IP address or domain needs to be specified.
- By default, <STRATOS_HTTPS_PORT> has been set to 9443. However, if the port offset has been incremented by n, the default port value needs to be incremented by n.
For Example:
```
cd <STRATOS_SOURCE_HOME>/samples
curl -X POST -H "Content-Type: application/json" -d @'cartridges/mock/php.json' -k -v -u admin:admin https://localhost:9443/api/cartridges
```
Adding a cartridge via the CLI tool.
```
add-cartridge -p <JSON_FILE_PATH>
```
Adding a cartridge via the Stratos Management Console (UI).
Log into Stratos dashboard and wait for the application to become active as follows:
1. Login to the Stratos Management Console. The default username and password is admin.
  https://localhost:9443/console
2. Navigate to the cartridge definitions page.
  1. Click Configurations on the home page.
  2. Click Cartridges. The Cartridges page will appear.
3. Click Add New Cartridge on the Cartridge definition page.

Creating a cartridge on Docker

The following section describes how to create a cartridge on Docker. Stratos uses Kubernetes to manage Docker containers.

Step 1: Creating a base image

Implement a Docker file.
Copy the Cartridge Agent (CA) and the required software to a preferred location. The Cartridge Agent should startup along with the container.

Build a Docker image.

docker build -t stratos/base-image:4.1.x-beta .

List the Docker images using the following command and get the Docker image ID of the required Docker image.
```
docker images
```
Pull the Docker image to all the Kubernetes minions in the Kubernetes Cluster.
The docker image could be pulled using either of the following methods:
1. If you are using the Docker hub, execute the docker pull command.
```
docker pull <DOCKER_IMAGE_ID>
```
2. Else export the Docker image to a .tar file.
  1. Save the new image to a .tar file.
    docker save <NEW_IMAGE_NAME> > <LOCATION_OF_OF_TAR_FILE>
    For example:
    docker save mystratosimage > /tmp/mystratosimage.tar
  2. Copy the TAR (mystratosimage.tar) file to your new Docker instance.
    docker load < <LOCATION_OF_OF_TAR_FILE>
    For example:
    docker load < /tmp/mynewimage.tar

Step 2: Creating a cartridge definition

The cartridge definition needs to be defined in a JSON file. For information on all the properties that can be used in a cartridge definition, see the Cartridge Resource Definition.
Include the respective Docker image ID found in step 1.4 in the cartridge definition.

{
  "type": "php",
  "provider": "apache",
  "category": "data",
  "host": "php.stratos.org",
  "displayName": "php",
  "description": "php Cartridge",
  "version": "7",
  "multiTenant": "false",
  "portMapping": [
    {
	  "name": "http-80",
      "protocol": "http",
      "port": "80",
      "proxyPort": "8280"
    },
    {
      "name": "http-22",
      "protocol": "tcp",
      "port": "22",
      "proxyPort": "8222"
    }
  ],
  "deployment": {
    
  },
  "iaasProvider": [
    {
      "type": "mock",
      "imageId": "RegionOne/b4ca55e3-58ab-4937-82ce-817ebd10240e",
      "networkInterfaces": [
        {
          "name": "network-non-routable",
          "networkUuid": "b55f009a-1cc6-4b17-924f-4ae0ee18db5e"
        }
      ],
      "property": [
        {
          "name": "instanceType",
          "value": "RegionOne/aa5f45a2-c6d6-419d-917a-9dd2e3888594"
        },
        {
          "name": "keyPair",
          "value": "reka"
        },
        {
          "name": "securityGroups",
          "value": "default"
        }
      ]
    }
  ]
}