// This module is included in the following assemblies:
//
// assembly-upgrading-kafka-versions.adoc

[id='proc-upgrading-brokers-newer-kafka-0-9-0-to-0-10-0-{context}']

= Upgrading brokers to a newer Kafka version

This procedure describes how to upgrade a {ProductName} Kafka cluster from one version to a higher version; for example 2.0.0 to 2.1.0.

.Prerequisites

* The Cluster Operator, which supports both versions of Kafka, is up and running.
* A `Kafka` resource to be upgraded.
* You have checked that your `Kafka.spec.kafka.config` contains no options that are not supported in the version of Kafka that you are upgrading to.

.Procedure

. Consult the table below and determine whether the new Kafka version has a different log message format version than the previous version. 
+
include::snip-kafka-versions.adoc[leveloffset=+1]
+
If the log message format versions are the same proceed to the next step. 
Otherwise, ensure the `Kafka.spec.kafka.config` has the `log.message.format.version` configured to the default for the previous version.
+
For example, if upgrading from 2.0.0:
+
[source,yaml]
----
apiVersion: v1alpha1
kind: Kafka
spec:
  # ...
  kafka:
    version: 2.0.0
    config:
      log.message.format.version: "2.0"
      # ...
----
+
NOTE: You must format the value of `log.message.format.version` as a string to prevent it from being interpreted as a number.
+
If `log.message.format.version` is unset then set it and wait for the resulting rolling restart of the Kafka cluster to complete.
+
[start=2]
. Change the `Kafka.spec.kafka.version` to specify the new version, but leave the `log.message.format.version` as the previous version.
If the image to be used is different from the image for the given version of Kafka configured in the Cluster Operator's `STRIMZI_KAFKA_IMAGES` then configure the `Kafka.spec.kafka.image` as well.
+
For example, if upgrading from Kafka 2.0.0 to 2.1.0:
+
[source,yaml]
----
apiVersion: v1alpha1
kind: Kafka
spec:
  # ...
  kafka:
    version: 2.1.0 <1>
    config:
      log.message.format.version: "2.0" <2>
      # ...
----
<1> This is changed to the new version
<2> This remains at the previous version

. Wait for the Cluster Operator to upgrade the cluster.
If the old and new versions of Kafka have different interbroker protocol versions, look in the Cluster Operator logs for an `INFO` level message in the following format:
+
[source,subs="+quotes"]
----
Reconciliation #_<num>_(watch) Kafka(_<namespace>_/_<name>_): Kafka version upgrade from _<from-version>_ to _<to-version>_, phase 2 of 2 completed
----
Alternatively, if the old and new versions of Kafka have the same interbroker protocol version, look in the Cluster Operator logs for an `INFO` level message  in the following format:
+
[source,subs="+quotes"]
----
Reconciliation #_<num>_(watch) Kafka(_<namespace>_/_<name>_): Kafka version upgrade from _<from-version>_ to _<to-version>_, phase 1 of 1 completed
----
+
For example, using `grep`:
+
[source,shell,subs="+quotes"]
----
oc logs -f _<cluster-operator-pod-name>_ | grep -E "Kafka version upgrade from [0-9.]+ to [0-9.]+, phase ([0-9]+) of \1 completed"
----

. Upgrade all your client applications to use the new version of the client libraries.
+
WARNING: You cannot downgrade after completing this step. If, for whatever reason, you need to revert the update at this point, follow the procedure xref:proc-downgrading-brokers-older-kafka-{context}[]. 

. If the log message format versions, as identified in step 1, are the same proceed to the next step. 
Otherwise change the `log.message.format.version` in `Kafka.spec.kafka.config` to the default version for the new version of Kafka now being used.
For example, if upgrading to 2.1.0:
+
[source,yaml]
----
apiVersion: v1alpha1
kind: Kafka
spec:
  # ...
  kafka:
    version: 2.1.0
    config:
      log.message.format.version: "2.1"
      # ...
----
+
Wait for the Cluster Operator to update the cluster.

.Additional resources

* See xref:proc-downgrading-brokers-older-kafka-str[] for the procedure to downgrade a {ProductName} Kafka cluster from one version to a lower version, for example 2.0.1 to 2.0.0.
