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 OperatorHub 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.5 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 the Operator using either the OpenShift command-line interface (CLI) or OperatorHub requires cluster administrator privileges for your OpenShift cluster. If you originally used the CLI to install the Operator, you should also use the CLI to upgrade the Operator. If you originally used OperatorHub to install the Operator (that is, it appears under Operators Installed Operators for your project in the OpenShift Container Platform web console), you should also use OperatorHub to upgrade the Operator. For more information about these upgrade methods, see: Section 6.2, "Upgrading the Operator using the CLI" Section 6.3.3, "Upgrading the Operator using OperatorHub" If you want to deploy the Operator to watch many namespaces, for example to watch all namespaces, you must: Make sure you have backed up all the CRs relating to broker deployments in your cluster. Uninstall the existing Operator. Deploy the 7.9 Operator to watch the namespaces you require. Check all your deployments and recreate if necessary. 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.9. 6.2.1. Prerequisites You should use the CLI to upgrade the Operator only if you originally used the CLI to install the Operator. If you originally used OperatorHub to install the Operator (that is, the Operator appears under Operators Installed Operators for your project in the OpenShift Container Platform web console), you should use OperatorHub to upgrade the Operator. To learn how to upgrade the Operator using OperatorHub, see Section 6.3, "Upgrading the Operator using OperatorHub" . 6.2.2. Upgrading version 7.8.x of the Operator This procedure shows to how to use the OpenShift command-line interface (CLI) to upgrade version 7.8.x of the Operator to the latest version for AMQ Broker 7.9. Procedure In your web browser, navigate to the Software Downloads page for AMQ Broker 7.9.4 patches . Ensure that the value of the Version drop-down list is set to 7.9.4 and the Patches tab is selected. to AMQ Broker 7.9.4 Operator Installation and Example Files , click Download . Download of the amq-broker-operator-7.9.4-ocp-install-examples.zip compressed archive automatically begins. 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.9.4-ocp-install-examples.zip ~/broker/operator In your chosen installation directory, extract the contents of the archive. For example: cd ~/broker/operator unzip amq-broker-operator-7.9.4-ocp-install-examples.zip Log in to OpenShift Container Platform as an administrator for the project that contains your existing Operator deployment. USD oc login -u <user> Switch to the OpenShift project in which you want to upgrade your Operator version. USD oc project <project-name> In the deploy directory of the latest Operator archive that you downloaded and extracted, open the operator.yaml file. Note In the operator.yaml file, the Operator uses an image that is represented by a Secure Hash Algorithm (SHA) value. The comment line, which begins with a number sign ( # ) symbol, denotes that the SHA value corresponds to a specific container image tag. Open the operator.yaml file for your Operator deployment. Check that any non-default values that you specified in your configuration are replicated in the new operator.yaml configuration file. If you have made any updates to the new operator.yaml file, save the file. Apply the updated Operator configuration. USD oc apply -f deploy/operator.yaml OpenShift updates your project to use the latest Operator version. To recreate your broker deployment, create a new CR yaml file to match the purpose of your original CR and apply it. Section 3.4.1, "Deploying a basic broker instance" . describes how to apply the deploy/crs/broker_activemqartemis_cr.yaml file in the Operator installation archive, you can use that file as a basis for your new CR yaml file. 6.3. Upgrading the Operator using OperatorHub This section describes how to use OperatorHub to upgrade different versions of the Operator to the latest version available for AMQ Broker 7.9. 6.3.1. Prerequisites You should use OperatorHub to upgrade the Operator only if you originally used OperatorHub to install the Operator (that is, the Operator appears under Operators Installed Operators for your project in the OpenShift Container Platform web console). By contrast, if you originally used the OpenShift command-line interface (CLI) to install the Operator, you should also use the CLI to upgrade the Operator. To learn how to upgrade the Operator using the CLI, see Section 6.2, "Upgrading the Operator using the CLI" . Upgrading the AMQ Broker Operator using OperatorHub requires cluster administrator privileges for your OpenShift cluster. 6.3.2. Before you begin This section describes some important considerations before you use OperatorHub to upgrade an instance of the AMQ Broker Operator. 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. 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 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.3. Upgrading the Operator using OperatorHub This procedure shows how to use OperatorHub to upgrade an instance of the AMQ Broker Operator. Procedure Log in to the OpenShift Container Platform web console as a cluster administrator. Delete the main Custom Resource (CR) instance for the broker deployment in your project. This action deletes the broker deployment. In the left navigation menu, click Administration Custom Resource Definitions . On the Custom Resource Definitions page, click the ActiveMQArtemis CRD. Click the Instances tab. Locate the CR instance that corresponds to your project namespace. For your CR instance, click the More Options icon (three vertical dots) on the right-hand side. Select Delete ActiveMQArtemis . Uninstall the existing AMQ Broker Operator from your project. In the left navigation menu, click Operators Installed Operators . From the Project drop-down menu at the top of the page, select the project in which you want to uninstall the Operator. Locate the Red Hat Integration - AMQ Broker instance that you want to uninstall. For your Operator instance, click the More Options icon (three vertical dots) on the right-hand side. Select Uninstall Operator . On the confirmation dialog box, click Uninstall . Use OperatorHub to install the latest version of the Operator for AMQ Broker 7.9. For more information, see Section 3.3.2, "Deploying the Operator from OperatorHub" . To recreate your broker deployment, create a new CR yaml file to match the purpose of your original CR and apply it. Section 3.4.1, "Deploying a basic broker instance" . describes how to apply the deploy/crs/broker_activemqartemis_cr.yaml file in the Operator installation archive, you can use that file as a basis for your new CR yaml file. 6.4. 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 broker deployment by specifying an AMQ Broker version. You might do this, for example, if you upgrade the Operator to the latest version for AMQ Broker 7.9.4 but the spec.upgrades.enabled property in your CR is already set to true and the spec.version property specifies 7.8.0 . To upgrade the broker container image, you need to manually specify a new AMQ Broker version (for example, 7.9.4 ). When you specify a new version of AMQ Broker, the Operator automatically chooses the broker container image that corresponds to this version. Prerequisites You must be using the latest version of the Operator for 7.9.4. To learn how to upgrade the Operator to the latest version, see: Section 6.2, "Upgrading the Operator using the CLI" Section 6.3.3, "Upgrading the Operator using OperatorHub" . As described in Section 2.4, "How the Operator chooses container images" , if you deploy a CR and do not explicitly specify a broker container image, the Operator automatically chooses the appropriate container image to use. To use the upgrade process described in this section, you must use this default behavior. If you override the default behavior by directly specifying a broker container image in your CR, the Operator cannot automatically upgrade the broker container image to correspond to an AMQ Broker version as described below. Procedure Edit the main broker CR instance for the broker deployment. Using the OpenShift command-line interface: Log in to OpenShift as a user that has privileges to edit and deploy CRs in the project for the broker deployment. 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. Using the OpenShift Container Platform web console: Log in to the console as a user that has privileges to edit and deploy CRs in the project for the broker deployment. In the left pane, click Administration Custom Resource Definitions . Click the ActiveMQArtemis CRD. Click the Instances tab. Locate the CR instance that corresponds to your project namespace. 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. To specify a version of AMQ Broker to which to upgrade the broker container image, set a value for the spec.version property of the CR. For example: spec: version: 7.9.4 ... In the spec section of the CR, locate the upgrades section. If this section is not already included in the CR, add it. spec: version: 7.9.4 ... upgrades: Ensure that the upgrades section includes the enabled and minor properties. spec: version: 7.9.4 ... upgrades: enabled: minor: To enable an upgrade of the broker container image based on a specified version of AMQ Broker, set the value of the enabled property to true . spec: version: 7.9.4 ... upgrades: enabled: true minor: To define the upgrade behavior of the broker, set a value for the minor property. To allow upgrades between minor AMQ Broker versions, set the value of minor to true . spec: version: 7.9.0 ... upgrades: enabled: true minor: true For example, suppose that the current broker container image corresponds to 7.8.0 , and a new image, corresponding to the 7.9.0 version specified for spec.version , is available. In this case, the Operator determines that there is an available upgrade between the 7.8 and 7.9 minor versions. Based on the preceding settings, which allow upgrades between minor versions, the Operator upgrades the broker container image. By contrast, suppose that the current broker container image corresponds to 7.9.0 , and you specify a new value of 7.9.1 for spec.version . If an image corresponding to 7.9.1 exists, the Operator determines that there is an available upgrade between 7.9.0 and 7.9.1 micro versions. Based on the preceding settings, which allow upgrades only between minor versions, the Operator does not upgrade the broker container image. To allow upgrades between micro AMQ Broker versions, set the value of minor to false . spec: version: 7.9.0 ... upgrades: enabled: true minor: false For example, suppose that the current broker container image corresponds to 7.8.0 , and a new image, corresponding to the 7.9.0 version specified for spec.version , is available. In this case, the Operator determines that there is an available upgrade between the 7.8 and 7.9 minor versions. Based on the preceding settings, which do not allow upgrades between minor versions (that is, only between micro versions), the Operator does not upgrade the broker container image. By contrast, suppose that the current broker container image corresponds to 7.9.0 , and you specify a new value of 7.9.1 for spec.version . If an image corresponding to 7.9.1 exists, the Operator determines that there is an available upgrade between 7.9.0 and 7.9.1 micro versions. Based on the preceding settings, which allow upgrades between micro versions, the Operator upgrades the broker container image. Apply the changes to the CR. Using the OpenShift command-line interface: Save the CR file. Switch to the project for the broker deployment. Apply the CR. Using the OpenShift web console: When you have finished editing the CR, click Save . When you apply the CR change, the Operator first validates that an upgrade to the AMQ Broker version specified for spec.version is available 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 available, and the values specified for upgrades.enabled and upgrades.minor allow the upgrade, then the Operator upgrades each broker in the deployment to use the broker container image that corresponds to the new AMQ Broker version. The broker container image that the Operator uses is defined in an environment variable in the operator.yaml configuration file of the Operator deployment. The environment variable name includes an identifier for the AMQ Broker version. For example, the environment variable RELATED_IMAGE_ActiveMQ_Artemis_Broker_Kubernetes_791 corresponds to AMQ Broker 7.9.1. 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. Additional resources To learn how the Operator uses environment variables to choose a broker container image, see Section 2.4, "How the Operator chooses container images" .

Commands:
mkdir ~/broker/operator mv amq-broker-operator-7.9.4-ocp-install-examples.zip ~/broker/operator
cd ~/broker/operator unzip amq-broker-operator-7.9.4-ocp-install-examples.zip
oc login -u <user>
oc project <project-name>
oc apply -f deploy/operator.yaml
oc login -u <user> -p <password> --server= <host:port>
spec: version: 7.9.4
spec: version: 7.9.4 upgrades:
spec: version: 7.9.4 upgrades: enabled: minor:
spec: version: 7.9.4 upgrades: enabled: true minor:
spec: version: 7.9.0 upgrades: enabled: true minor: true
spec: version: 7.9.0 upgrades: enabled: true minor: false
oc project <project_name>
oc apply -f <path/to/broker_custom_resource_instance> .yaml