Chapter 6. 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 the Operator Lifecycle Manager
  • The broker container image for an Operator-based broker deployment

6.1. Before you begin

This section describes some important considerations before you upgrade the Operator and broker container images for an Operator-based broker deployment.

  • To upgrade an Operator-based broker deployment running 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. Then, you must create a new Operator-based broker deployment that matches your existing deployment. To learn how to create a new Operator-based broker deployment, see Chapter 3, Deploying AMQ Broker on OpenShift Container Platform using the AMQ Broker Operator.
  • Upgrading an Operator deployment using either the OpenShift command-line interface (CLI) or the Operator Lifecycle Manager requires cluster administrator privileges for your OpenShift cluster.
  • You cannot directly upgrade version 0.6 of the Operator (that is, the Technical Preview version available in AMQ Broker 7.4) to later versions, including the latest version for AMQ Broker 7.8. 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:

  • The procedures in this section show how to manually upgrade your image specifications between minor versions (for example, from 0.17 to 0.18 or 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 from Red Hat, 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.8. If the deployment currently uses minor version 7.8-5, and a newer minor version, 7.8-6, becomes available, 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.

6.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.8.

For an alternative method of upgrading the AMQ Broker Operator that uses the OperatorHub graphical interface, see Section 6.3.2, “Upgrading the Operator using OperatorHub”.

6.2.1. Upgrading version 0.17 of the Operator

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

Procedure

  1. In your web browser, navigate to the Software Downloads page for AMQ Broker 7.8.0 releases.
  2. Ensure that the value of the Version drop-down list is set to 7.8.0 and the Releases tab is selected.
  3. Next to AMQ Broker 7.8 Operator Installation Files, click Download.

    Download of the amq-broker-operator-7.8.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.8.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.8.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 broker Custom Resource (CR) instance in your project. This also deletes the broker deployment. 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.8 from Red Hat.

    spec:
        template:
            spec:
                containers:
                    image: registry.redhat.io/amq7/amq-broker-rhel7-operator:0.18
  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.4.1, “Deploying a basic broker instance”.

6.2.2. 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 first version available for AMQ Broker 7.7) to the latest version for AMQ Broker 7.8.

Procedure

  1. In your web browser, navigate to the Software Downloads page for AMQ Broker 7.8.0 releases.
  2. Ensure that the value of the Version drop-down list is set to 7.8.0 and the Releases tab is selected.
  3. Next to AMQ Broker 7.8 Operator Installation Files, click Download.

    Download of the amq-broker-operator-7.8.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.8.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.8.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 broker Custom Resource (CR) instance in your project. This also deletes the broker deployment. 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.8 from Red Hat.

    spec:
        template:
            spec:
                containers:
                    image: registry.redhat.io/amq7/amq-broker-rhel7-operator:0.18
  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.4.1, “Deploying a basic broker instance”.

6.2.3. 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.8.

Procedure

  1. In your web browser, navigate to the Software Downloads page for AMQ Broker 7.8.0 releases.
  2. Ensure that the value of the Version drop-down list is set to 7.8.0 and the Releases tab is selected.
  3. Next to AMQ Broker 7.8 Operator Installation Files, click Download.

    Download of the amq-broker-operator-7.8.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.8.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.8.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 broker Custom Resource (CR) instance in your project. This also deletes the broker deployment. 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.8.

    $ 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.8, 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.8 from Red Hat.

    spec:
        template:
            spec:
                containers:
                    image: registry.redhat.io/amq7/amq-broker-rhel7-operator:0.18
  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.

6.2.4. 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.8.

Procedure

  1. In your web browser, navigate to the Software Downloads page for AMQ Broker 7.8.0 releases.
  2. Ensure that the value of the Version drop-down list is set to 7.8.0 and the Releases tab is selected.
  3. Next to AMQ Broker 7.8 Operator Installation Files, click Download.

    Download of the amq-broker-operator-7.8.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.8.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.8.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 broker Custom Resource (CR) instance in your project. This also deletes the broker deployment. 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.8.

    $ 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.8.

    $ 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.8, 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.8 from Red Hat.

    spec:
        template:
            spec:
                containers:
                    image: registry.redhat.io/amq7/amq-broker-rhel7-operator:0.18
  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.4.1, “Deploying a basic broker instance”.

6.3. Upgrading the Operator using the Operator Lifecycle Manager

This section describes how to use the the Operator Lifecycle Manager and OperatorHub graphical interface to upgrade different versions of the Operator to the latest version available for AMQ Broker 7.8.

For an alternative method of upgrading the AMQ Broker Operator that uses the OpenShift command-line interface (CLI), see Section 6.2, “Upgrading the Operator using the CLI”.

6.3.1. Before you begin

This section describes some important considerations before you use OperatorHub to upgrade an instance of the AMQ Broker Operator.

  • 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.8. 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.17 of the Operator (that is, the latest version available for AMQ Broker 7.7), version 0.15 (the first version available for AMQ Broker 7.7), version 0.13 (the version available for AMQ Broker 7.6), or version 0.9 (the version available for AMQ Broker 7.5, or the Long Term Support version available for AMQ Broker 7.4), the Operator Lifecycle Manager 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.
  • 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.
  • 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.

6.3.2. Upgrading the Operator using OperatorHub

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

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 AdministrationCustom 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 to 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 OperatorsInstalled 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.8. See Section 3.2.1, “Getting the Operator code”.
    2. Remove existing CRDs in your cluster and manually deploy the latest CRDs. See Section 3.2.2, “Deploying the Operator using the CLI”.
  5. Use OperatorHub to install the latest version of the Operator for AMQ Broker 7.8. For more information, see Section 3.3.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.4.1, “Deploying a basic broker instance”.

6.4. Upgrading the broker container image

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

6.4.1. Choosing an upgrade method

Upgrading the broker container image by specifying an image tag or by specifying an AMQ Broker version both involve editing the Custom Resource (CR) instance used to create your broker 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 Ecosystem Catalog. Instead, when you update the CR to specify a AMQ Broker version (for example, 7.8.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.8-5.

The broker container 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_780. 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 container image tag is statically defined in the Operator deployment. The Operator is not able to dynamically search the Red Hat Ecosystem Catalog 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 be a combination of both upgrade approaches.

6.4.2. 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 at least version 0.13 of the Operator (that is, 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 version 0.13 or greater of the AMQ Broker Operator is 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. Edit the main broker CR instance for the broker deployment.

    1. Using the OpenShift command-line interface:

      1. Log in to OpenShift as a user that has privileges to edit and deploy CRs in the project for the broker deployment:

        $ oc login -u <user> -p <password> --server=<host:port>
      2. In a text editor, open the CR file that you used for your broker deployment. For example, this might be the broker_activemqartemis_cr.yaml file that was included in the deploy/crs directory of the Operator installation archive that you previously downloaded and extracted.
    2. Using the OpenShift Container Platform web console:

      1. Log in to the console as a user that has privileges to edit the CR for your broker deployment.
      2. In the left pane, click AdministrationCustom Resource Definitions
      3. Click the ActiveMQArtemis CRD.
      4. Click the Instances tab.
      5. Locate the CR instance that corresponds to your project namespace.
      6. For your CR instance, click the More Options icon (three vertical dots) on the right-hand side. Select Edit ActiveMQArtemis.

        Within the console, a YAML editor opens, enabling you to edit the CR instance.

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

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

    In the preceding step, you specify a floating image tag (that is, 7.8) rather than a full image tag (for example, 7.8-5). When you specify this floating tag and apply the changes, your deployment automatically pulls and uses the latest image available in the 7.8 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.8-6, 7.8-7, and so on) when they become available from Red Hat.

  3. Apply the changes to the CR.

    1. Using the OpenShift command-line interface:

      1. Save the CR file.
      2. Switch to the project for the broker deployment.

        $ oc project <project-name>
      3. Apply the CR.

        $ oc apply -f <path/to/broker-custom-resource-instance>.yaml
    2. Using the OpenShift web console:

      1. When you have finished editing the CR, click Save.

    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.

6.4.3. 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. Edit the main broker CR instance for the broker deployment.

    1. Using the OpenShift command-line interface:

      1. Log in to OpenShift as a user that has privileges to edit and deploy CRs in the project for the broker deployment:

        $ oc login -u <user> -p <password> --server=<host:port>
      2. In a text editor, open the CR file that you used for your broker deployment. For example, this might be the broker_activemqartemis_cr.yaml file that was included in the deploy/crs directory of the Operator installation archive that you previously downloaded and extracted.
    2. Using the OpenShift Container Platform web console:

      1. Log in to the console as a user that has privileges to edit and deploy CRs in the project for the broker deployment.
      2. In the left pane, click AdministrationCustom Resource Definitions
      3. Click the ActiveMQArtemis CRD.
      4. Click the Instances tab.
      5. Locate the CR instance that corresponds to your project namespace.
      6. For your CR instance, click the More Options icon (three vertical dots) on the right-hand side. Select Edit ActiveMQArtemis.

        Within the console, a YAML editor opens, enabling you to edit the CR instance.

  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.7.0 and 7.8.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.8.0
        ...
        upgrades:
            enabled: true
            minor: true
  4. Apply the changes to the CR.

    1. Using the OpenShift command-line interface:

      1. Save the CR file.
      2. Switch to the project for the broker deployment.

        $ oc project <project-name>
      3. Apply the CR.

        $ oc apply -f <path/to/broker-custom-resource-instance>.yaml
    2. Using the OpenShift web console:

      1. When you have finished editing the CR, click Save.

    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.8-5.

    The broker container 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_780.

    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.8-5