Create Cartridge

To access the cartridges which can be installed in the Jelastic Cloud, you need to make additional configurations to standard OpenShift cartridges. Using this instruction, you will easily compile the needed cartridge package and make it available for your users.

So our cartridge consists of two parts:

  • basic OpenShift cartridge
  • Jelastic configurations
You can use cartridges already prepared and tested by Jelastic. Such cartridges can be uploaded from the template repository.

A. Basic OpenShift Cartridge

Before creating your own cartridge, you should search the current list of Red Hat and OpenShift Community provided cartridges.

If the required cartridge is not provided in the list of existing cartridges, you can create your own using this Cartridge Developer’s Guide.

B. Jelastic Configurations

When you have your cartridge packed (or simply used an existing one) you need to add a jelastic directory to its content to make this cartridge appropriate for using in the Jelastic Cloud.

This directory should have the following structure:

jelastic:

Let’s look through each component step-by-step.

ICONS


This subdirectory should contain three logos of cartridges that will be displayed:

  • in JCA after adding the cartridge to the list

  • at the dashboard in the Environment topology

  • at the dashboard after adding this cartridge to the environment


Note: these logos should have transparent backgrounds and be the following sizes:
  • 16x16
  • 32x32
  • 64x64

SCRIPTS


Currently this directory contains three scripts:

  • reset_password.sh is responsible for the function of password resetting;
  • deploy.sh implements deploy and undeploy functionality for applications;
  • generate_optimal_configs.sh is responsible for optimizing application’s configuration files for best performance based on the available system resources inside a container (amount of cloudlets stated for it).

1. The reset_password.sh file should include function _setPassword description which implements the functionality for setting/resetting predefined system variables.

Here you can operate with the following parameters:

  • J_OPENSHIFT_APP_ADM_USER
    This parameter is used for stating username.The value for this parameter is taken from Admin_App_User in the jelastic.conf file

  • J_OPENSHIFT_APP_ADM_PASSWORD
    This parameter is used for providing randomly chosen password. The value is generated by Jelastic Core.

Here is the example of the reset_password.sh script for Cassandra:

#!/bin/bash

SED=$(which sed);
GREP=$(which grep);

#
# This is an example of reset password hook in Jelastic
#

#$J_OPENSHIFT_APP_ADM_USER        ;   Operate this variable for the username
#$J_OPENSHIFT_APP_ADM_PASSWORD    ;   Use this varible for your password

function _setPassword() {
        new_passwd_file=$(mktemp);
        old_passwd_file=$(mktemp);
        cassanra_conf="/opt/repo/versions/1.2.5/conf/cassandra.yaml";
        cqlsh_app="/opt/repo/versions/1.2.5/bin/cqlsh";

        echo ALTER USER cassandra WITH PASSWORD \'$J_OPENSHIFT_APP_ADM_PASSWORD\'\; > $new_passwd_file;
        echo UPDATE system_auth.credentials set salted_hash=\'\$2a\$10\$vbfmLdkQdUz3Rmw.fF7Ygu6GuphqHndpJKTvElqAciUJ4SZ3pwquu\' where username=\'cassandra\'\; > $old_passwd_file;

        export CQLSH_HOST=$OPENSHIFT_CASSANDRA_DB_HOST;
        export CQLSH_PORT=$OPENSHIFT_CASSANDRA_DB_PORT;

        # Init data is needed for password auth
        $SED -i 's/authenticator: org.apache.cassandra.auth.AllowAllAuthenticator/authenticator: org.apache.cassandra.auth.PasswordAuthenticator/g'     $cassanra_conf;
        service cartridge restart > /dev/null 2>&1;

        while netstat -lnt | awk '$4 ~ /:'"${OPENSHIFT_CASSANDRA_DB_PORT}"'$/ {exit 1}'; do sleep 1; done;
        sleep 10;
        $SED -i 's/authenticator: org.apache.cassandra.auth.PasswordAuthenticator/authenticator: org.apache.cassandra.auth.AllowAllAuthenticator/g'     $cassanra_conf;
        service cartridge restart > /dev/null 2>&1;
        while netstat -lnt | awk '$4 ~ /:'"${OPENSHIFT_CASSANDRA_DB_PORT}"'$/ {exit 1}'; do sleep 1; done;
        [ -f "$old_passwd_file" ] && $cqlsh_app  --file $old_passwd_file;
        $SED -i 's/authenticator: org.apache.cassandra.auth.AllowAllAuthenticator/authenticator: org.apache.cassandra.auth.PasswordAuthenticator/g'     $cassanra_conf;
        service cartridge restart > /dev/null 2>&1;
        while netstat -lnt | awk '$4 ~ /:'"${OPENSHIFT_CASSANDRA_DB_PORT}"'$/ {exit 1}'; do sleep 1; done;
        [ -f "$new_passwd_file" ] && $cqlsh_app -u $J_OPENSHIFT_APP_ADM_USER -p "cassandra"  --file $new_passwd_file;
}

2. The deploy.sh script is obligatory only for compute node  cartridges (with application server). It should include _deploy() and _undeploy() functions (just implemented, not called). The first one performs the deployment procedure for compute node, and the second one, respectively, performs the undeployment procedure.

While preparing this script, you can also use all available OpenShift’s environment variables that are applied in cartridge configurations and usually starts with an "OPENSHIFT_" prefix.

Here is the example of the deploy.sh script for JBoss7:
#!/bin/bash

# Simple deploy and undeploy scenarios for JBoss 7

WGET=$(which wget);

function _deploy(){
     [ "x${context}" == "xroot" ] && context="ROOT";
     [ -f "${WEBROOT}/${context}.war" ] && { rm -f "${WEBROOT}/${context}.war"; rm -f "${WEBROOT}/${context}.war.*" ; };
     $WGET --no-check-certificate --content-disposition -O "${WEBROOT}/${context}.war" "$package_url";
}

function _undeploy(){
     [ "x${context}" == "xroot" ] && context="ROOT";
     [ -f "${WEBROOT}/${context}.war" ] && { rm -f "${WEBROOT}/${context}.war"; rm -f "${WEBROOT}/${context}.war.*" ; };
}

3. The generate_optimal_configs.sh script is not mandatory but strongly recommended. Without this script, the cartridge will be still functional, but its performance will not depend on the amount of cloudlets (resources) stated.

This script may be written in any programming language, which can be interpreted by a Jelastic container, namely: BASH, SED, AWK, Perl, Python. You can also use any other language, but in this case, you have to install your interpreter by specifying an appropriate RPM package name in the Native_Requires parameter of jelastic.conf file (described in the separate section below).

Here is the example of the generate_optimal_configs.sh script for Jetty8:

#!/bin/bash

SED=$(which sed);

#
# config optimizer for Jetty8
#

JETTY_START_SCRIPT="${OPENSHIFT_JETTY8_DIR}.openshift/action_hooks/start";

[ -z "$XMS" ] && { XMS=32; }
memory_total=`free -m | grep Mem | awk '{print $2}'`;
[ -z "$XMX" ] && { let XMX=memory_total-35; }

$SED -i "s/-Xms[0-9]*m/-Xms${XMS}m/g" $JETTY_START_SCRIPT;
$SED -i "s/-Xmx[0-9]*m/-Xmx${XMX}m/g" $JETTY_START_SCRIPT;

FILE_MANAGER.CONF


The file_manager.conf file should contain the path to the folders or files in your cartridge which are going to be displayed in the Jelastic dashboard while opening the Config option.

This file should have the following structure:

[keyword1]
       versions/{version_number}/{folder_name}
[keyword2]
       versions/{version_number}/{folder_name}
       versions/{version_number}/{folder_name}

where

keyword - name of the resources group that will be displayed in the configuration manager;
versions/{version_number}/{folder_name} - full path to the folder from the root of cartridge.


Folders, specified under each of keywords, will be shown inside the appropriate directories with all their content. So, if you want to just open separate folders for users, but not all of them, then specify the paths to the particular folders.

For example, if file_manager.conf file for Jetty 9 cartridge looks like following:

[conf]
       versions/9.1.3/etc
[libraries]
       versions/9.1.3/modules
       versions/9.1.3/lib
[cron]
       cron
[keys]
       keys


You will get the next folder’s structure displayed at the dashboard:

In such a way all the configuration files, libraries, modules, etc, can be easily grouped into the separate directories with corresponding names.

JELASTIC.CONF


The jelastic.conf file should include the following parameters:

  • Node_Mission

Here you need to specify where to place your cartridge in the Environment topology.

Possible ValuePlace Description
cacheto Memcached

Note: to create Memcached you are required to add compute node to the environment. The same requirement will be for the cartridge which is added to cache node type.
cpto application servers
nosqldbto NoSQL databases
sqldbto SQL databases
lbto Balancing node
buildto Maven build node

Note: Maven is available only for Java that’s why cartridge added to build node type will be displayed only for Java users
vdsto VDS server

Note: often VDS is not available for trial users or disabled at all. As a result it is not displayed. The same will be with cartridge added to vds node type


For example:
Node_Mission=nosqldb

  • Engine_Type

Here, specify the main engine which is used for your cartridge.

For example:

Engine_Type=java

  • Valid_Engines

Within this parameter you can set a list of specific engines versions (corresponding to the Engine_Type parameter value), that will be available for your cartridge. If you would like to all of the versions to be available, this parameter is not needed.

For example:
Valid_Engines=java7,java8

  • Native_Requirements

If you need to upload any packages from the official repo for appropriate performance of your cartridge, you just need to enumerate them, comma delimited here.

For example:
Native_Requires=ruby,java

  • App_User

The value of this parameter is the same for all cartridges:
App_User=jelastic

  • Admin_App_User

The value of this parameter will be used as a login to admin panel of the cartridge (it will be the same for all users).

For example:
Admin_App_User=admin

  • Node_Type

Using this parameter, you can specify the name of your cartridge. In such a way, this cartridge will be signed in JCA and dashboard.

For example:
Node_Type=neo4j

  • Webroot_Path

This parameter is obligatory for compute node cartridges (with application server) only. Its value defines the default location (folder), where the deployed to cartridge application package will be placed.

For example:
Webroot_Path="${OPENSHIFT_JETTY8_DIR}/versions/8.14/webapps"
  • Reset_Password

Set this parameter’s value equal to 1, if you would like to email the credentials for cartridge’s administrator access to a user after environment creation. Note that this is an optional parameter for non-DB cartridges and can be used only in the case your cartridge includes admin panel.

For example:
Reset_Password=1

  • Firewall_Enabled

It’s an optional parameter, used to override the global firewall configurations, defined for the current user in JCA. State its value to 0 or 1 to disable/enable a firewall respectively. Note: firewall will be switched on/off for the current cartridge node only.

For example:
Firewall_enabled=0