Chapter 6. Upgrading an Operator-based broker deployment

Procedure

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

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

   Download of the amq-broker-operator-7.10.7-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.10.7-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-operator-7.10.7-ocp-install-examples.zip

6. Log in to OpenShift Container Platform as an administrator for the project that contains your existing Operator deployment.

   $ oc login -u <user>

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

   $ oc project <project-name>

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

9. Open the operator.yaml file for your previous Operator deployment. Check that any non-default values that you specified in your previous configuration are replicated in the new operator.yaml configuration file.

10. In the new operator.yaml file, the Operator is named controller-manager by default. Replace all instances of controller-manager with amq-broker-operator, which was the name of the Operator in previous versions, and save the file. For example:

    spec:
    ...
      selector
        matchLabels
          name: amq-broker-operator
    ...

11. Update the CRDs that are included with the Operator. You must update the CRDs before you deploy the Operator.

    1. Update the main broker CRD.

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

    2. Update the address CRD.

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

    3. Update the scaledown controller CRD.

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

    4. Update the security CRD.

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

12. If you are upgrading from AMQ Broker Operator 7.10.0 only, delete the Operator and the StatefulSet.

    By default, the new Operator deletes the StatefulSet to remove custom and Operator metering labels, which were incorrectly added to the StatefulSet selector by the Operator in 7.10.0. When the Operator deletes the StatefulSet, it also deletes the existing broker Pods, which causes a temporary broker outage. If you want to avoid an outage, complete the following steps to delete the Operator and the StatefulSet without deleting the broker Pods.

    1. Delete the Operator.

       $ oc delete -f deploy/operator.yaml

    2. Delete the StatefulSet with the --cascade=orphan option to orphan the broker Pods. The orphaned broker Pods continue to run after the StatefulSet is deleted.

       $ oc delete statefulset <statefulset-name> --cascade=orphan

13. If you are upgrading from AMQ Broker Operator 7.10.0 or 7.10.1, check if your main broker CR has labels called application or ActiveMQArtemis configured in the deploymentPlan.labels attribute.

    These labels are reserved for the Operator to assign labels to Pods and are not permitted as custom labels after 7.10.1. If these custom labels were configured in the main broker CR, the Operator-assigned labels on the Pods were overwritten by the custom labels. If either of these custom labels are configured in the main broker CR, complete the following steps to restore the correct labels on the Pods and remove the labels from the CR.

    1. If you are upgrading from 7.10.0, you deleted the Operator in the previous step. If you are upgrading from 7.10.1, delete the Operator.

       $ oc delete -f deploy/operator.yaml

    2. Run the following command to restore the correct Pod labels. In the following example, 'ex-aao' is the name of the StatefulSet deployed.

       $ for pod in $(oc get pods | grep -o '^ex-aao[^ ]*') do; oc label --overwrite pods $pod ActiveMQArtemis=ex-aao application=ex-aao-app; done

    3. Delete the application and ActiveMQArtemis labels from the deploymentPlan.labels attribute in the CR.

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

          oc login -u <user> -p <password> --server=<host:port>

       2. Open the sample CR file called broker_activemqartemis_cr.yaml that was included in the deploy/crs directory of the Operator installation archive that you downloaded and extracted.
       3. In the deploymentPlan.labels attribute in the CR, delete any custom labels called application or ActiveMQArtemis.
       4. Save the CR file.

       5. Deploy the CR instance.

          1. Switch to the project for the broker deployment.

             $ oc project <project_name>

          2. Apply the CR.

             $ oc apply -f <path/to/broker_custom_resource_instance>.yaml

    4. If you deleted the previous Operator, deploy the new Operator.

        $ oc create -f deploy/operator.yaml

14. Apply the updated Operator configuration.

    $ oc apply -f deploy/operator.yaml

15. The new Operator can recognize and manage your previous broker deployments. If automatic updates are enabled in the CR of your deployment, the Operator’s reconciliation process upgrades each broker pod. If automatic updates are not enabled, you can enable them by setting the following attributes in your CR:

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

    For more information on enabling automatic updates, see, Section 6.4, “Upgrading the broker container image by specifying an AMQ Broker version”.

    Note

    If the reconciliation process does not start, you can start the process by scaling the deployment. For more information, see Section 3.4.1, “Deploying a basic broker instance”.

16. Add attributes to the CR for the new features that are available in the upgraded broker, as required.

Procedure

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

8. Use OperatorHub to install the latest version of the Operator for AMQ Broker 7.10. For more information, see Section 3.3.2, “Deploying the Operator from OperatorHub”.

   If automatic updates are enabled in the CR of your deployment, the Operator’s reconciliation process upgrades each broker pod when the new Operator starts. If automatic updates are not enabled, you can enable them by setting the following attributes in your CR:

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

   For more information on enabling automatic updates, see, Section 6.4, “Upgrading the broker container image by specifying an AMQ Broker version”.

   Note

   If the reconciliation process does not start, you can start the process by scaling the deployment. For more information, see Section 3.4.1, “Deploying a basic broker instance”.

Procedure

1. Log in to the OpenShift Container Platform web console as a cluster administrator.

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

3. When you upgrade a 7.10.0 Operator, the new Operator deletes the StatefulSet to remove custom and Operator metering labels, which were incorrectly added to the StatefulSet selector by the Operator in 7.10.0. When the Operator deletes the StatefulSet, it also deletes the existing broker pods, which causes a temporary broker outage. If you want to avoid the outage, complete the following steps to delete the StatefulSet and orphan the broker pods so that they continue to run.

   1. Log in to OpenShift Container Platform CLI as an administrator for the project that contains your existing Operator deployment:

      $ oc login -u <user>

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

      $ oc project <project-name>

   3. Delete the StatefulSet with the --cascade=orphan option to orphan the broker Pods. The orphaned broker Pods continue to run after the StatefulSet is deleted.

      $ oc delete statefulset <statefulset-name> --cascade=orphan

4. Check if your main broker CR has labels called application or ActiveMQArtemis configured in the deploymentPlan.labels attribute.

   In 7.10.0, it was possible to configure these custom labels in the CR. These labels are reserved for the Operator to assign labels to Pods and cannot be added as custom labels after 7.10.0. If these custom labels were configured in the main broker CR in 7.10.0, the Operator-assigned labels on the Pods were overwritten by the custom labels. If the CR has either of these labels, complete the following steps to restore the correct labels on the Pods and remove the labels from the CR.

   1. In the OpenShift command-line interface (CLI), run the following command to restore the correct Pod labels. In the following example, 'ex-aao' is the name of the StatefulSet deployed.

      $ for pod in $(oc get pods | grep -o '^ex-aao[^ ]*') do; oc label --overwrite pods $pod ActiveMQArtemis=ex-aao application=ex-aao-app; done

   2. Delete the application and ActiveMQArtemis labels from the deploymentPlan.labels attribute in the CR.

      1. Using the OpenShift command-line interface:

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

            oc login -u <user> -p <password> --server=<host:port>

         2. Open the sample CR file called broker_activemqartemis_cr.yaml that was included in the deploy/crs directory of the Operator installation archive that you downloaded and extracted.
         3. In the deploymentPlan.labels element in the CR, delete any custom labels called application or ActiveMQArtemis.
         4. Save the CR file.

         5. Deploy the CR instance.

            1. Switch to the project for the broker deployment.

               $ oc project <project_name>

            2. Apply the CR.

               $ oc apply -f <path/to/broker_custom_resource_instance>.yaml

      2. Using the OpenShift Container Platform web console:

         1. Log in to the console as a user that has privileges to deploy CRs in the project for the broker deployment.
         2. In the left pane, click Administration Custom Resource Definitions.
         3. Click the ActiveMQArtemis CRD.
         4. Click the Instances tab.
         5. Click the instance for your broker deployment.

         6. Click the YAML tab.

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

         7. In the deploymentPlan.labels element in the CR, delete any custom labels called application or ActiveMQArtemis.
         8. Click Save.

5. Use OperatorHub to install the latest version of the Operator for AMQ Broker 7.10. For more information, see Section 3.3.2, “Deploying the Operator from OperatorHub”.

   The new Operator can recognize and manage your previous broker deployments. If automatic updates are enabled in the CR of your deployment, the Operator’s reconciliation process upgrades each broker pod when the new Operator starts. If automatic updates are not enabled, you can enable them by setting the following attributes in your CR:

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

   For more information on enabling automatic updates, see, Section 6.4, “Upgrading the broker container image by specifying an AMQ Broker version”.

   Note

   If the reconciliation process does not start, you can start the process by scaling the deployment. For more information, see Section 3.4.1, “Deploying a basic broker instance”.

6. Add attributes to the CR for the new features that are available in the upgraded broker, as required.

Procedure

1. Log in to the OpenShift Container Platform web console as a cluster administrator.

2. Check if your main broker CR has labels called application or ActiveMQArtemis configured in the deploymentPlan.labels attribute.

   These labels are reserved for the Operator to assign labels to Pods and cannot be used after 7.10.1. If these custom labels were configured in the main broker CR, the Operator-assigned labels on the Pods were overwritten by the custom labels.

3. If these custom labels are not configured in the main broker CR, use OperatorHub to install the latest version of the Operator for AMQ Broker 7.10. For more information, see Section 3.3.2, “Deploying the Operator from OperatorHub”.

4. If either of these custom labels are configured in the main broker CR, complete the following steps to uninstall the existing Operator, restore the correct Pod labels and remove the labels from the CR, before you install the new Operator.

   Note

   By uninstalling the Operator, you can remove the custom labels without the Operator deleting the StatefulSet, which also deletes the existing broker pods and causes a temporary broker outage.

   1. 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 from 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.

   2. In the OpenShift command-line interface (CLI), run the following command to restore the correct Pod labels. In the following example, 'ex-aao' is the name of the StatefulSet deployed.

      $ for pod in $(oc get pods | grep -o '^ex-aao[^ ]*') do; oc label --overwrite pods $pod ActiveMQArtemis=ex-aao application=ex-aao-app; done

   3. Delete the application and ActiveMQArtemis labels from the deploymentPlan.labels attribute in the CR.

      1. Using the OpenShift command-line interface:

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

            oc login -u <user> -p <password> --server=<host:port>

         2. Open the sample CR file called broker_activemqartemis_cr.yaml that was included in the deploy/crs directory of the Operator installation archive that you downloaded and extracted.
         3. In the deploymentPlan.labels attribute in the CR, delete any custom labels called application or ActiveMQArtemis.
         4. Save the CR file.

         5. Deploy the CR instance.

            1. Switch to the project for the broker deployment.

               $ oc project <project_name>

            2. Apply the CR.

               $ oc apply -f <path/to/broker_custom_resource_instance>.yaml

      2. Using the OpenShift Container Platform web console:

         1. Log in to the console as a user that has privileges to deploy CRs in the project for the broker deployment.
         2. In the left pane, click Administration Custom Resource Definitions.
         3. Click the ActiveMQArtemis CRD.
         4. Click the Instances tab.
         5. Click the instance for your broker deployment.

         6. Click the YAML tab.

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

         7. In the deploymentPlan.labels attribute in the CR, delete any custom labels called application or ActiveMQArtemis.
         8. Click Save.

5. Use OperatorHub to install the latest version of the Operator for AMQ Broker 7.10. For more information, see Section 3.3.2, “Deploying the Operator from OperatorHub”.

   The new Operator can recognize and manage your previous broker deployments. If automatic updates are enabled in the CR of your deployment, the Operator’s reconciliation process upgrades each broker pod when the new Operator starts. If automatic updates are not enabled, you can enable them by setting the following attributes in your CR:

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

   For more information on enabling automatic updates, see, Section 6.4, “Upgrading the broker container image by specifying an AMQ Broker version”.

   Note

   If the reconciliation process does not start, you can start the process by scaling the deployment. For more information, see Section 3.4.1, “Deploying a basic broker instance”.

6. Add attributes to the CR for the new features that are available in the upgraded broker, as required.