docs(v1): instructions for api conversion tool

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 `v1beta2` version.
+* A later release (planned for 0.52 or 1.0.0) removes the `v1beta2` API 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 / 1.0.0).  
+Resources converted to `v1` are compatible with Strimzi versions 0.49, 0.50, and 0.51.
+
+//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

@@ -16,9 +16,13 @@ For example, if you used the Strimzi installation files, modify those files to p
 After you have upgraded your Cluster Operator to {ProductVersion}, the next step is to upgrade all Kafka nodes to the latest supported version of Kafka. 
 Kafka upgrades are performed by the Cluster Operator through rolling updates of the Kafka nodes.
 
-If you encounter any issues with the new version, Strimzi can be xref:assembly-downgrade-{context}[downgraded] to the previous version.
+IMPORTANT: When upgrading to Strimzi version 0.49 or later, convert all custom resources and CRDs to the `v1` API.  
+The `v1beta2` API is deprecated and will be removed in a future release.  
+Conversion must be performed after upgrading the Cluster Operator, so that the Cluster Operator can interpret the resources.  
+Custom resources can be updated before or after the Kafka upgrade.  
+For more information, see xref:assembly-api-conversion-{context}[Converting Strimzi custom resources to the `v1` API].
 
-.Upgrade without downtime
+If you encounter any issues with the new version, Strimzi can be xref:assembly-downgrade-{context}[downgraded] to the previous version.
 
 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.
 

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-conversion-tool-commands.adoc

@@ -0,0 +1,47 @@
+:_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.
+
+Kubernetes `Job`::  
+Runs the conversion tool as a Kubernetes job inside the cluster.  
+Use this command when local access to the cluster is unavailable or restricted.
+
+`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.

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-sequence.adoc

@@ -22,6 +22,12 @@ ZooKeeper-based Apache Kafka clusters are not supported anymore and need to be m
 
 . xref:assembly-upgrade-{context}[Upgrade the Cluster Operator].
 
+. If upgrading to Strimzi 0.49 or later, convert all custom resources and CRDs to the `v1` API.  
++
+The `v1beta2` API is deprecated and will be removed in a future release.  
++
+For more information, see xref:assembly-api-conversion-{context}[Converting Strimzi custom resources to the `v1` API].
+
 . Update the xref:proc-upgrade-kafka-kraft-{context}[Kafka `version` and `metadataVersion`].
 
 NOTE: From Strimzi 0.39, upgrades and downgrades between KRaft-based clusters are supported.   

documentation/modules/upgrading/proc-convert-custom-resource-yaml.adoc

@@ -0,0 +1,41 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id='proc-convert-custom-resource-yaml-{context}']
+= Converting custom resource YAML files
+
+[role="_abstract"]
+Use the Strimzi API conversion tool with the `convert-file` command to convert Strimzi custom resources from YAML files to the `v1` API.
+
+Each input file can contain multiple resource definitions.
+The conversion operation converts all Strimzi custom resources while leaving other Kubernetes resources unchanged.
+
+.Procedure
+
+. Run `convert-file` with the `--file` option to specify the input file.
++
+Choose one of the following output options:
++
+* Use `--in-place` to overwrite the source file.
+* Use `--output <file>` to create a new file.
+* Omit both options to print the converted resource to standard output.
++
+Example commands:
++
+[source,shell]
+----
+# Convert the input file and print the output:
+bin/v1-api-conversion.sh convert-file --file <input.yaml>
+
+# Convert and overwrite the input file:
+bin/v1-api-conversion.sh convert-file --file <input.yaml> --in-place
+
+# Convert and write to a new file: 
+bin/v1-api-conversion.sh convert-file --file <input.yaml> --output <output.yaml>
+
+# Convert multiple input files and print the output: 
+bin/v1-api-conversion.sh convert-file --file <input1.yaml> --file <input2.yaml>
+----
+
+. Review the converted YAML to confirm that the `apiVersion` is set to `kafka.strimzi.io/v1`.  
+. Apply the converted files to the cluster using `kubectl apply -f` or `kubectl replace -f`.
+. Ensure that all conversions complete successfully before proceeding to upgrade the CRDs.

documentation/modules/upgrading/proc-convert-custom-resources-cluster.adoc

@@ -0,0 +1,51 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id='proc-convert-custom-resources-cluster-{context}']
+= Converting custom resources in a Kubernetes cluster
+
+[role="_abstract"]
+Use the Strimzi API conversion tool with the `convert-resource` command to convert existing Strimzi custom resources directly in a Kubernetes cluster to the `v1` API.
+
+.Procedure
+
+. Run `convert-resource` using one of the following options:
++
+* `--namespace <namespace>` to convert resources in a specific namespace  
+* `--all-namespaces` to convert resources in all namespaces  
+* Omit both options to convert resources in the current namespace  
+* `--kind <kind>` to convert only resources of a specific kind (for example, `Kafka`, `KafkaConnect`, or `KafkaBridge`)  
+* `--name <name>` with `--kind` to convert a single resource by name  
++
+Example commands:
++
+[source,shell]
+----
+# Convert all Strimzi resources in the current namespace:
+bin/v1-api-conversion.sh convert-resource
+
+# Convert all Strimzi resources in all namespaces:
+bin/v1-api-conversion.sh convert-resource --all-namespaces
+
+# Convert all Strimzi resources in the `my-kafka` namespace:
+bin/v1-api-conversion.sh convert-resource --namespace my-kafka
+
+# Convert only Kafka resources in all namespaces:
+bin/v1-api-conversion.sh convert-resource --all-namespaces --kind Kafka
+
+# Convert `Kafka` and `KafkaConnect` resources in all namespaces:
+bin/v1-api-conversion.sh convert-resource --all-namespaces --kind Kafka --kind KafkaConnect
+
+# Convert a Kafka cluster named `my-cluster` in namespace `my-kafka`: 
+bin/v1-api-conversion.sh convert-resource --kind Kafka --namespace my-kafka --name my-cluster
+----
+
+. Verify that the converted resources now use the `kafka.strimzi.io/v1` API version:
++  
+[source,shell]
+----
+kubectl get kafkas,kafkaconnects,kafkabridges,kafkamirrormaker2s,kafkarebalances,kafkatopics,kafkausers,kafkanodepools -A \
+  -o custom-columns="VERSION:.apiVersion,KIND:.kind,NAMESPACE:.metadata.namespace,NAME:.metadata.name" \
+  | grep "kafka.strimzi.io/v1"
+----
+
+. Ensure that all conversions complete successfully before proceeding to upgrade the CRDs.