25.7. Upgrading Kafka when using ZooKeeper

Procedure

1. Update the Kafka cluster configuration:

   oc edit kafka <kafka_configuration_file>

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.6 if upgrading from Kafka version 3.6.0 to 3.7.0:

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

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

   注意

   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.

   注意

   Changing the kafka.version ensures that all brokers in the cluster are 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.6.0 to 3.7.0:

   apiVersion: kafka.strimzi.io/v1beta2
   kind: Kafka
   spec:
     # ...
     kafka:
       version: 3.7.0 

   1

   
       config:
         log.message.format.version: "3.6" 

   2

   
         inter.broker.protocol.version: "3.6" 

   3

   
         # ...

   1

   Kafka version is changed to the new version.

   2

   Message format version is unchanged.

   3

   Inter-broker protocol version is unchanged.

   警告

   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 Kafka.spec.kafka.image of the Kafka custom resource, 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, update KafkaMirrorMaker2.spec.version.

      注意

      If you are using custom images that are built manually, you must rebuild those images to ensure that they are up-to-date with the latest Streams for Apache Kafka base image. For example, if you created a container image from the base Kafka Connect image, update the Dockerfile to point to the latest base image and build configuration.

7. Verify that the upgraded client applications work correctly with the new Kafka brokers.

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

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

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

10. 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.7.0:

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

    重要

    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.

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

    You can check the upgrade has completed successfully from the status of the Kafka resource.