Show Table of Contents
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-upgradescript, 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-upgradescript, 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
IDENTof 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_versionparameter is set. If theignore_cartridge_versionparameter is set, record an incompatible upgrade for the cartridge in the itinerary. - If the latest manifest includes the current cartridge version in the
Compatible-Versionselement, record a compatible upgrade for the cartridge in the itinerary. Otherwise, record an incompatible upgrade for the cartridge in the itinerary.
Where did the comment section go?
Red Hat's documentation publication system recently went through an upgrade to enable speedier, more mobile-friendly content. We decided to re-evaluate our commenting platform to ensure that it meets your expectations and serves as an optimal feedback mechanism. During this redesign, we invite your input on providing feedback on Red Hat documentation via the discussion platform.