Chapter 4. Upgrading broker deployments on OpenShift Container Platform

The procedures in this section show how to upgrade:

  • The version for an existing instance of the AMQ Broker Operator, using both the OpenShift command-line interface (CLI) and the Operator Lifecycle Manager
  • The broker container image for both Operator- and templates-based broker deployments
Note

The procedures in this section show to manually upgrade your image specifications between major versions, as represented by floating tags (for example, from 7.x to 7.y). When you specify a floating tag such as 7.y in your image specification, your deployment automatically pulls and uses a new minor image version (that is, 7.y-z) when it becomes available in the Red Hat Container Registry, provided that the imagePullPolicy attribute in your Stateful Set or Deployment Config is set to Always.

For example, suppose that the image attribute of your deployment specifies a floating tag of 7.6. If the deployment currently uses minor version 7.6-2, and a newer minor version, 7.6-3, becomes available in the registry, then your deployment automatically pulls and uses the new minor version. To use the new image, each broker in the deployment is restarted. If you have multiple brokers in your deployment, brokers are restarted one at a time.

Important

To upgrade an existing AMQ Broker deployment on OpenShift Container Platform 3.11 to run on OpenShift Container Platform 4.1 or later, 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 an Operator-based broker deployment

The following procedures show you how to upgrade:

  • The broker container image for an Operator-based broker deployment
  • The Operator version used by your OpenShift project

4.1.1. Upgrading the broker container image for an Operator-based deployment

The following procedure shows how to upgrade the broker container image for a broker deployment based on the AMQ Broker Operator.

Note

The procedure assumes that you used the Operator for AMQ Broker 7.5 (version 0.9) to create your previous broker deployment. The name of the main broker Custom Resource (CR) instance included with 0.9-x versions of the Operator was broker_v2alpha1_activemqartemis_cr.yaml.

You can also use instructions similar to those below to upgrade the broker container image for a deployment based on the Operator for AMQ Broker 7.4 (version 0.6). The name of the main broker Custom Resource (CR) instance included with 0.6-x versions of the Operator was broker_v1alpha1_activemqartemis_cr.yaml.

Prerequisites

Procedure

  1. In the deploy/crs directory of the Operator archive that you downloaded and extracted during your previous installation, open the broker_v2alpha1_activemqartemis_cr.yaml Custom Resource (CR).

  2. Edit the image element to specify the latest AMQ Broker 7.6 container image, as shown below. 

    image: registry.redhat.io/amq7/amq-broker:7.6

  3. Apply the CR change. 

    $ oc apply -f deploy/crs/broker_v2alpha1_activemqartemis_cr.yaml

    When you apply the CR change, each broker Pod in your deployment shuts down and then restarts using the new broker container image. If you have multiple brokers in your deployment, only one broker Pod shuts down and restarts at a time.

4.1.2. Upgrading the Operator using the CLI

This procedure shows to how to use the OpenShift command-line interface (CLI) to upgrade an installation of the Operator for AMQ Broker 7.5 (version 0.9) to the latest version for AMQ Broker 7.6.

Important
  • As part of the Operator upgrade, you must delete and then recreate any existing broker deployment in your project. These steps are described in the procedure that follows.
  • You cannot directly upgrade an Operator installation for AMQ Broker 7.4 (version 0.6) to the latest version for AMQ Broker 7.6. The Custom Resource Definitions (CRDs) used by version 0.6 are not compatible with the latest version of the Operator. To upgrade your Operator from version 0.6, you must delete your previously-deployed CRDs before performing a new installation of the Operator. When you have installed the new version of the Operator, you then need to recreate your broker deployments. For more information, see Section 2.3, “Installing the AMQ Broker Operator using the CLI”.
  • For an alternative method of upgrading the AMQ Broker Operator that uses the OperatorHub graphical interface, see Section 4.1.3, “Upgrading the Operator using the Operator Lifecycle Manager”.

Prerequisites

  • You previously installed and deployed an instance of the Operator for AMQ Broker 7.5 (version 0.9).

Procedure

  1. In your web browser, navigate to the AMQ Broker Software Downloads page.
  2. In the Version drop-down box, ensure that the value is set to the latest Broker version, 7.6.0.

  3. Next to AMQ Broker 7.6 Operator Installation Files, click Download.

    Download of the amq-broker-operator-7.6.0-ocp-install-examples.zip compressed archive automatically begins.

  4. When the download has completed, move the archive to your chosen installation directory. The following example moves the archive to a directory called /broker/operator. 

    sudo mv amq-broker-operator-7.6.0-ocp-install-examples.zip /broker/operator

  5. In your chosen installation directory, extract the contents of the archive. For example: 

    cd /broker/operator
sudo unzip amq-broker-operator-7.6.0-ocp-install-examples.zip

  6. Log in to OpenShift Container Platform as a cluster administrator. For example: 

    $ oc login -u system:admin

  7. Switch to the OpenShift project in which you want to upgrade your Operator version. 

    $ oc project <project_name>

  8. Delete the main CR for the existing broker deployment in your project. For example: 

    $ oc delete -f deploy/crs/broker_v2alpha1_activemqartemis_cr.yaml

  9. Update the main broker CRD in your OpenShift cluster to the latest version included with AMQ Broker 7.6. 

    $ oc apply -f deploy/crds/broker_activemqartemis_crd.yaml
    Note

    You do not need to update your cluster with the latest versions of the CRDs for addressing or the scaledown controller. In AMQ Broker 7.6, these CRDs are fully compatible with those included with AMQ Broker 7.5.

  10. In the deploy directory of the Operator archive that you downloaded and extracted during your previous installation, open the operator.yaml file.

  11. Update the spec.containers.image attribute to specify the full path to the latest AMQ Broker Operator image for AMQ Broker 7.6 in the Red Hat Container Registry. 

    spec:
    template:
        spec:
            containers:
                image: registry.redhat.io/amq7/amq-broker-rhel7-operator:0.13

  12. When you have updated the spec.containers.image attribute to specify your desired Operator version, apply the changes. 

    $ oc apply -f deploy/operator.yaml

    OpenShift updates your project to use the latest Operator version.

  13. To recreate your previous broker deployment, deploy a new instance of the main broker CR in your project. For more information, see Section 2.5, “Deploying a basic broker”.

4.1.3. Upgrading the Operator using the Operator Lifecycle Manager

This procedure shows how to use the Operator Lifecycle Manager (OLM) to upgrade an instance of the AMQ Broker Operator.

Important
  • In AMQ Broker 7.6, you cannot use the OLM to seamlessly upgrade a previous installation of the AMQ Broker Operator to the latest version for AMQ Broker 7.6. Instead, you must first uninstall the existing Operator and then install the latest version from OperatorHub, as described in the procedure that follows. As part of this upgrade, you must also delete and then recreate any existing broker deployment in your project.
  • If you plan to upgrade an installation of the Operator for AMQ Broker 7.4 (version 0.6) to the latest version for AMQ Broker 7.6, you must delete the Custom Resource Definitions (CRDs) previously deployed in your cluster, before performing a new installation of the Operator. These steps are described in the procedure that follows.

Procedure

  1. Log in to OpenShift Container Platform as an administrator. For example: 

    $ oc login -u system:admin

  2. Switch to the OpenShift project in which you want to upgrade your Operator version. 

    $ oc project <project_name>

  3. Delete the main Custom Resource (CR) for the existing broker deployment in your project. For example: 

    $ oc delete -f deploy/crs/broker_v2alpha1_activemqartemis_cr.yaml
  4. Log in to the OpenShift Container Platform web console as a cluster administrator.

  5. In the OpenShift Container Platform web console, uninstall the existing AMQ Broker Operator.

    1. Click Operators → Installed Operators.
    2. From the Projects drop-down menu, select the project in which you want to uninstall the Operator.
    3. From the Actions drop-down menu in the top-right corner, select Uninstall Operator.
    4. On the Remove Operator Subscription dialog box, ensure that the check box entitled Also completely remove the Operator from the selected namespace is selected.
    5. Click Remove.

  6. If you are upgrading the AMQ Broker 7.4 Operator (that is, version 0.6):

    1. Access the latest CRDs included with AMQ Broker 7.6. See Section 2.3.1, “Getting the Operator code”.

    2. Remove existing CRDs in your cluster and manually deploy the latest CRDs. See Section 2.3.2, “Deploying the AMQ Broker Operator using the CLI”.

      Note
      • If you are upgrading the AMQ Broker 7.5 Operator (that is, version 0.9), the OLM automatically updates the CRDs in your OpenShift cluster when you install the latest Operator version from OperatorHub. You do not need to remove existing CRDs.
      • When you update your cluster with the latest CRDs, this update affects all projects in the cluster. In particular, any broker Pods previously deployed from version 0.6 or version 0.9 of the AMQ Broker Operator become unable to update their status in the OpenShift Container Platform web console. When you click the Logs tab of a running broker Pod, you see messages in the log indicating that 'UpdatePodStatus' has failed. Despite this update failure, however, the broker Pods and broker Operator in that project continue to work as expected. To fix this issue for an affected project, that project must also use the latest version of the AMQ Broker Operator.
  7. Use OperatorHub to install the latest version of the Operator for AMQ Broker 7.6. For more information, see Section 2.4.3, “Deploying the AMQ Broker Operator from OperatorHub”.
  8. To recreate your previous broker deployment, deploy a new instance of the main broker CR in your project. For more information, see Section 2.5, “Deploying a basic broker”.

4.2. Upgrading a templates-based broker deployment

The following procedures show how to upgrade the broker container image for a deployment that is 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 AMQ Broker 7.6 container image, registry.redhat.io/amq7/amq-broker:7.6.

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

    Changes based on the previous two steps are shown in the example below: 

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

    In AMQ Broker, container image tags increment by 1 for each new version of the container image added to the Red Hat image registry, for example, 7.6-1, 7.6-2, and so on. If you specify a tag name without a final digit (7.6, for example), this tag is known as a floating tag. When you specify a floating tag, OpenShift Container Platform automatically identifies the most recent available image (that is, the image tag with the highest final number) and uses this image to upgrade your broker deployment.

  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 AMQ Broker 7.6 container image, registry.redhat.io/amq7/amq-broker:7.6.

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

    Changes based on the previous two steps are shown in the example below: 

    ...
spec:
    containers:
        image: 'registry.redhat.io/amq7/amq-broker:7.6'
..
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.