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
- Load the gear upgrade extension, if configured.
- Inspect the gear state.
- Run the gear extension's
pre-upgrade
script, if it exists. - Compute the upgrade itinerary for the gear.
- If the itinerary contains an incompatible upgrade, stop the gear.
- Upgrade the cartridges in the gear according to the itinerary.
- Run the gear extension's
post-upgrade
script, if it exists. - If the itinerary contains an incompatible upgrade, restart and validate the gear.
- 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
- Read in the current
IDENT
of the cartridge. - 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.
- 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 theignore_cartridge_version
parameter is set, record an incompatible upgrade for the cartridge in the itinerary. - 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.