docs(v1): instructions for api conversion tool (#12072)

Signed-off-by: prmellor <pmellor@redhat.com>

Author: PaulRMellor

documentation/assemblies/upgrading/assembly-api-conversion.adoc

@@ -0,0 +1,35 @@
+:_mod-docs-content-type: ASSEMBLY
+
+[id='assembly-api-conversion-{context}']
+= Converting Strimzi custom resources to the v1 API
+
+[role="_abstract"]
+This section describes how to prepare Strimzi custom resources and CRDs for the `v1` API before performing an upgrade.
+
+Prepare Strimzi custom resources and CRDs for the `v1` API by using the Strimzi API conversion tool or by applying the required changes manually.  
+The tool is provided with the release artifacts.  
+To use the tool, extract it and run the conversion script from the `bin` directory.
+
+The migration to the `v1` API has two stages.
+
+* Version 0.49 introduces the `v1` API and deprecates the older `v1alpha1`, `v1beta1`, and `v1beta2` versions. (`v1alpha1` and `v1beta1` versions are used only for `KafkaUser` and `KafkaTopic` resources).
+* A later release (planned for 0.52.0 or 1.0.0) removes the `v1alpha1`, `v1beta1`, and `v1beta2` APIs and updates all components to use `v1`.
+
+Complete the conversion of custom resources and CRDs after upgrading to version 0.49 or later, and before upgrading to the later release that removes the `v1beta2` API (Strimzi 0.52.0 / 1.0.0).  
+Resources converted to `v1` are compatible with Strimzi versions 0.49 and later.
+
+//tool commands
+include::../../modules/upgrading/con-conversion-tool-commands.adoc[leveloffset=+1]
+//prep for conversion
+include::../../modules/upgrading/ref-preparing-for-conversion.adoc[leveloffset=+1]
+//converting resources locally
+include::../../modules/upgrading/proc-convert-custom-resource-yaml.adoc[leveloffset=+1]
+//converting resources in a cluster
+include::../../modules/upgrading/proc-convert-custom-resources-cluster.adoc[leveloffset=+1]
+//converting resources as a job
+include::../../modules/upgrading/proc-run-conversion-tool-job.adoc[leveloffset=+1]
+//upgrading CRDs
+include::../../modules/upgrading/proc-upgrade-crds.adoc[leveloffset=+1]
+//resource updates
+include::../../assemblies/upgrading/assembly-update-resources.adoc[leveloffset=+1]
+

documentation/assemblies/upgrading/assembly-update-resources.adoc

@@ -0,0 +1,24 @@
+:_mod-docs-content-type: ASSEMBLY
+
+[id='assembly-update-resources-v1-{context}']
+= Updating custom resources for the v1 API
+
+[role="_abstract"]
+Use this section to review the configuration changes introduced in the Strimzi `v1` API and determine which updates are required for your deployment.
+
+The reference information describes updates for each Strimzi custom resource type.  
+Some updates are applied automatically by the API conversion tool, while others require manual editing of custom resources.
+
+The following sections describe the manual and automatic updates required for each Strimzi custom resource type.
+
+include::../../modules/upgrading/con-understanding-v1-api-changes.adoc[leveloffset=+1]
+include::../../modules/upgrading/ref-kafka-v1-changes.adoc[leveloffset=+1]
+include::../../modules/upgrading/ref-kafkaconnect-v1-changes.adoc[leveloffset=+1]
+include::../../modules/upgrading/ref-kafkamirrormaker2-v1-changes.adoc[leveloffset=+1]
+include::../../modules/upgrading/ref-kafkabridge-v1-changes.adoc[leveloffset=+1]
+include::../../modules/upgrading/ref-kafkaconnector-v1-changes.adoc[leveloffset=+1]
+include::../../modules/upgrading/ref-kafkarebalance-v1-changes.adoc[leveloffset=+1]
+include::../../modules/upgrading/ref-kafkanodepool-v1-changes.adoc[leveloffset=+1]
+include::../../modules/upgrading/ref-kafkatopic-v1-changes.adoc[leveloffset=+1]
+include::../../modules/upgrading/ref-kafkauser-v1-changes.adoc[leveloffset=+1]
+include::../../modules/upgrading/ref-strimzipodset-v1-changes.adoc[leveloffset=+1]

documentation/assemblies/upgrading/assembly-upgrade.adoc

@@ -18,8 +18,6 @@ Kafka upgrades are performed by the Cluster Operator through rolling updates of
 
 If you encounter any issues with the new version, Strimzi can be xref:assembly-downgrade-{context}[downgraded] to the previous version.
 
-.Upgrade without downtime
-
 For topics configured with high availability (replication factor of at least 3 and evenly distributed partitions), the upgrade process should not cause any downtime for consumers and producers.
 
 The upgrade triggers rolling updates, where brokers are restarted one by one at different stages of the process. 
@@ -28,16 +26,15 @@ During this time, overall cluster availability is temporarily reduced, which may
 //sequence
 include::../../modules/upgrading/con-upgrade-sequence.adoc[leveloffset=+1]
 
-//kafka upgrade concepts
-include::../../modules/upgrading/con-upgrade-paths.adoc[leveloffset=+1]
-include::../../modules/upgrading/con-upgrade-versions-and-images.adoc[leveloffset=+2]
-
-//client upgrade concepts
-include::../../modules/upgrading/con-upgrade-strategies-for-upgrading-clients.adoc[leveloffset=+1]
-
 //upgrading kubernetes
 include::../../modules/upgrading/con-upgrade-cluster.adoc[leveloffset=+1]
 
+//upgrade considerations for pre-0.39 upgrades (non-KRaft)
+include::../../modules/upgrading/con-migrate-kraft-pre-0.39.adoc[leveloffset=+1]
+
+//upgrade considerations for v1 conversion
+include::../../modules/upgrading/con-api-conversion-v1.adoc[leveloffset=+1]
+
 //upgrading cluster operator
 include::assembly-upgrade-cluster-operator.adoc[leveloffset=+1]
 
@@ -46,3 +43,10 @@ include::../../modules/upgrading/proc-upgrade-kafka-kraft.adoc[leveloffset=+1]
 
 //checking the status of an upgrade
 include::../../modules/upgrading/con-upgrade-status.adoc[leveloffset=+1]
+
+//kafka upgrade concepts
+include::../../modules/upgrading/con-upgrade-paths.adoc[leveloffset=+1]
+include::../../modules/upgrading/con-upgrade-versions-and-images.adoc[leveloffset=+2]
+
+//client upgrade concepts
+include::../../modules/upgrading/con-upgrade-strategies-for-upgrading-clients.adoc[leveloffset=+1]

documentation/deploying/deploying.adoc

@@ -66,6 +66,8 @@ include::assemblies/deploying/assembly-drain-cleaner.adoc[leveloffset=+1]
 include::assemblies/deploying/assembly-rolling-updates.adoc[leveloffset=+1]
 //How to monitor restart events
 include::assemblies/deploying/assembly-deploy-restart-events.adoc[leveloffset=+1]
+//Using the API conversion tool
+include::assemblies/upgrading/assembly-api-conversion.adoc[leveloffset=+1]
 //Upgrading the deployment
 include::assemblies/upgrading/assembly-upgrade.adoc[leveloffset=+1]
 //Downgrading the deployment

documentation/modules/upgrading/con-api-conversion-v1.adoc

@@ -0,0 +1,27 @@
+:_mod-docs-content-type: CONCEPT
+
+// This module is included in the following assemblies:
+//
+// assembly-upgrade.adoc
+
+[id='con-api-conversion-v1-{context}']
+= Converting to v1 API from versions earlier than 0.49
+
+[role="_abstract"]
+When upgrading from a version prior to Strimzi 0.49.0, you **must** convert your custom resources and CRDs to the `v1` API. 
+The `v1beta2` API is deprecated and will be removed in a future release (planned for 0.52.0 or 1.0.0).
+
+IMPORTANT: This conversion applies to KRaft-based clusters. 
+If you are upgrading from a version earlier than 0.39, you must first xref:con-migrate-kraft-pre-0.39-{context}[migrate to KRaft] before proceeding with this conversion and the upgrade.
+
+Follow this specific sequence for the `v1` API conversion:
+
+. **Before upgrading the Cluster Operator to 0.49.0 or later:**
+* If you have `KafkaUser` resources using the `.spec.authorization.acls[].operation` field (singular), you **must** update them to use `.spec.authorization.acls[].operations` (plural).
+
+. **After upgrading the Cluster Operator to 0.49.0 or later:**
+* You can now convert all other custom resources and CRDs to the `v1` API.
+* This step **must** be done *after* the Cluster Operator is upgraded, as the new operator version is required to interpret the `v1` format.
+* This conversion can be done any time after the 0.49.0 upgrade but **must** be completed before the future release that removes the `v1beta2` API.
+
+For complete conversion instructions, see xref:assembly-api-conversion-{context}[Converting Strimzi custom resources to the `v1` API].

documentation/modules/upgrading/con-conversion-tool-commands.adoc

@@ -0,0 +1,46 @@
+:_mod-docs-content-type: CONCEPT
+
+[id='con-conversion-tool-commands-{context}']
+= Conversion tool commands
+
+[role="_abstract"]
+The Strimzi API conversion tool provides commands to convert Strimzi custom resources and upgrade Custom Resource Definitions (CRDs) to the `v1` API.
+
+Each command runs through a shell script located in the `bin` directory.
+
+Run the tool using the following command format:
+
+[source,shell]
+----
+bin/v1-api-conversion.sh <command>
+----
+
+If you are using Windows, run `bin/v1-api-conversion.cmd` instead.
+
+The following commands are available for converting custom resources and upgrading CRDs:
+
+`convert-file`::  
+Converts Strimzi custom resources from local YAML files.  
+Use this command when applying configuration through GitOps or when direct cluster access is restricted.
+
+`convert-resource`::  
+Converts existing Strimzi custom resources directly in Kubernetes.  
+Use this command when updating live environments managed by the Cluster Operator.
+
+`crd-upgrade`::  
+Upgrades Strimzi CRDs to use the `v1` API as the storage version.  
+Run this command only after all custom resources have been converted.
+
+`help`::
+Use the `help` command to list available commands and options or to display detailed help for a specific command.
++
+[source,shell]
+----
+bin/v1-api-conversion.sh help
+bin/v1-api-conversion.sh help <command>
+----
++
+For example, run `bin/v1-api-conversion.sh help convert-file` to see the supported options for converting YAML files.
+
+NOTE: As an alternative to running the tool locally from your computer, you can also run it as a Kubernetes `Job`.
+For more information, see the `README.md` file in the conversion tool.

documentation/modules/upgrading/con-migrate-kraft-pre-0.39.adoc

@@ -0,0 +1,19 @@
+:_mod-docs-content-type: CONCEPT
+
+// This module is included in the following assemblies:
+//
+// assembly-upgrade.adoc
+
+[id='con-migrate-kraft-pre-0.39-{context}']
+= Migrating to KRaft from versions earlier than 0.39
+
+Direct upgrades to Strimzi {ProductVersion} from versions earlier than 0.39 are **not supported**.
+
+Before you can upgrade to {ProductVersion}, you **must** follow this required path:
+
+. Upgrade your cluster to a Strimzi version between 0.39 and 0.45.
+. Migrate your cluster from ZooKeeper to KRaft.
+
+For more information, see xref:assembly-kraft-mode-{context}[Using Kafka in KRaft mode].
+
+After your cluster is running on KRaft, you can proceed with the upgrade to Strimzi {ProductVersion}.

documentation/modules/upgrading/con-understanding-v1-api-changes.adoc

@@ -0,0 +1,30 @@
+:_mod-docs-content-type: CONCEPT
+
+= Manual and automatic v1 API changes
+
+[role="_abstract"]
+The Strimzi `v1` API introduces structural and configuration changes to custom resources.
+Some properties and sections from earlier API versions have been removed or replaced. 
+
+Custom resources can be updated for the `v1` API in two ways:
+
+* By using the Strimzi API conversion tool to apply supported automatic changes.
+* By editing and reapplying resources manually without using the tool.
+
+Even when the conversion tool is used, some changes must still be applied manually because the tool cannot modify or remove the unsupported configuration.  
+The reference information in this section lists which changes the tool can perform automatically and which require manual updates.
+
+.Manual changes
+
+Manual changes are updates that the conversion tool does not apply automatically.  
+
+To apply a manual change:
+
+. Edit the affected custom resource.
+. Update or remove the required properties.
+. Reapply the resource using `kubectl apply -f` or `kubectl replace -f`.
+
+.Automatic changes
+
+Automatic changes are updates that the conversion tool applies during conversion.  
+Even when the conversion tool is used, some manual changes are still required for the custom resources.

documentation/modules/upgrading/con-upgrade-paths.adoc

@@ -34,8 +34,3 @@ Review supported Kafka versions in the link:https://strimzi.io/downloads/[Suppor
 * 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[]
-
-== Upgrading from a Strimzi version earlier than 0.39
-
-Strimzi {ProductVersion} supports upgrades only for KRaft-based Apache Kafka clusters managed by Strimzi 0.39 and newer.
-When upgrading from older Strimzi versions, please make sure to first upgrade to a Strimzi version from 0.39 to 0.45 and migrate to KRaft before upgrading to Strimzi {ProductVersion}.

documentation/modules/upgrading/con-upgrade-sequence.adoc

@@ -16,9 +16,13 @@ Strimzi {ProductVersion} requires Kubernetes {KubernetesVersion}.
 +
 You can xref:con-upgrade-cluster-{context}[upgrade Kubernetes with minimal downtime].
 
-. Make sure you use Strimzi 0.39 or newer and all your Apache Kafka clusters are Kraft-based.
+. xref:con-migrate-kraft-pre-0.39-{context}[Ensure Kafka clusters are KRaft-based].
 +
-ZooKeeper-based Apache Kafka clusters are not supported anymore and need to be migrated to KRaft before upgrading the Cluster Operator or Apache Kafka.
+If upgrading from a version earlier than 0.39, you **must** migrate from ZooKeeper to KRaft *before* upgrading the Cluster Operator. Upgrades from ZooKeeper-based clusters are not supported.
+
+. xref:con-api-conversion-v1-{context}[Prepare for v1 API conversion].
++
+If upgrading from a version prior to 0.49, this requirement includes a `KafkaUser` update that **must** be done *before* upgrading the Cluster Operator. 
 
 . xref:assembly-upgrade-{context}[Upgrade the Cluster Operator].