Chapter 4. Upgrading broker deployments on OpenShift Container Platform

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.

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”.

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”.

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.

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.