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

[id='proc-downgrade-kafka-kraft-{context}']
= Downgrading Kafka clusters and client applications

[role="_abstract"]
You can downgrade a Kafka cluster to an earlier version only when the metadata format is compatible. 
Kafka permits downgrades only if there are no metadata changes between your current Kafka version and the target version. 
In practice, this means the cluster’s metadata version must be set to a value that the target Kafka version supports, and there must be no intervening metadata changes between the two versions.

IMPORTANT: If the cluster is already using the latest metadata version for the current release, you cannot downgrade. 
The downgrade is only possible if there is a metadata format that is valid in both the current and target Kafka versions.
Consult the Apache Kafka documentation for information on supported metadata version values and downgrade limitations.

.Prerequisites

* The Cluster Operator is up and running.
* Before you downgrade the Kafka cluster, check the following for the `Kafka` resource:

** The `Kafka` custom resource does not include options that are unsupported by the target Kafka version.
** The target Kafka version supports the metadata version (`spec.kafka.metadataVersion`) you plan to use. 

You can verify the current Kafka and metadata version by checking the status of the `Kafka` custom resource.

.Procedure

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

. Change the `metadataVersion` version to a value that is supported by both the current Kafka version and the target version.
The Kafka version must be able to operate with this metadata format.
+
Leave the `Kafka.spec.kafka.version` unchanged at the _current_ Kafka version.
+
For example, if downgrading from Kafka {KafkaVersionHigher} to {KafkaVersionLower}:
+
[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 changed to a version supported by the earlier Kafka version.
<2> Kafka version is unchanged.
+
NOTE: The value of `metadataVersion` must be a string to prevent it from being interpreted as a floating point number.

. Save the change, and wait for Cluster Operator to update `.status.kafkaMetadataVersion` for the `Kafka` resource. 

. Change the `Kafka.spec.kafka.version` to the previous version.
+
For example, if downgrading from Kafka {KafkaVersionHigher} to {KafkaVersionLower}:
+
[source,yaml,subs=attributes+]
----
apiVersion: {KafkaApiVersion}
kind: Kafka
metadata:
  name: my-cluster
spec:
  kafka:
    replicas: 3
    metadataVersion: {KafkaMetadataVersionLower} # <1>
    version: {KafkaVersionLower} # <2>
    # ...
----
+
<1> Metadata version is supported by the Kafka version.
<2> Kafka version is changed to the new version.

. If the image for the Kafka version is different from the image defined in `STRIMZI_KAFKA_IMAGES` for the Cluster Operator, update `Kafka.spec.kafka.image`.
+
See xref:con-versions-and-images-str[].

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

. Downgrade all client applications (consumers) to use the previous version of the client binaries.
+
The Kafka cluster and clients are now using the previous Kafka version.
