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

[id='con-upgrade-paths-{context}']
= Strimzi upgrade paths

[role="_abstract"]
Two upgrade paths are available for Strimzi.

Incremental upgrade::
An incremental upgrade involves upgrading Strimzi from the previous minor version to version {ProductVersion}.

Multi-version upgrade::
A multi-version upgrade involves upgrading an older version of Strimzi to version {ProductVersion} within a single upgrade, skipping one or more intermediate versions. 
Upgrading from any earlier Strimzi version to the latest version is possible. 

[id='con-upgrade-paths-kafka-versions-{context}']
== Support for Kafka versions when upgrading

When upgrading Strimzi, it is important to ensure compatibility with the Kafka version being used.

Multi-version upgrades are possible even if the supported Kafka versions differ between the old and new versions. 
However, if you attempt to upgrade to a new Strimzi version that does not support the current Kafka version, xref:con-upgrade-cluster-operator-unsupported-kafka-str[an error indicating that the Kafka version is not supported is generated]. 
In this case, you must upgrade the Kafka version as part of the Strimzi upgrade by changing the `spec.kafka.version` in the `Kafka` custom resource to the supported version for the new Strimzi version.

ifdef::Section[]
[NOTE]
====
You can review supported Kafka versions in the link:https://strimzi.io/downloads/[Supported versions^] table.

* The *Operators* column lists all released Strimzi versions (the Strimzi version is often called the "Operator version").
* The *Kafka versions* column lists the supported Kafka versions for each Strimzi version.
====
endif::Section[]

[id='con-upgrade-paths-earlier-versions-{context}']
== Upgrading from a Strimzi version earlier than 0.22

If you are upgrading to the latest version of Strimzi from a version prior to version 0.22, do the following:

. Upgrade Strimzi to version 0.22 following the xref:con-upgrade-sequence-{context}[standard sequence].
. Convert Strimzi custom resources to `v1beta2` using the _API conversion tool_ provided with Strimzi.
. Do one of the following:
+
* Upgrade Strimzi to a version between 0.23 and 0.26 (where the `ControlPlaneListener` feature gate is disabled by default).
* Upgrade Strimzi to a version between 0.27 and 0.31 (where the `ControlPlaneListener` feature gate is enabled by default) with the `ControlPlaneListener` feature gate disabled.
. Enable the `ControlPlaneListener` feature gate.
. Upgrade to Strimzi {ProductVersion} following the xref:con-upgrade-sequence-{context}[standard sequence].

Strimzi custom resources started using the `v1beta2` API version in release 0.22.
CRDs and custom resources must be converted *before* upgrading to Strimzi 0.23 or newer.
For information on using the API conversion tool, see the {UpgradeGuide}.

NOTE: As an alternative to first upgrading to version 0.22, you can install the custom resources from version 0.22 and then convert the resources.

The `ControlPlaneListener` feature is now permanently enabled in Strimzi.
You must upgrade to a version of Strimzi where it is disabled, then enable it using the 
`STRIMZI_FEATURE_GATES` environment variable in the Cluster Operator configuration.

.Disabling the `ControlPlaneListener` feature gate
[source,yaml,options="nowrap"]
----
env:
  - name: STRIMZI_FEATURE_GATES
    value: -ControlPlaneListener
----

.Enabling the `ControlPlaneListener` feature gate
[source,yaml,options="nowrap"]
----
env:
  - name: STRIMZI_FEATURE_GATES
    value: +ControlPlaneListener
----