Chapter 5. Upgrading an Operator-based broker deployment

The procedures in this section show how to upgrade:

  • The AMQ Broker Operator version, using both the OpenShift command-line interface (CLI) and OperatorHub
  • The broker container image for an Operator-based broker deployment
Note

  • 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:

  • The procedures show how to manually upgrade your image specifications between minor versions (for example, from 7.x to 7.y). If you use a floating tag such as 7.y in your image specification, your deployment automatically pulls and uses new micro image versions (that is, 7.y-z) when they become 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.7. If the deployment currently uses minor version 7.7-2, and a newer minor version, 7.7-3, becomes available in the registry, then your deployment automatically pulls and uses the new minor version. To use the new image, each broker Pod in the deployment is restarted. If you have multiple brokers in your deployment, brokers Pods are restarted one at a time.

5.1. About upgrading Technical Preview-based deployments

Version 0.6 of the AMQ Broker Operator, which was first available in AMQ Broker 7.4.0, was a Technical Preview feature only. If you intend to upgrade the broker container image or Operator version for a broker deployment based on this version of the Operator, the list below describes some important considerations.

  • You cannot directly upgrade version 0.6 of the Operator to later versions, including the latest version for AMQ Broker 7.7. The Custom Resource Definitions (CRDs) used by version 0.6 are not compatible with later versions 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. To learn how to install the latest version of the Operator , see Section 3.1, “Installing the Operator using the CLI”.
  • When you update your cluster with the CRDs for the latest Operator version, this update affects all projects in the cluster. Any broker Pods previously deployed from version 0.6 of the Operator become unable to update their status. When you click the Logs tab of a running broker Pod in the OpenShift Container Platform web console, you see messages indicating that 'UpdatePodStatus' has failed. However, the broker Pods and Operator in that project continue to work as expected. To fix this issue for an affected project, you must also upgrade that project to use the latest version of the Operator.
  • Section 5.4, “Upgrading the broker container image” shows how to upgrade the broker container image for an Operator-based deployment. That procedure assumes that you used version 0.13 of the Operator to create your previous deployment. You can use similar instructions to upgrade the broker container image for a deployment based on version 0.6 of the Operator. The main broker Custom Resource (CR) instance included with version 0.6 was broker_v1alpha1_activemqartemis_cr.yaml.

5.2. Upgrading the Operator using the CLI

The procedures in this section show how to use the OpenShift command-line interface (CLI) to upgrade different versions of the Operator to the latest version available for AMQ Broker 7.7.

Note
  • For an alternative method of upgrading the AMQ Broker Operator that uses the OperatorHub graphical interface, see Section 5.3, “Upgrading the Operator using OperatorHub”.
  • Upgrading a AMQ Broker Operator deployment using either the OpenShift CLI or OperatorHub requires cluster administrator privileges for your OpenShift cluster.

5.2.1. Upgrading version 0.15 of the Operator

This procedure shows to how to use the OpenShift command-line interface (CLI) to upgrade version 0.15 of the Operator (that is, the previous version available for AMQ Broker 7.7) to the latest version for AMQ Broker 7.7.

Procedure

  1. In your web browser, navigate to the Software Downloads page for AMQ Broker 7.7.0 patches.
  2. Ensure that the value of the Version drop-down list is set to 7.7.0 and the Patches tab is selected.

  3. Next to AMQ Broker 7.7.0 Operator Installation and Example Files, click Download.

    Download of the amq-broker-operator-7.7.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. 

    mkdir ~/broker/operator
mv amq-broker-operator-7.7.0-ocp-install-examples.zip ~/broker/operator

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

    cd ~/broker/operator
unzip amq-broker-operator-7.7.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 Custom Resource (CR) for the existing broker deployment in your project. For example: 

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

  9. Update the main broker Custom Resource Definition (CRD) in your OpenShift cluster to the latest version. 

    $ 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. These CRDs are fully compatible with the ones included with the previous Operator version.

  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 property to specify the full path to the latest Operator image for AMQ Broker 7.7, as shown below. 

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

  12. When you have updated spec.containers.image, 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 3.3.1, “Deploying a basic broker instance”.

5.2.2. Upgrading version 0.13 of the Operator

This procedure shows to how to use the OpenShift command-line interface (CLI) to upgrade version 0.13 of the Operator (that is, the version available for AMQ Broker 7.6) to the latest version for AMQ Broker 7.7.

Procedure

  1. In your web browser, navigate to the Software Downloads page for AMQ Broker 7.7.0 patches.
  2. Ensure that the value of the Version drop-down list is set to 7.7.0 and the Patches tab is selected.

  3. Next to AMQ Broker 7.7.0 Operator Installation and Example Files, click Download.

    Download of the amq-broker-operator-7.7.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. 

    mkdir ~/broker/operator
mv amq-broker-operator-7.7.0-ocp-install-examples.zip ~/broker/operator

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

    cd ~/broker/operator
unzip amq-broker-operator-7.7.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 Custom Resource (CR) for the existing broker deployment in your project. For example: 

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

  9. Update the main broker Custom Resource Definition (CRD) in your OpenShift cluster to the latest version. 

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

  10. Update the address CRD in your OpenShift cluster to the latest version included with AMQ Broker 7.7. 

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

    You do not need to update your cluster with the latest version of the CRD for the scaledown controller. In AMQ Broker 7.7, this CRD is fully compatible with the one that was included with the Operator for AMQ Broker 7.6.

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

  12. Update the spec.containers.image property to specify the full path to the latest Operator image for AMQ Broker 7.7, as shown below. 

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

  13. When you have updated spec.containers.image, apply the changes. 

    $ oc apply -f deploy/operator.yaml

    OpenShift updates your project to use the latest Operator version.

5.2.3. Upgrading version 0.9 of the Operator

The following procedure shows how to use the OpenShift command-line interface (CLI) to upgrade version 0.9 of the Operator (that is, the version available for AMQ Broker 7.5 or the Long Term Support version available for AMQ Broker 7.4) to the latest version for AMQ Broker 7.7.

Important

As part of this Operator upgrade, you must delete and then recreate any existing broker deployment in your project. These steps are described in the procedure that follows.

Procedure

  1. In your web browser, navigate to the Software Downloads page for AMQ Broker 7.7.0 patches.
  2. Ensure that the value of the Version drop-down list is set to 7.7.0 and the Patches tab is selected.

  3. Next to AMQ Broker 7.7.0 Operator Installation and Example Files, click Download.

    Download of the amq-broker-operator-7.7.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. 

    mkdir ~/broker/operator
mv amq-broker-operator-7.7.0-ocp-install-examples.zip ~/broker/operator

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

    cd ~/broker/operator
unzip amq-broker-operator-7.7.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 Custom Resource (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 Custom Resource Definition (CRD) in your OpenShift cluster to the latest version included with AMQ Broker 7.7. 

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

  10. Update the address CRD in your OpenShift cluster to the latest version included with AMQ Broker 7.7. 

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

    You do not need to update your cluster with the latest version of the CRD for the scaledown controller. In AMQ Broker 7.7, this CRD is fully compatible with the one included with the previous Operator version.

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

  12. Update the spec.containers.image property to specify the full path to the latest Operator image for AMQ Broker 7.7, as shown below. 

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

  13. When you have updated spec.containers.image, apply the changes. 

    $ oc apply -f deploy/operator.yaml

    OpenShift updates your project to use the latest Operator version.

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

5.3. Upgrading the Operator using OperatorHub

This procedure shows how to use OperatorHub to upgrade an instance of the AMQ Broker Operator.

Important
  • Upgrading the AMQ Broker Operator using OperatorHub requires cluster administrator privileges for your OpenShift cluster.
  • You cannot use OperatorHub to seamlessly upgrade the Operator to the latest version for AMQ Broker 7.7. Instead, you must 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 are upgrading version 0.6 of the Operator (that is, the Technical Preview version that was available for AMQ Broker 7.4), you must also 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 the OpenShift Container Platform web console as a cluster administrator.

  2. Delete the main Custom Resource (CR) instance for the broker deployment in your project. This action deletes the broker deployment.

    1. In the left navigation menu, click Custom Resource Definitions.
    2. On the Custom Resource Definitions page, click the ActiveMQArtemis CRD.
    3. Click the Instances tab.
    4. Locate the CR instance that corresponds for your project namespace.
    5. For your CR instance, click the More Options icon (three vertical dots) on the right-hand side. Select Delete ActiveMQArtemis.

  3. Uninstall the existing AMQ Broker Operator from your project.

    1. In the left navigation menu, click Operators → Installed Operators.
    2. From the Project drop-down menu at the top of the page, select the project in which you want to uninstall the Operator.
    3. Locate the Red Hat Integration - AMQ Broker instance that you want to uninstall.
    4. For your Operator instance, click the More Options icon (three vertical dots) on the right-hand side. Select Uninstall Operator.
    5. On the confirmation dialog box, click Uninstall.

  4. If you are upgrading version 0.6 of the Operator (that is, the Technical Preview version that was available for AMQ Broker 7.4):

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

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

      Note
      • If you are upgrading version 0.15 of the Operator (that is, the first version available for AMQ Broker 7.7), version 0.13 (that is, the version available for AMQ Broker 7.6), or version 0.9 (that is, the version available for AMQ Broker 7.5, or the Long Term Support version available for AMQ Broker 7.4), the Operator Lifecycle Manager (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 CRDs for the latest Operator version, this update affects all projects in the cluster. Any broker Pods deployed from previous versions of the Operator might 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 indicating that 'UpdatePodStatus' has failed. However, the broker Pods and Operator in that project continue to work as expected. To fix this issue for an affected project, you must also upgrade that project to use the latest version of the Operator.
  5. Use OperatorHub to install the latest version of the Operator for AMQ Broker 7.7. For more information, see Section 3.2.3, “Deploying the Operator from OperatorHub”.
  6. To recreate your previous broker deployment, deploy a new instance of the main broker CR in your project. For more information, see Section 3.3.1, “Deploying a basic broker instance”.

5.4. Upgrading the broker container image

For an Operator-based broker deployment, the procedures in this section show how to:

Both approaches to upgrading the broker container image involve editing the Custom Resource (CR) instance used to create your deployment.

An advantage of upgrading the broker container image by specifying the AMQ Broker version is that you are not responsible for ensuring that the image tag specified in the CR corresponds to a valid image in the Red Hat Container Registry. Instead, when you update the CR to specify a AMQ Broker version (for example, 7.7.0), the Operator first validates that a direct upgrade to the specified version of AMQ Broker is possible for your existing deployment. If an upgrade is possible, the Operator updates the CR to specify a broker container image for the specified version of AMQ Broker, for example, registry.redhat.io/amq7/amq-broker:7.7-2. The broker image that the Operator specifies is defined by default in an environment variable in the Operator deployment. The environment variable name aligns with the AMQ Broker version, for example, BROKER_IMAGE_770. When the Operator has applied the CR change, it restarts each broker Pod in your deployment so that each Pod uses the specified image version.

A potential disadvantage of upgrading the broker container image by specifying the AMQ Broker version is that the broker image is statically defined in the Operator deployment. The Operator is not able to dynamically search the Red Hat Container Registry for newer image versions that have become available. For this reason, you might still want the option of manually updating the image tag after the Operator has performed an initial upgrade. Therefore, a strategy to ensure that a broker deployment continues to use the latest version of the broker container image might mix both upgrade approaches.

The procedures that follow show both approaches.

5.4.1. Upgrading the broker container image by specifying an image tag

The following procedure shows how to upgrade the broker container image for an Operator-based deployment by specifying an image tag.

Prerequisites

  • The procedure assumes that you used version 0.15 or 0.13 of the Operator (that is, the first version available for AMQ Broker 7.7 or the version available for AMQ Broker 7.6) to create your previous broker deployment. The name of the main broker Custom Resource (CR) instance included with those versions of the Operator was broker_activemqartemis_cr.yaml.

    You can use similar instructions to upgrade the broker container image for a deployment based on version 0.9 of the Operator (that is, the version available for AMQ Broker 7.5 or the Long Term Support version available for AMQ Broker 7.4). The name of the main broker CR included with version 0.9 of the Operator was broker_v2alpha1_activemqartemis_cr.yaml.

Procedure

  1. In the deploy/crs directory of the Operator archive that you downloaded and extracted during your previous installation, open the main broker CR, broker_activemqartemis_cr.yaml.

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

    spec:
    ...
    deploymentPlan:
        ...
        image: registry.redhat.io/amq7/amq-broker:7.7
    Note

    In the preceding step, you specify a floating image tag (that is, 7.7) rather than a full image tag (for example, 7.7-2). When you specify this floating tag and apply the changes, your deployment automatically pulls and uses the latest image available in the 7.7 image stream. In addition, when you specify a floating tag, if the imagePullPolicy attribute in your Stateful Set is set to Always, your deployment automatically pulls and uses new micro image versions (for example, 7.7-3, 7-7-4, and so on) when they become available in the Red Hat Container Registry.

  3. Save the CR file.

  4. Apply the CR change. 

    $ oc apply -f deploy/crs/broker_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.

5.4.2. Upgrading the broker container image by specifying an AMQ Broker version

The following procedure shows how to upgrade the broker container image for an Operator-based deployment by specifying an AMQ Broker version.

Prerequisites

Procedure

  1. In the deploy/crs directory of the Operator archive that you downloaded and extracted during your previous installation, open the main broker CR, broker_activemqartemis_cr.yaml.

  2. In the upgrades section of the CR, enable upgrades of the broker container image between minor versions of AMQ Broker, for example between 7.6.0 and 7.7.0. 

    spec:
    ...
    upgrades:
        enabled: true
        minor: true
    Note

    Both of the preceding options must be set to true to enable upgrades between minor versions of AMQ Broker.

  3. Update the version property of the CR to specify the minor version of AMQ Broker that you want the upgraded broker container image to correspond to. For example: 

    spec:
    version: 7.7.0
    ...
    upgrades:
        enabled: true
        minor: true
  4. Save the CR file.

  5. Apply the CR change. 

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

    When you apply the CR change, the Operator first validates that a direct upgrade to the specified version of AMQ Broker is possible for your existing deployment. If you have specified an invalid version of AMQ Broker to which to upgrade (for example, a version that is not yet available), the Operator logs a warning message, and takes no further action.

    However, if an upgrade to the specified version is possible, the Operator automatically modifies the CR instance for your deployment to specify a broker container image for the specified version of AMQ Broker, for example, registry.redhat.io/amq7/amq-broker:7.7-2. The default broker image that the Operator uses is defined in an environment variable in the Operator deployment. The environment variable name aligns with the AMQ Broker version, for example, BROKER_IMAGE_770. When the Operator has applied the CR change, it restarts each broker Pod in your deployment so that each Pod uses the specified image version. If you have multiple brokers in your deployment, only one broker Pod shuts down and restarts at a time.

    When you reopen or reload the CR, you see that the Operator has updated the image attribute. For example: 

    spec:
    ...
    deploymentPlan:
        ...
        image: registry.redhat.io/amq7/amq-broker:7.7-2