5.3. Upgrading Custom and Community Cartridges

The OpenShift Enterprise runtime contains a system for upgrading custom cartridges on a gear to the latest available version and for applying gear-level changes that affect cartridges.
The oo-admin-upgrade command on the broker host provides the command line interface for the upgrade system and can upgrade all the gears in an OpenShift Enterprise environment, all the gears on a node, or a single gear. This command queries the OpenShift Enterprise broker to determine the locations of the gears to migrate and uses MCollective calls to trigger the upgrade for a gear.

Upgrade Process Overview

  1. Load the gear upgrade extension, if configured.
  2. Inspect the gear state.
  3. Run the gear extension's pre-upgrade script, if it exists.
  4. Compute the upgrade itinerary for the gear.
  5. If the itinerary contains an incompatible upgrade, stop the gear.
  6. Upgrade the cartridges in the gear according to the itinerary.
  7. Run the gear extension's post-upgrade script, if it exists.
  8. If the itinerary contains an incompatible upgrade, restart and validate the gear.
  9. Clean up after the upgrade by deleting pre-upgrade state and upgrade metadata.
See the OpenShift Enterprise Cartridge Specification Guide at https://access.redhat.com/site/documentation for more information on the cartridge upgrade process.
The oo-admin-upgrade command can perform the following tasks, as described by the oo-admin-upgrade help command:
oo-admin-upgrade archive
Archives existing upgrade data in order to begin a completely new upgrade attempt.
oo-admin-upgrade help <task>
List available tasks or describe the designated task and its options.
oo-admin-upgrade upgrade-gear --app-name=<app_name>
Upgrades only the specified gear.
oo-admin-upgrade upgrade-node --version=<version>
Upgrades all gears on one or all nodes.

Important

Do not use the oo-admin-upgrade upgrade-from-file task. The help output of the oo-admin-upgrade command does list upgrade-from-file as a valid task. However, it is not meant for direct use by an administrator and can invalidate an upgrade process.