Chapter 10. Upgrading AMQ Streams

1. Upgrade AMQ Streams to version 1.7 following the standard sequence.
2. Convert AMQ Streams custom resources to v1beta2 using the Red Hat AMQ Streams API Conversion Tool provided with AMQ Streams 1.8.

3. Do one of the following:

   • Upgrade to AMQ Streams 1.8 (where the ControlPlaneListener feature gate is disabled by default).
   • Upgrade to AMQ Streams 2.0 or 2.2 (where the ControlPlaneListener feature gate is enabled by default) with the ControlPlaneListener feature gate disabled.
4. Enable the ControlPlaneListener feature gate.
5. Upgrade to AMQ Streams 2.3 following the standard sequence.

1. Upgrade to AMQ Streams 1.7.
2. Download the Red Hat AMQ Streams API Conversion Tool provided with AMQ Streams 1.8.

3. Convert custom resources and CRDs to v1beta2.

   For more information, see the AMQ Streams 1.7 upgrade documentation.

4. In the OperatorHub, delete version 1.7 of the Red Hat Integration - AMQ Streams Operator.

5. If it also exists, delete version 2.3 of the Red Hat Integration - AMQ Streams Operator.

   If it does not exist, go to the next step.

   If the Approval Strategy for the AMQ Streams Operator was set to Automatic, version 2.3 of the operator might already exist in your cluster. If you did not convert custom resources and CRDs to the v1beta2 API version before release, the operator-managed custom resources and CRDs will be using the old API version. As a result, the 2.3 Operator is stuck in Pending status. In this situation, you need to delete version 2.3 of the Red Hat Integration - AMQ Streams Operator as well as version 1.7.

   If you delete both operators, reconciliations are paused until the new operator version is installed. Follow the next steps immediately so that any changes to custom resources are not delayed.

6. In the OperatorHub, do one of the following:

   • Upgrade to version 1.8 of the Red Hat Integration - AMQ Streams Operator (where the ControlPlaneListener feature gate is disabled by default).
   • Upgrade to version 2.0 or 2.2 of the Red Hat Integration - AMQ Streams Operator (where the ControlPlaneListener feature gate is enabled by default) with the ControlPlaneListener feature gate disabled.

7. Upgrade to version 2.3 of the Red Hat Integration - AMQ Streams Operator immediately.

   The installed 2.3 operator begins to watch the cluster and performs rolling updates. You might notice a temporary decrease in cluster performance during this process.

Procedure

1. Take note of any configuration changes made to the existing Cluster Operator resources (in the /install/cluster-operator directory). Any changes will be overwritten by the new version of the Cluster Operator.
2. Update your custom resources to reflect the supported configuration options available for AMQ Streams version 2.3.

3. Update the Cluster Operator.

   1. Modify the installation files for the new Cluster Operator version according to the namespace the Cluster Operator is running in.

      On Linux, use:

      sed -i 's/namespace: .*/namespace: my-cluster-operator-namespace/' install/cluster-operator/*RoleBinding*.yaml

      On MacOS, use:

      sed -i '' 's/namespace: .*/namespace: my-cluster-operator-namespace/' install/cluster-operator/*RoleBinding*.yaml

   2. If you modified one or more environment variables in your existing Cluster Operator Deployment, edit the install/cluster-operator/060-Deployment-strimzi-cluster-operator.yaml file to use those environment variables.

4. When you have an updated configuration, deploy it along with the rest of the installation resources:

   oc replace -f install/cluster-operator

   Wait for the rolling updates to complete.

5. If the new Operator version no longer supports the Kafka version you are upgrading from, the Cluster Operator returns an error message to say the version is not supported. Otherwise, no error message is returned.

   • If the error message is returned, upgrade to a Kafka version that is supported by the new Cluster Operator version:

     1. Edit the Kafka custom resource.
     2. Change the spec.kafka.version property to a supported Kafka version.
   • If the error message is not returned, go to the next step. You will upgrade the Kafka version later.

6. Get the image for the Kafka pod to ensure the upgrade was successful:

   oc get pods my-cluster-kafka-0 -o jsonpath='{.spec.containers[0].image}'

   The image tag shows the new Operator version. For example:

   registry.redhat.io/amq7/amq-streams-kafka-33-rhel8:2.3.0

Broker-level consumers first strategy

1. Upgrade all the consuming applications.
2. Change the broker-level log.message.format.version to the new version.
3. Upgrade all the producing applications.

1. Upgrade all the consuming applications.
2. Change the topic-level message.format.version to the new version.
3. Upgrade all the producing applications.

1. Change the topic-level message.format.version to the old version (or rely on the topic defaulting to the broker-level log.message.format.version).
2. Upgrade all the consuming and producing applications.
3. Verify that the upgraded applications function correctly.
4. Change the topic-level message.format.version to the new version.

Procedure

1. Update the Kafka cluster configuration:

   oc edit kafka <my_cluster>

2. If configured, check that the inter.broker.protocol.version and log.message.format.version properties are set to the current version.

   For example, the current version is 3.2 if upgrading from Kafka version 3.2.3 to 3.3.1:

   kind: Kafka
   spec:
     # ...
     kafka:
       version: 3.2.3
       config:
         log.message.format.version: "3.2"
         inter.broker.protocol.version: "3.2"
         # ...

   If log.message.format.version and inter.broker.protocol.version are not configured, AMQ Streams automatically updates these versions to the current defaults after the update to the Kafka version in the next step.

   Note

   The value of log.message.format.version and inter.broker.protocol.version must be strings to prevent them from being interpreted as floating point numbers.

3. Change the Kafka.spec.kafka.version to specify the new Kafka version; leave the log.message.format.version and inter.broker.protocol.version at the defaults for the current Kafka version.

   Note

   Changing the kafka.version ensures that all brokers in the cluster will be upgraded to start using the new broker binaries. During this process, some brokers are using the old binaries while others have already upgraded to the new ones. Leaving the inter.broker.protocol.version unchanged at the current setting ensures that the brokers can continue to communicate with each other throughout the upgrade.

   For example, if upgrading from Kafka 3.2.3 to 3.3.1:

   apiVersion: kafka.strimzi.io/v1beta2
   kind: Kafka
   spec:
     # ...
     kafka:
       version: 3.3.1 1
       config:
         log.message.format.version: "3.2" 2
         inter.broker.protocol.version: "3.2" 3
         # ...

   1

   Kafka version is changed to the new version.

   2

   Message format version is unchanged.

   3

   Inter-broker protocol version is unchanged.

   Warning

   You cannot downgrade Kafka if the inter.broker.protocol.version for the new Kafka version changes. The inter-broker protocol version determines the schemas used for persistent metadata stored by the broker, including messages written to __consumer_offsets. The downgraded cluster will not understand the messages.

4. If the image for the Kafka cluster is defined in the Kafka custom resource, in Kafka.spec.kafka.image, update the image to point to a container image with the new Kafka version.

   See Kafka version and image mappings

5. Save and exit the editor, then wait for rolling updates to complete.

   Check the progress of the rolling updates by watching the pod state transitions:

   oc get pods my-cluster-kafka-0 -o jsonpath='{.spec.containers[0].image}'

   The rolling updates ensure that each pod is using the broker binaries for the new version of Kafka.

6. Depending on your chosen strategy for upgrading clients, upgrade all client applications to use the new version of the client binaries.

   If required, set the version property for Kafka Connect and MirrorMaker as the new version of Kafka:

   1. For Kafka Connect, update KafkaConnect.spec.version.
   2. For MirrorMaker, update KafkaMirrorMaker.spec.version.
   3. For MirrorMaker 2.0, update KafkaMirrorMaker2.spec.version.

7. If configured, update the Kafka resource to use the new inter.broker.protocol.version version. Otherwise, go to step 9.

   For example, if upgrading to Kafka 3.3.1:

   apiVersion: kafka.strimzi.io/v1beta2
   kind: Kafka
   spec:
     # ...
     kafka:
       version: 3.3.1
       config:
         log.message.format.version: "3.2"
         inter.broker.protocol.version: "3.3"
         # ...

8. Wait for the Cluster Operator to update the cluster.

9. If configured, update the Kafka resource to use the new log.message.format.version version. Otherwise, go to step 10.

   For example, if upgrading to Kafka 3.3.1:

   apiVersion: kafka.strimzi.io/v1beta2
   kind: Kafka
   spec:
     # ...
     kafka:
       version: 3.3.1
       config:
         log.message.format.version: "3.3"
         inter.broker.protocol.version: "3.3"
         # ...

   Important

   From Kafka 3.0.0, when the inter.broker.protocol.version is set to 3.0 or higher, the log.message.format.version option is ignored and doesn’t need to be set.

10. Wait for the Cluster Operator to update the cluster.

    • The Kafka cluster and clients are now using the new Kafka version.
    • The brokers are configured to send messages using the inter-broker protocol version and message format version of the new version of Kafka.