5.2. Installing and Removing Custom and Community Cartridges

In addition to cartridges provided and supported by Red Hat, you can install custom and community cartridges for developers to use in their applications. The following table describes the cartridge types available and indicates their level of Red Hat support.

Table 5.1. Cartridge Types

Type Description Red Hat Supported?
Standard cartridges These cartridges are shipped with OpenShift Enterprise. Yes. Requires base OpenShift Enterprise entitlement.
Premium cartridges These cartridges are shipped with OpenShift Enterprise. Yes. Requires premium add-on OpenShift Enterprise entitlement.
Custom cartridges These cartridges are developed by users and can be based on other cartridges. See the OpenShift Enterprise Cartridge Specification Guide for more information on creating custom cartridges. No.
Community cartridges These cartridges are contributed by the community. See the OpenShift Origin Index at http://origin.ly to browse and search for many community cartridges. No.
Partner cartridges These cartridges are developed by third-party partners. No, but can possibly be directly supported by the third-party developer.

Note

Red Hat supports the base OpenShift Enterprise platform on which custom and community cartridges run, but does not support or maintain the custom and community cartridges themselves. See https://access.redhat.com/support/policy/updates/openshift/policies.html for more information about Red Hat's support for OpenShift Enterprise.
Custom and Community Cartridges Versus Downloadable Cartridges

Custom and community cartridges are installed locally on your OpenShift Enterprise deployment and appear as cartridge options for developers when using the Management Console or client tools. However, installing custom or community cartridges locally as an administrator is not to be confused with developers using downloadable cartridges, which are custom or community cartridges that are hosted externally. See the OpenShift Enterprise User Guide for more information on developers using downloadable cartridges in applications:

https://access.redhat.com/site/documentation/en-US/OpenShift_Enterprise/2/html-single/User_Guide/index.html#Downloadable_Cartridges2
If you are using OpenShift Enterprise 2.1 or later, you can also see Section 5.1.1, “Importing, Activating, and Deactivating Cartridges” for instructions on managing downloadable cartridges locally in the MongoDB database. By importing the downloadable cartridge manifests on the broker, downloadable cartridges can be made persistently available as cartridge options for all developers while the cartridge sources are still hosted externally.
Installing Custom and Community Cartridges

To use custom or community cartridges in any release of OpenShift Enterprise 2, you must install the cartridges from a source directory using the oo-admin-cartridge command on each node host. In OpenShift Enterprise 2.1 and later, you must then import the newly installed cartridge manifests on the broker using the oo-admin-ctl-cartridge command before the cartridges are usable in applications.

Procedure 5.1. To Install Custom or Community Cartridges:

  1. Run the following command on each node host, specifying the source directory of the custom or community cartridge to install: 
    # oo-admin-cartridge --action install --source /path/to/cartridge/
  2. Verify that the list of installed cartridges on each node host is updated with the newly added custom or community cartridge:

    Example 5.4. Listing Installed Cartridges

    # oo-admin-cartridge --list

(redhat, jenkins-client, 1.4, 0.0.1)
(redhat, haproxy, 1.4, 0.0.1)
(redhat, jenkins, 1.4, 0.0.1)
(redhat, mock, 0.1, 0.0.1)
(redhat, tomcat, 8.0, 0.0.1)
(redhat, cron, 1.4, 0.0.1)
(redhat, php, 5.3, 0.0.1)
(myvendor, mycart, 1.1, 0.0.1)
(redhat, ruby, 1.9, 0.0.1)
(redhat, perl, 5.10, 0.0.1)
(redhat, diy, 0.1, 0.0.1)
(redhat, mysql, 5.1, 0.2.0)
    This command displays the vendor name, cartridge name, software version, and cartridge version of each installed cartridge.
  3. Restart the MCollective service on each node host: 
    # service ruby193-mcollective restart
  4. Update the cartridge lists on the broker. For releases prior to OpenShift Enterprise 2.1, run the following command on the broker host to clear the broker cache and, if installed, the Management Console cache: 
    # oo-admin-broker-cache --clear --console
    For OpenShift Enterprise 2.1 and later, run the following commands on the broker host to import and activate the latest cartridges from the nodes and, if installed, clear the Management Console cache: 
    # oo-admin-ctl-cartridge -c import-profile --activate
# oo-admin-console-cache --clear
Removing Custom and Community Cartridges

You can also use the oo-admin-cartridge command to remove cartridges from the cartridge repositories on a node host. Cartridges should only be removed from cartridge repositories after they are no longer in use by any existing applications. When removing a cartridge, ensure the same cartridge is removed from each node host.

Procedure 5.2. To Remove Custom and Community Cartridges:

  1. For OpenShift Enterprise 2.1 and later, deactivate the cartridge to be removed by running the following command on the broker host: 
    # oo-admin-ctl-cartridge -c deactivate --name Cart_Name
    Deactivating the cartridge ensures it can no longer be used by developers in new applications or as add-on cartridges to existing applications. This step is not applicable for releases prior to OpenShift Enterprise 2.1.
  2. List the installed cartridges by running the following command on each node host: 
    # oo-admin-cartridge --list
    Identify in the output the cartridge name, software version, and cartridge version of the cartridge to be removed.
  3. Remove the cartridge from the cartridge repository by running the following command on each node host with the cartridge information identified in the previous step: 
    # oo-admin-cartridge --action erase --name Cart_Name --version Software_Version_Number --cartridge_version Cart_Version_Number
  4. Update the relevant cartridge lists. For releases prior to OpenShift Enterprise 2.1, clear the cache for the broker and, if installed, the Management Console by running the following command on the broker host: 
    # oo-admin-broker-cache --clear --console
    For OpenShift Enterprise 2.1 and later, clear the cache for only the Management Console, if installed, by running the following command on the broker host: 
    # oo-admin-console-cache --clear