Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 6. Upgrading an Operator-based broker deployment

Upgrading an Operator-based broker deployment involves upgrading both the Operator and the broker container images.

6.1. Before you begin
Copy link

Review planning considerations and best practices before upgrading your Operator-based broker deployment.

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

  • Upgrade the Operator and the broker images in two separate steps, beginning with the Operator upgrade, to ensure that the upgrade runs smoothly.

    To separate the upgrade of the broker images from the Operator upgrade, you must prevent the upgraded Operator from automatically upgrading the broker container images to the latest version supported by the new Operator. You can prevent this automatic upgrade by setting the version attribute in the CR. For example, you can set the value of the version attribute to the version of the broker images currently deployed, which is displayed in the status section of the CR. For more information, see Section 6.6.1, “Restricting automatic upgrades of broker images by using version numbers”.

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

  • Upgrading the Operator using either the OpenShift command-line interface (CLI) or OperatorHub requires cluster administrator privileges for your OpenShift cluster.

  • If the redeliveryDelayMultiplier and the redeliveryCollisionAvoidanceFactor attributes are configured in the main broker CR in a 7.8.x or 7.9.x deployment, the new Operator is unable to reconcile any CR after you upgrade to 7.10.x or later. The reconcile fails because the data type of both attributes changed from float to string in 7.10.x.

    You can work around this issue by deleting the redeliveryDelayMultiplier and the redeliveryCollisionAvoidanceFactor attributes from the spec.deploymentPlan.addressSettings.addressSetting attribute. Then, configure the attributes under the brokerProperties attribute. For example: 

    spec:
    ...
    brokerProperties:
    - "addressSettings.#.redeliveryMultiplier=2.1"
    - "addressSettings.#.redeliveryCollisionAvoidanceFactor=1.2"
    Note

    Under the brokerProperties attribute, use the redeliveryMultiplier attribute name instead of the redeliveryDelayMultiplier attribute name that you deleted.

6.2. Automatic Operator upgrades
Copy link

If you select automatic update approval when you install an Operator by using OperatorHub, the Operator is automatically updated to new micro versions that become available. For example, if the installed Operator version is 7.12.3, OperatorHub automatically upgrades the Operator to version 7.12.4.

Automatic upgrades between minor Operator versions are not supported. For example, if the current Operator is version 7.12.4, an automatic upgrade to version 7.13.x is not possible. To upgrade between minor versions of the Operator, you must manually uninstall the current Operator and install the new Operator from the channel where Operators for that minor version are made available. You can manually upgrade between minor versions of the Operator by using OperatorHub or the OpenShift command-line interface (CLI).

Note

Uninstalling the Operator has no effect on the brokers that are managed by the Operator provided that you do not select the Delete all operand instances for this operator checkbox during the uninstall procedure. For more information, see Section 6.3.2, “Upgrading the Operator”.

Use OperatorHub to upgrade the Operator only if you originally used OperatorHub to install the Operator (that is, the Operator is displayed under menu:Operators[Installed Operators] for your project in the OpenShift Container Platform web console).

If you originally used the OpenShift command-line interface (CLI) to install the Operator, use the CLI to upgrade the Operator. To learn how to upgrade the Operator by using the CLI, see Section 6.4, “Manually upgrading the Operator by using the OpenShift command-line interface (CLI)”.

Note

If you are upgrading from 7.10.0 or 7.10.1, see the specific sections that describe how to complete the upgrade of these versions of the Operator.

6.3.1. Before you begin
Copy link

Review planning considerations and best practices before you upgrade your Operator-based broker deployment by using OperatorHub.

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 must not remove existing CRDs. If you remove existing CRDs, all CRs and broker instances are also removed.
  • 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.

  • If you are upgrading from 7.10.0 or 7.10.1, see the specific sections that describe how to complete the upgrade of these versions of the Operator. Upgrading these versions requires additional steps to prevent the Operator upgrade from restarting the broker pods in the deployment.

    Section 6.3.3, “Upgrading the Operator from 7.10.0”

    Section 6.3.4, “Upgrading the Operator from 7.10.1”

6.3.2. Upgrading the Operator
Copy link

To complete a manual upgrade of the Operator, you must uninstall the Operator that is currently installed and install the new Operator.

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 menu: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.

    Warning

    Ensure that the Delete all operand instances for this operator checkbox is NOT selected. If this checkbox is selected, the broker instances that are managed by the Operator are deleted when the Operator is uninstalled.

  7. On the confirmation dialog box, click Uninstall.
  8. Use OperatorHub to install the latest version of the Operator for AMQ Broker 7.13. For more information, see Section 3.2.2, “Deploying the Operator from OperatorHub”.
  9. In the left navigation menu, click menu:Operators[Installed Operators].
  10. Verify that the correct version number is displayed under the Red Hat Integration - AMQ Broker instance that is installed.

6.3.3. Upgrading the Operator from 7.10.0
Copy link

You must uninstall the 7.10.0 Operator and install the new Operator to complete the upgrade. During this procedure you must complete additional steps to prevent the new Operator from restarting the broker pods in the deployment and causing an outage.

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 menu: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. Edit the CR for your deployment. 

          oc edit ActiveMQArtemis <statefulset name> -n <namespace>
        3. In the deploymentPlan.labels element in the CR, delete any custom labels called application or ActiveMQArtemis.
        4. Save the CR.

      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 menu: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.13. For more information, see Section 3.2.2, “Deploying the Operator from OperatorHub”.

    The new Operator can recognize and manage your previous broker deployments. If you set values in the image or version field in the CR, the Operator’s reconciliation process upgrades the broker pods to the corresponding images when the Operator starts. For more information, see Section 6.6, “Restricting automatic upgrades of broker container images”. Otherwise, the Operator upgrades each broker pod to the latest container image.

    Note

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

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

6.3.4. Upgrading the Operator from 7.10.1
Copy link

You must uninstall the 7.10.1 Operator and install the new Operator to complete the upgrade. Depending on your configuration, you might need to complete additional steps during the upgrade to prevent the new Operator from restarting the broker pods and causing an outage.

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.13. For more information, see Section 3.2.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 menu: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. Edit the CR for your deployment. 

          oc edit ActiveMQArtemis <statefulset name> -n <namespace>
        3. In the deploymentPlan.labels attribute in the CR, delete any custom labels called application or ActiveMQArtemis.
        4. Save the CR file.

      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 menu: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.13. For more information, see Section 3.2.2, “Deploying the Operator from OperatorHub”.

    The new Operator can recognize and manage your previous broker deployments. If you set values in the image or version field in the CR, the Operator’s reconciliation process upgrades the broker pods to the corresponding images when the Operator starts. For more information, see Section 6.6, “Restricting automatic upgrades of broker container images”. Otherwise, the Operator upgrades each broker pod to the latest container image.

    Note

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

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

You can use the CLI to upgrade the Operator if you originally used the CLI to install the Operator.

Procedure

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

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

    Download of the amq-broker-operator-7.13.4-ocp-install-examples-rhel8.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.13.4-ocp-install-examples-rhel8.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.13.4-ocp-install-examples-rhel8.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 amq-broker-controller-manager by default. If the name of the Operator in your previous deployment is not amq-broker-controller-manager, replace all instances of amq-broker-controller-manager with the previous Operator name. For example: 

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

  11. In the new operator.yaml file, the service account for the Operator is named amq-broker-controller-manager. In previous versions, the service account for the Operator was named amq-broker-operator.

    1. If you want to use the service account name in your previous deployment, replace the name of the service account in the new operator.yaml file with the name used in the previous deployment. For example: 

      spec:
  ...
  serviceAccountName: amq-broker-operator
  ...

    2. If you want to use the new service account name, amq-broker-controller-manager for the Operator, update the service account, role, and role binding in your project. 

      $ oc apply -f deploy/service_account.yaml
       
      $ oc apply -f deploy/role.yaml
       
      $ oc apply -f deploy/role_binding.yaml

  12. Update the CRDs that are included with 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

  13. 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
      Note

      Deleting the Operator does not remove the broker instances that are managed by the Operator.

    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

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

  15. Apply the updated Operator configuration. 

    $ oc apply -f deploy/operator.yaml
  16. Add attributes to the CR for the new features that are available in the upgraded broker, as required.

6.5. Upgrading broker container images
Copy link

After the Operator is upgraded, it can manage multiple versions of AMQ Broker. You can find the precise list of versions supported by the new Operator in the Operator log.

The following is an example of the log entry showing the list of broker versions supported by the Operator.

INFO setup Version of the operator: 7.13.4.OPR.1 2024-08-14T15:04:17 INFO setup Supported ActiveMQArtemis Kubernetes Image Versions: 7.12.0 7.12.1 7.12.2 7.12.3 7.12.4 7.13.0 7.13.1 7.13.2 7.13.3 7.13.4 …​.

If, as recommended, you configured the version attribute in the custom resource to prevent the new Operator from automatically upgrading the broker images at the same time as the Operator upgrade, you can change the version number to upgrade the broker images. For more information, see Section 6.6, “Restricting automatic upgrades of broker container images”.

Note

If the version attribute is not configured in the custom resource, the Operator automatically upgrades each broker it manages to the latest available version of the broker container image that the Operator supports. For a 7.13.4 Operator, the latest version of the broker container images supported is 7.13.4.

By default, the Operator automatically upgrades each broker it manages to the latest available images that the Operator supports. You can restrict the ability of the Operator to upgrade the images by configuring a version number or the URLs of specific container images in the broker custom resource.

You can prevent the Operator from automatically upgrading to the latest broker container images by specifying a version number in the custom resource (CR).

Note

When you restrict upgrades based on version numbers, the Operator continues to automatically upgrade the brokers to use any new images that contain security fixes for the version deployed.

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. Edit the CR. 

        $ oc edit ActiveMQArtemis <CR instance name> -n <namespace>

    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 menu:Operators[Installed Operator].
      3. Click the Red Hat Integration - AMQ Broker for RHEL 9 (Multiarch) operator.
      4. Click the AMQ Broker tab.
      5. Click the name of the ActiveMQArtemis instance name.

      6. Click the YAML tab.

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

        Note

        In the status section of the CR, the .status.version.brokerVersion field shows the version of AMQ Broker that is currently deployed.

  2. In the spec.version attribute, specify the version to which the Operator can upgrade the broker and init container images in your deployment. The following are examples of values that you can specify.

    Examples

    In the following example, the Operator upgrades the current container images in your deployment to 7.13.0. 

    spec:
   version: '7.13.0'
    ...

    In the following example, the Operator upgrades the current container images in your deployment to the latest available 7.12.x images. For example, if your deployment is using 7.12.1 container images, the Operator automatically upgrades the images to 7.12.4 but not to 7.13.4. 

    spec:
    version: '7.12'
    ...

    In the following example, the Operator upgrades the current container images in your deployment to the latest 7.x.x images. For example, if your deployment is using 7.12.4 images, the Operator automatically upgrades the images to 7.13.4. 

    spec:
    version: '7'
    ...
    Note

    To upgrade between minor versions of the container images, for example, from 7.12.x to 7.13.x, you require an Operator that has the same minor version as that of the new container images. For example, to upgrade from 7.12.4 to 7.13.4, a 7.13.x Operator must be installed.

  3. Save the CR.

    Important

    If you use the spec.version attribute in the CR to restrict automatic upgrades of broker container images, ensure that the CR does not also contain a spec.deploymentPlan.image or a spec.deploymentPlan.initImage attribute. Both of these attributes override the spec.version attribute. If the CR has one of these attributes as well as the spec.version attribute, the versions of the broker and init images deployed can diverge, which might prevent the broker from running.

    When you save the CR, the Operator first validates that an upgrade to the AMQ Broker version specified for spec.version is available for your existing deployment. If you 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, then the Operator upgrades each broker in the deployment to use the broker container images that correspond 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_7134 corresponds to AMQ Broker 7.13.4.

    When the Operator applies 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

You can prevent the Operator from automatically upgrading to the latest broker images by specifying the registry URLs of the images to deploy in the custom resource (CR). After the Operator deploys the specified images, no further upgrades occur until you replace the image URLs in the CR.

Note

If you restrict updates by specifying broker image URLs in the CR, the Operator does not automatically upgrade the brokers to use newer images that contain security fixes for the images deployed.

Important

If you want to restrict automatic upgrades by using image URLs, specify URLs for both the spec.deploymentPlan.image and the spec.deploymentPlan.initImage attributes in the CR to ensure that the broker and init container images match. If you specify the URL of one container image only, the broker and init container image can diverge, which might prevent the broker from running.

Note

If a CR has a spec.version attribute in addition to spec.deploymentPlan.image and spec.deploymentPlan.initImage attributes, the Operator ignores the spec.version attribute.

Procedure

  1. Obtain the URLs of the broker and init container images to which the Operator can upgrade the current images.

    1. In the Red Hat Catalog, open the broker container component page: AMQ Broker for RHEL 9 (Multiarch).
    2. In the Architecture drop-down, select your architecture.
    3. In the Tag drop-down, select the tag that corresponds to the image you want to install. Tags are displayed in chronological order based on the release date. A tag consists of the release version and an assigned tag.
    4. Open the Get this image tab.
    5. In the Manifest field, click the Copy icon.
    6. Paste the URL into a text file.
    7. In the Red Hat Catalog, open the init container component page: AMQ Broker Init for RHEL 9 (Multiarch)
    8. To obtain the URL of the init container image, repeat the steps that you followed to obtain the URL of the broker container image.

  2. 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. Edit the CR. 

         oc edit ActiveMQArtemis <CR instance name> -n <namespace>

    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 menu:Operators[Installed Operator].
      3. Click the Red Hat Integration - AMQ Broker for RHEL 9 (Multiarch) operator.
      4. Click the AMQ Broker tab.
      5. Click the name of the ActiveMQArtemis instance name.

      6. Click the YAML tab.

        Within the console, a YAML editor opens, which enables you to configure the CR instance

    3. Copy the URLs of the broker and init container images that you recorded in the text file and insert them in the spec.deploymentPlan.image and spec.deploymentPlan.initImage fields in the CR. For example: 

      spec:
  ...
  deploymentPlan:
    image: registry.redhat.io/amq7/amq-broker-rhel8@994c9a1499fa1c991e18a9e2387d7b77decb9ff9eac3feeb129d56c8d1c7cd84
    initImage: registry.redhat.io/amq7/amq-broker-init-rhel8@94baced8fab3b8d15351dabb47de9600add2ee333e7d15b8b6037ecd84dcc532
  ...

  3. Save the CR.

    When you save the CR, the Operator upgrades the brokers to use the new images and uses these images until you update the values of the spec.deploymentPlan.image and spec.deploymentPlan.initImage attributes again.

  4. If you want to prevent future Operator upgrades from restarting the brokers in your deployment, edit the CR and specify the version number of the brokers that are deployed in the spec.version attribute.

    If the spec.version attribute is not configured in the CR, subsequent upgrades of the Operator cause the broker pods to restart. The pod restart is required because the new Operator adds the latest supported broker version to a label in the StatefulSet unless a version number is explicitly set in the spec.version attribute.

    You can find the version number value to specify for the spec.version attribute in the status section of the CR after the brokers start. For more information, see Viewing status information for your broker deployment.

    Note

    If you already deployed AMQ Broker without setting image URLs, you can set the image URLs retrospectively to prevent the Operator from upgrading the current images deployed. You can find the registry URLs for the images deployed in the .status.version.image and .status.version.initImage attributes, which are in the status section of the CR.

    If you copy the image URLs from the .status.version.image and .status.version.initImage attributes and insert them in the spec.deploymentPlan.image and the spec.deploymentPlan.initImage attributes, the Operator does not upgrade the images currently deployed.

Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2026 Red HatBack to top