Chapter 11. 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.

11.1. Upgrade Itinerary

The upgrade process must be re-entrant; if it fails or times out, a subsequent upgrade operation must pick up where the last one left off. The upgrade itinerary stores information about which cartridges in a gear to upgrade and which type of upgrade to perform.
There are two types of cartridge upgrade processes: compatible and incompatible. The Compatible-Versions element in a cartridge's $cartridge_name/metadata/manifest.yml file determines whether the new version is compatible with a previous version. The main difference between the compatible and incompatible upgrade processes is that an incompatible cartridge's gear stops during an upgrade, while a compatible cartridge's gear continues to run.

Upgrade Itinerary Configuration

  1. Read in the current IDENT of the cartridge.
  2. Determine the name and software version of the cartridge in the cartridge repository; this provides the manifest for the latest version of the cartridge. If a manifest does not exist in the cartridge repository or does not include the software version, skip the cartridge.
  3. If the latest manifest is for the same cartridge version as the version currently installed on the gear, skip the cartridge unless the ignore_cartridge_version parameter is set. If the ignore_cartridge_version parameter is set, record an incompatible upgrade for the cartridge in the itinerary.
  4. If the latest manifest includes the current cartridge version in the Compatible-Versions element, record a compatible upgrade for the cartridge in the itinerary. Otherwise, record an incompatible upgrade for the cartridge in the itinerary.