Chapter 5. Cartridge Management

This chapter covers the management of cartridges provided by Red Hat, the installation and management of custom and community cartridges, and other cartridge tasks.

Note

Some sections in this chapter assume that you have installed cartridges on node hosts. See the following section of the OpenShift Enterprise Deployment Guide for instructions on installing cartridges from RPM packages provided by Red Hat, if required:
https://access.redhat.com/site/documentation/en-US/OpenShift_Enterprise/2/html-single/Deployment_Guide/index.html#sect-Installing_Cartridges

Important

If needed, administrators can choose to configure the JBoss EWS cartridge tomcat7 binary provided by the EWS 3 product to work around known security issues with the JBoss EWS-2 tomcat7 binary. See Known Issues to learn more.

5.1. Managing Cartridges on Broker Hosts

Important

Cartridge management on broker hosts, which includes any usage of the oo-admin-ctl-cartridge command, is only applicable to OpenShift Enterprise 2.1 and later.
With the release of OpenShift Enterprise 2.1, cartridges are managed on the broker. While cartridges are still initially installed on nodes, you must then import the cartridge manifests on the broker from the nodes, which creates records in the MongoDB datastore using metadata from the manifests. Cartridges must then be activated before they can be used by developers in new applications or as add-on cartridges to existing applications.
With this cartridge management system, the broker application is able to track which cartridges are deployed on which applications, including the corresponding capabilities for each cartridge. The broker application can then control cartridge actions such as starting, stopping, scaling, and deleting. This system also allows developers to know which cartridges you have activated and made available.
Software Versions Versus Cartridge Versions

To better understand cartridge management on broker hosts, including required tasks such as importing and activating cartridges, it is important to note the distinction between software versions and cartridge versions in cartridge manifests.

When you install cartridges on nodes, either from RPM packages or source directories, cartridge manifests are installed, which describe the features a cartridge requires and the information to provide to developers about a cartridge. A single manifest can support one or more software versions, which identify the specific version or versions of a web framework or add-on technology that the cartridge is supporting. For example, installing the openshift-origin-cartridge-ruby RPM package provides support for two software versions: Ruby 1.8 and Ruby 1.9.
Each software version is then associated with a cartridge name and presented to developers as a distinct cartridge. For example, the Ruby 1.8 software version is presented with the cartridge name ruby-1.8, and Ruby 1.9 with the cartridge name ruby-1.9.
However, each manifest also has a cartridge version, which is separate from any software version or cartridge name. When a cartridge is updated by the cartridge author, the cartridge version is incremented to identify the new release of that particular cartridge. Therefore, a single cartridge name can be associated with multiple cartridge versions over time, based on the manifests that have been installed. For example, if errata is released that updates openshift-origin-cartridge-ruby to a newer package version, this can result in manifests installed on nodes for two cartridge versions: 0.0.17 and 0.0.18. The ruby-1.8 cartridge name would therefore have two cartridge versions (0.0.17 and 0.0.18), and the ruby-1.9 cartridge would also have two cartridge versions (0.0.17 and 0.0.18).
Active and Inactive Cartridges

After manifests have been imported on the broker, you can designate cartridges as either active or inactive. The active cartridge represents the cartridge, based on an imported manifest, that is made available to developers for creating new applications or adding to existing applications. Any inactive cartridges cannot be deployed as new cartridges by developers. Cartridges can be activated automatically when importing the latest manifests from nodes or activated and deactivated manually at any time.

5.1.1. Importing, Activating, and Deactivating Cartridges

With the release of OpenShift Enterprise 2.1, you must import cartridge manifests on the broker host and activate or deactivate cartridges using the oo-admin-ctl-cartridge command. Running the oo-admin-ctl-cartridge command with the -c import-profile option imports the latest manifests for all cartridges installed on a randomly selected node for each gear profile. Importing the latest manifests includes manifests for both newly installed cartridges as well as newly updated cartridges that may have older manifests that were previously imported.
Run the following command on the broker host to import the latest manifests from nodes and mark all new or updated cartridges as active: 
# oo-admin-ctl-cartridge -c import-profile --activate
You can also import manifests for downloadable cartridges to make them persistently available as cartridge options for developers. The cartridge sources for downloadable cartridges remain hosted externally, and they are downloaded when a developer deploys them as a new cartridge. Run the following command to import the latest manifest for a downloadable cartridge and mark all new or updated cartridges as active: 
# oo-admin-ctl-cartridge -c import --url URL_to_Cartridge_Manifest --activate
When importing and activating at the same time, any other previously imported cartridges with the same cartridge name are automatically deactivated, though applications already using previous versions are unaffected and continue to function. This only means that developers cannot deploy new cartridges using the inactive cartridges.
Activating and Deactivating Using Cartridge Names

After manifests have been imported, you can activate and deactivate cartridges manually using their cartridge name. Running the oo-admin-ctl-cartridge command with the -c list option lists all currently imported cartridges and the timestamp of each import. Active cartridges are identified with an asterisk.

Example 5.1. Listing Imported Cartridges

# oo-admin-ctl-cartridge -c list
		
* cron-1.4         plugin    Cron 1.4              2014/06/16 22:09:55 UTC
* jenkins-client-1 plugin    Jenkins Client        2014/06/16 22:09:55 UTC
  mongodb-2.4      service   MongoDB 2.4           2014/06/16 22:09:55 UTC
* mysql-5.1        service   MySQL 5.1             2014/06/16 22:09:55 UTC
* mysql-5.5        service   MySQL 5.5             2014/06/16 22:09:55 UTC
  ruby-1.8         web       Ruby 1.8              2014/06/16 22:09:55 UTC
* ruby-1.9         web       Ruby 1.9              2014/06/16 22:09:55 UTC
* haproxy-1.4      web_proxy Web Load Balancer     2014/06/16 22:09:55 UTC
The following command activates cartridges using one or more cartridge names: 
# oo-admin-ctl-cartridge -c activate --name Cart_Name1,Cart_Name2,Cart_Name3
The following command deactivates cartridges using one or more cartridge names: 
# oo-admin-ctl-cartridge -c deactivate --name Cart_Name1,Cart_Name2,Cart_Name3
Advanced Managing Using Cartridge IDs

Whenever a new manifest is imported, a record is created in the MongoDB datastore noting the cartridge name, the timestamp of the import, and a unique cartridge ID. Cartridge IDs are alphanumeric strings used to identify a cartridge based on an imported manifest and timestamp of the import. Therefore, a single cartridge name can be associated with multiple cartridge IDs.

For most cases, importing and activating the latest manifests at the same time is the workflow recommended by Red Hat when updates are released for cartridges provided by Red Hat. However, if you need developers to go back to using an inactive cartridge when deploying new cartridges, you can activate and deactivate using specific cartridge IDs at any time. For more advanced cartridge management, including activating and deactivating using cartridge IDs, see the man page for oo-admin-ctl-cartridge.

5.1.2. Migrating and Upgrading Existing Applications to Active Cartridges

To allow existing applications that are using inactive cartridges to switch to using the currently active cartridges, the following two tasks must be performed for the switch to fully take effect for both new and existing gears.
Migrating Existing Applications to Active Cartridges for New Gears

Existing applications using inactive cartridges continue to use the inactive versions when adding new gears, for example, during scaling operations. Run the following command on the broker host to allow these applications to instead use the currently active cartridges, if active versions are available, when adding new gears: 

# oo-admin-ctl-cartridge -c migrate
This command initiates a migration that updates the MongoDB datastore records all of applications that are using inactive cartridges to refer instead to the currently active cartridges. Existing application gears on nodes, however, are unaffected, and continue to use inactive cartridges.

Note

If the command returns an exit code 2, wait a few minutes for all applications to finish using the cartridges, then run the command again until it completes successfully.
Upgrading Existing Application Gears to Active Cartridges

You can use the oo-admin-upgrade command on the broker host to upgrade existing application gears that are currently using inactive cartridges to instead use active cartridges. The most common scenario that requires this cartridge upgrade process is when applying certain asynchronous errata updates. See the following section of the OpenShift Enterprise Deployment Guide for instructions on running the oo-admin-upgrade command when applying these types of errata updates:

https://access.redhat.com/site/documentation/en-US/OpenShift_Enterprise/2/html-single/Deployment_Guide/index.html#chap-Asynchronous_Errata_Updates
The oo-admin-upgrade command can also be used to upgrade existing application gears that are using inactive versions of custom, community, and downloadable cartridges. See Section 5.3, “Upgrading Custom and Community Cartridges” for more information.

5.1.3. Removing Unused Inactive Cartridges

When inactive cartridges are no longer being used by any existing applications, you can remove these cartridges from the MongoDB datastore by running the oo-admin-ctl-cartridge command with the -c clean option on the broker. This command returns a list of the unused inactive cartridges that were removed, but also lists any inactive cartridges that were not removed because they were still in use by an application. Inactive cartridges that were not removed are shown on lines starting with a # symbol; the number of applications that are still using the cartridge is shown at the end of the same line.

Example 5.2. Listing Imported Cartridges And Removing Unused Inactive Cartridges

# oo-admin-ctl-cartridge -c list
		
* cron-1.4         plugin    Cron 1.4              2014/06/16 22:09:55 UTC
* jenkins-client-1 plugin    Jenkins Client        2014/06/16 22:09:55 UTC
  mongodb-2.4      service   MongoDB 2.4           2014/06/16 22:09:55 UTC
* mysql-5.1        service   MySQL 5.1             2014/06/16 22:09:55 UTC
* mysql-5.5        service   MySQL 5.5             2014/06/16 22:09:55 UTC
  ruby-1.8         web       Ruby 1.8              2014/06/16 22:09:55 UTC
* ruby-1.9         web       Ruby 1.9              2014/06/16 22:09:55 UTC
* haproxy-1.4      web_proxy Web Load Balancer     2014/06/16 22:09:55 UTC
		
# oo-admin-ctl-cartridge -c clean
		
Deleting all unused cartridges from the broker ...
539f6b336892dff17900000f # ruby-1.8                            
# 539f6b336892dff179000012 mongodb-2.4                         1
In the above example, the mongodb-2.4 and ruby-1.8 cartridges were both inactive cartridges. The ruby-1.8 cartridge was successfully removed, however the mongodb-2.4 cartridge was not because it was still in use by one application. Listing the imported cartridges again confirms the removal of only the ruby-1.8 cartridge:

Example 5.3. Listing Imported Cartridges After Removing Unused Inactive Cartridges

# oo-admin-ctl-cartridge -c list
		
* cron-1.4         plugin    Cron 1.4              2014/06/16 22:09:55 UTC
* jenkins-client-1 plugin    Jenkins Client        2014/06/16 22:09:55 UTC
  mongodb-2.4      service   MongoDB 2.4           2014/06/16 22:09:55 UTC
* mysql-5.1        service   MySQL 5.1             2014/06/16 22:09:55 UTC
* mysql-5.5        service   MySQL 5.5             2014/06/16 22:09:55 UTC
* ruby-1.9         web       Ruby 1.9              2014/06/16 22:09:55 UTC
* haproxy-1.4      web_proxy Web Load Balancer     2014/06/16 22:09:55 UTC