Chapter 4. Upgrading AMQ Broker on OpenShift Container Platform

Important
  • AMQ Broker 7.4 has been designated as a Long Term Support (LTS) release version. Bug fixes and security advisories will be made available for AMQ Broker 7.4 in a series of micro releases (7.4.1, 7.4.2, 7.4.3, and so on) for a period of at least 12 months. This means that you will be able to get recent bug fixes and security advisories for AMQ Broker without having to upgrade to a new minor release.

  • To remain in a supported configuration, you must upgrade to the latest micro release in the LTS release stream.

  • To upgrade an existing AMQ Broker deployment on OpenShift Container Platform 3.11 to run on OpenShift Container Platform 4.1, you must first upgrade your OpenShift Container Platform installation, before performing a clean installation of AMQ Broker that matches your existing deployment. To perform a clean AMQ Broker installation, use one of these methods:

4.1. Upgrading Operator-based broker deployments

This section provides information about updating the Operator version used by your OpenShift project.

4.1.1. Upgrading the Operator

Version 0.6 of the AMQ Broker Operator was a Technology Preview feature only. If you have version 0.6 of the Operator installed in an OpenShift project, it is recommended that you update the Operator to the latest Long Term Support (LTS) version. The latest LTS version of the Operator includes fixes for bugs and security advisories. Red Hat supports LTS versions of the Operator for production use.

Described below are some important things to note about upgrading the Technical Preview version of the Operator to the latest LTS version.

Important
  • The Custom Resource Definitions (CRDs) used by version 0.6 of the Operator are not compatible with the Long Term Support (LTS) version. For this reason, you cannot perform a seamless upgrade of the Operator. To upgrade your Operator from version 0.6, you must delete the CRDs previously deployed in your OpenShift cluster. You must also remove the existing Operator and broker deployment from any project in which you want to install the LTS version of the Operator.
  • When you update an OpenShift cluster with the latest CRDs, this update affects all projects in the cluster. Any broker Pods previously deployed from version 0.6 no longer work. You should update each affected project in the OpenShift cluster to use the LTS version of the Operator. Then, you can deploy Custom Resources (CRs) included with the LTS version of the Operator to recreate your previous broker deployments.
  • When you deploy a new CR to recreate a previous broker deployment, you can specify the latest broker container image in the LTS stream in your CR.

For instructions on installing the LTS version of the Operator and creating new broker deployments, see Deploying AMQ Broker on OpenShift Container Platform using an Operator.

4.2. Upgrading a templates-based broker deployment

The following procedures show how to upgrade the broker container image for broker deployments based on application templates.

4.2.1. Upgrading non-persistent broker deployments

This procedure shows you how to upgrade a non-persistent broker deployment. The non-persistent broker templates in the OpenShift Container Platform service catalog have labels that resemble the following:

  • Red Hat AMQ Broker 7.x (Ephemeral, no SSL)
  • Red Hat AMQ Broker 7.x (Ephemeral, with SSL)
  • Red Hat AMQ Broker 7.x (Custom Config, Ephemeral, no SSL)

Prerequisites

  • Starting in AMQ Broker 7.3, you use a new version of the Red Hat Container Registry to access container images. This new version of the registry requires you to become an authenticated user before you can access images and pull them into an OpenShift project. Before following the procedure in this section, you must first complete the steps described in Red Hat Container Registry Authentication.

Procedure

  1. Navigate to the OpenShift Container Platform web console and log in.
  2. Click the project in which you want to upgrade a non-persistent broker deployment.

  3. Select the Deployment Config (DC) corresponding to your broker deployment.

    1. In OpenShift Container Platform 4.1, click Workloads → Deployment Configs.
    2. In OpenShift Container Platform 3.11, click Applications → Deployments. Within your broker deployment, click the Configuration tab.

  4. From the Actions menu, click Edit Deployment Config (OpenShift Container Platform 4.1) or Edit YAML (OpenShift Container Platform 3.11).

    The YAML tab of the Deployment Config opens, with the .yaml file in an editable mode.

  5. Edit the image attribute to specify the latest broker container image in the Long Term Support (LTS) image stream. 

    ...
spec:
    containers:
          image: 'registry.redhat.io/amq7/amq-broker-lts-rhel7:7.4'
    Note

    If you specify a tag format such as 7.4 for the image attribute (rather than a tag with a specific version identifier, such as 7.4-6), this tag format is known as a floating tag. When you specify a floating tag, OpenShift Container Platform automatically identifies the most recent available image in the specified repository and uses this image to upgrade your broker deployment.

  6. Add the imagePullSecrets attribute to specify the image pull secret associated with the account used for authentication in the Red Hat Container Registry. 

    ...
spec:
    containers:
          image: 'registry.redhat.io/amq7/amq-broker-lts-rhel7:7.4'
..
imagePullSecrets:
  - name: {PULL-SECRET-NAME}

  7. Click Save.

    If a newer broker image than the one currently installed is available in the Red Hat Container Registry, OpenShift Container Platform upgrades your broker deployment. To do this, OpenShift Container Platform stops the existing broker Pod and then starts a new Pod that uses the new image.

4.2.2. Upgrading persistent broker deployments

This procedure shows you how to upgrade a persistent broker deployment. The persistent broker templates in the OpenShift Container Platform service catalog have labels that resemble the following:

  • Red Hat AMQ Broker 7.x (Persistence, clustered, no SSL)
  • Red Hat AMQ Broker 7.x (Persistence, clustered, with SSL)
  • Red Hat AMQ Broker 7.x (Persistence, with SSL)

Prerequisites

  • Starting in AMQ Broker 7.3, you use a new version of the Red Hat Container Registry to access container images. This new version of the registry requires you to become an authenticated user before you can access images and pull them into an OpenShift project. Before following the procedure in this section, you must first complete the steps described in Red Hat Container Registry Authentication.

Procedure

  1. Navigate to the OpenShift Container Platform web console and log in.
  2. Click the project in which you want to upgrade a persistent broker deployment.

  3. Select the StatefulSet (SS) corresponding to your broker deployment.

    1. In OpenShift Container Platform 4.1, click Workloads → Stateful Sets.
    2. In OpenShift Container Platform 3.11, click Applications → Stateful Sets.

  4. From the Actions menu, click Edit Stateful Set (OpenShift Container Platform 4.1) or Edit YAML (OpenShift Container Platform 3.11).

    The YAML tab of the StatefulSet opens, with the .yaml file in an editable mode.

  5. To prepare your broker deployment for upgrade, scale the deployment down to zero brokers.

    1. If the replicas attribute is currently set to 1 or greater, set it to 0.
    2. Click Save.

  6. When all broker Pods have shut down, edit the Stateful Set .yaml file again. Edit the image attribute to specify the latest broker container image in the LTS image stream. 

    ...
spec:
    containers:
          image: 'registry.redhat.io/amq7/amq-broker-lts-rhel7:7.4'
    Note

    If you specify a tag format such as 7.4 for the image attribute (rather than a tag with a specific version identifier, such as 7.4-6), this tag format is known as a floating tag. When you specify a floating tag, OpenShift Container Platform automatically identifies the most recent available image in the specified repository and uses this image to upgrade your broker deployment.

  7. Add the imagePullSecrets attribute to specify the image pull secret associated with the account used for authentication in the Red Hat Container Registry. 

    ...
spec:
    containers:
          image: 'registry.redhat.io/amq7/amq-broker-lts-rhel7:7.4'
..
imagePullSecrets:
  - name: {PULL-SECRET-NAME}
  8. Set the replicas attribute back to the original value.

  9. Click Save.

    If a newer broker image than the one currently installed is available in the Red Hat Container Registry, OpenShift Container Platform upgrades your broker deployment. To do this, OpenShift Container Platform restarts the broker Pod.