Chapter 15. Asynchronous Errata Updates

Security, bug fix, and enhancement updates for minor versions of OpenShift Enterprise are released as asynchronous errata through the Red Hat Network. All OpenShift Enterprise 2 errata are available on the Red Hat Customer Portal at https://rhn.redhat.com/errata/rhel6-rhose2-errata.html. Red Hat recommends applying the latest errata updates.
Cartridge Upgrades

When Red Hat releases asynchronous errata updates within a minor release, the errata can include upgrades to shipped cartridges. After installing the updated cartridge packages using the yum command, further steps are often necessary to upgrade cartridges on existing gears to the latest available version and to apply gear-level changes that affect cartridges. The OpenShift Enterprise runtime contains a system for accomplishing these tasks.

The oo-admin-upgrade command provides the command line interface for the upgrade system and can upgrade all gears in an OpenShift Enterprise environment, all gears on a single 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. While the ose-upgrade command, outlined in Chapter 4, Upgrading from Previous Versions, handles running the oo-admin-upgrade command during major platform upgrades, oo-admin-upgrade must be run by an administrator when applying asynchronous errata updates that require cartridge upgrades.
Determining Application Downtime During Cartridge Upgrades

During a cartridge upgrade, the upgrade process can be classified as either compatible or incompatible. As mentioned in the OpenShift Enterprise Cartridge Specification Guide, to be compatible with a previous cartridge version, the code changes to be made during the cartridge upgrade must not require a restart of the cartridge or of an application using the cartridge. If the previous cartridge version is not in the Compatible-Versions list of the updated cartridge's manifest.yml file, the upgrade is handled as an incompatible upgrade.

Incompatible upgrades must stop the gear before the upgrade begins, complete the upgrade, and then restart the gear. This process can cause a short amount of downtime for the application. For instructions on how to determine upgrade compatibility for all cartridges in a directory, and therefore whether any application downtime would be required during an upgrade, see the Knowledgebase solution at https://access.redhat.com/solutions/1186183 on the Red Hat Customer Portal.
Example oo-admin-upgrade Usage

Instructions for applying asynchronous errata updates are provided in Section 15.1, “Applying Asynchronous Errata Updates”; in the event that cartridge upgrades are required after installing the updated packages, the oo-admin-upgrade command syntax as provided in those instructions upgrades all gears on all nodes by default. Alternatively, to only upgrade a single node or gear, the following oo-admin-upgrade command examples are provided. Replace 2.y.z in any of the following examples with the target version.

Important

To prevent previously cached node data from interfering with the current upgrade, archive existing upgrade data with the oo-admin-upgrade archive command.
The following commands upgrade all gears on all nodes: 
# oo-admin-upgrade archive
# oo-admin-upgrade upgrade-node --version=2.y.z
The following commands upgrade all gears on a single node: 
# oo-admin-upgrade archive
# oo-admin-upgrade upgrade-node --upgrade-node=node1.example.com --version=2.y.z
The following commands upgrade a single gear: 
# oo-admin-upgrade archive
# oo-admin-upgrade upgrade-gear --app-name=testapp --login=demo --upgrade-gear=gear-UUID --version=2.y.z

15.1. Applying Asynchronous Errata Updates

The following instructions provide a general overview on how to apply asynchronous errata updates within a minor release to previously installed OpenShift Enterprise systems.

Procedure 15.1. To Apply Asynchronous Errata Updates:

  1. On each host, run the following command to ensure that the yum configuration is still appropriate for the type of host and its OpenShift Enterprise version: 
    # oo-admin-yum-validator
    If run without any options, this command attempts to determine the type of host and its version, and report any problems that are found. See Section 7.2, “Configuring Yum on Broker Hosts” or Section 9.2, “Configuring Yum on Node Hosts” for more information on how to use the oo-admin-yum-validator command when required.
  2. Ensure all previously released errata relevant to your systems have been fully applied, including errata from required Red Hat Enterprise Linux channels and, if applicable, JBoss channels.
  3. On each host, install the updated packages. Note that running the yum update command on a host installs packages for all pending updates at once: 
    # yum update
  4. After the yum update command is completed, verify whether there are any additional update instructions that apply to the releases you have just installed. These instructions are provided in the "Asynchronous Errata Updates" chapter of the OpenShift Enterprise Release Notes at https://access.redhat.com/documentation relevant to your installed minor version.
    For example, if you have OpenShift Enterprise 2.1.3 installed and are updating to release 2.1.5, you must check for additional instructions for releases 2.1.4 and 2.1.5 in the OpenShift Enterprise 2.1 Release Notes at:
    https://access.redhat.com/documentation/en-US/OpenShift_Enterprise/2/html-single/2.1_Release_Notes/index.html#chap-Asynchronous_Errata_Updates
    Guidance on aggregating steps when applying multiple updates is provided as well. Additional steps can include restarting certain services, or using the oo-admin-upgrade command to apply certain cartridge changes. The update is complete after you have performed any additional steps that are required as described in the relevant OpenShift Enterprise Release Notes.