// This module is included in the following assemblies:
//
// assembly-upgrade.adoc

[id='proc-upgrade-kafka-kraft-{context}']
= Upgrading KRaft-based Kafka clusters and client applications

[role="_abstract"]
Upgrade a KRaft-based Strimzi Kafka cluster to a newer supported Kafka version and KRaft metadata version.

You should also choose a xref:con-strategies-for-upgrading-clients-{context}[strategy for upgrading clients].
Kafka clients are upgraded in step 6 of this procedure.

NOTE: Refer to the Apache Kafka documentation for the latest on support for KRaft-based upgrades.

.Prerequisites

* The Cluster Operator is up and running.
* Before you upgrade the Strimzi Kafka cluster, check that the properties of the `Kafka` resource do _not_ contain configuration options that are not supported in the new Kafka version.

.Procedure

. Update the Kafka cluster configuration:
+
[source,shell,subs=+quotes]
----
kubectl edit kafka <kafka_configuration_file>
----

. If configured, check that the current `spec.kafka.metadataVersion` is set to a version supported by the version of Kafka you are upgrading to.
+
For example, the current version is {KafkaMetadataVersionLower} if upgrading from Kafka version {KafkaVersionLower} to {KafkaVersionHigher}:
+
[source,yaml,subs=attributes+]
----
apiVersion: {KafkaApiVersion}
kind: Kafka
metadata:
  name: my-cluster
spec:
  kafka:
    replicas: 3
    metadataVersion: {KafkaMetadataVersionLower}
    version: {KafkaVersionLower}
    # ...
----
+
If `metadataVersion` is not configured,
Strimzi automatically updates it to the current default after the update to the Kafka version in the next step.
+
NOTE: The value of `metadataVersion` must be a string to prevent it from being interpreted as a floating point number.

. Change the `Kafka.spec.kafka.version` to specify the new Kafka version; leave the `metadataVersion` at the default for the _current_ Kafka version.
+
[NOTE]
====
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 `metadataVersion` unchanged at the current setting ensures that the Kafka brokers and controllers can continue to communicate with each other throughout the upgrade.
====
+
For example, if upgrading from Kafka {KafkaVersionLower} to {KafkaVersionHigher}:
+
[source,yaml,subs=attributes+]
----
apiVersion: {KafkaApiVersion}
kind: Kafka
metadata:
  name: my-cluster
spec:
  kafka:
    replicas: 3
    metadataVersion: {KafkaMetadataVersionLower} # <1>
    version: {KafkaVersionHigher} # <2>
    # ...
----
<1> Metadata version is unchanged
<2> Kafka version is changed to the new version.

. 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 xref:con-versions-and-images-str[Kafka version and image mappings]

. Save and exit the editor, then wait for the rolling updates to upgrade the Kafka nodes to complete.
+
Check the progress of the rolling updates by watching the pod state transitions:
+
[source,shell,subs=+quotes]
----
kubectl 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.

. Depending on your chosen xref:con-strategies-for-upgrading-clients-{context}[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:
+
.. For Kafka Connect, update `KafkaConnect.spec.version`.
.. For MirrorMaker, update `KafkaMirrorMaker.spec.version`.
.. For MirrorMaker 2, update `KafkaMirrorMaker2.spec.version`.
+
NOTE: 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 Strimzi base image. 
For example, if you xref:creating-new-image-from-base-str[created a container image from the base Kafka Connect image], update the Dockerfile to point to the latest base image and build configuration.

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

. If configured, update the Kafka resource to use the new `metadataVersion` version. Otherwise, go to step 9.
+
For example, if upgrading to Kafka {KafkaVersionHigher}:
+
[source,yaml,subs=attributes+]
----
apiVersion: {KafkaApiVersion}
kind: Kafka
metadata:
  name: my-cluster
spec:
  kafka:
    replicas: 3
    metadataVersion: {KafkaMetadataVersionHigher}
    version: {KafkaVersionHigher}
    # ...
----
+
WARNING: Exercise caution when changing the `metadataVersion`, as downgrading may not be possible. 
You cannot downgrade Kafka if the `metadataVersion` for the new Kafka version is higher than the Kafka version you wish to downgrade to. 
However, understand the potential implications on support and compatibility when maintaining an older version.

. Wait for the Cluster Operator to update the cluster.
+
You can xref:con-upgrade-status-{context}[check the upgrade has completed successfully from the status of the `Kafka` resource].