diff --git a/documentation/assemblies/upgrading/assembly-api-conversion.adoc b/documentation/assemblies/upgrading/assembly-api-conversion.adoc new file mode 100644 index 00000000000..d1cf2b097cd --- /dev/null +++ b/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] + diff --git a/documentation/assemblies/upgrading/assembly-update-resources.adoc b/documentation/assemblies/upgrading/assembly-update-resources.adoc new file mode 100644 index 00000000000..3aea6ecb5cb --- /dev/null +++ b/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] \ No newline at end of file diff --git a/documentation/assemblies/upgrading/assembly-upgrade.adoc b/documentation/assemblies/upgrading/assembly-upgrade.adoc index ca53fcb5e8f..956b155063b 100644 --- a/documentation/assemblies/upgrading/assembly-upgrade.adoc +++ b/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. diff --git a/documentation/deploying/deploying.adoc b/documentation/deploying/deploying.adoc index ab673c2b4ed..20d8421844a 100644 --- a/documentation/deploying/deploying.adoc +++ b/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 diff --git a/documentation/modules/upgrading/con-conversion-tool-commands.adoc b/documentation/modules/upgrading/con-conversion-tool-commands.adoc new file mode 100644 index 00000000000..53f98bc1f6a --- /dev/null +++ b/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 +---- + +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 +---- ++ +For example, run `bin/v1-api-conversion.sh help convert-file` to see the supported options for converting YAML files. \ No newline at end of file diff --git a/documentation/modules/upgrading/con-understanding-v1-api-changes.adoc b/documentation/modules/upgrading/con-understanding-v1-api-changes.adoc new file mode 100644 index 00000000000..82150709bc7 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/documentation/modules/upgrading/con-upgrade-sequence.adoc b/documentation/modules/upgrading/con-upgrade-sequence.adoc index d3f37c22c96..2df5c9fdfe0 100644 --- a/documentation/modules/upgrading/con-upgrade-sequence.adoc +++ b/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. \ No newline at end of file diff --git a/documentation/modules/upgrading/proc-convert-custom-resource-yaml.adoc b/documentation/modules/upgrading/proc-convert-custom-resource-yaml.adoc new file mode 100644 index 00000000000..53219bba523 --- /dev/null +++ b/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 ` 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 + +# Convert and overwrite the input file: +bin/v1-api-conversion.sh convert-file --file --in-place + +# Convert and write to a new file: +bin/v1-api-conversion.sh convert-file --file --output + +# Convert multiple input files and print the output: +bin/v1-api-conversion.sh convert-file --file --file +---- + +. 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. \ No newline at end of file diff --git a/documentation/modules/upgrading/proc-convert-custom-resources-cluster.adoc b/documentation/modules/upgrading/proc-convert-custom-resources-cluster.adoc new file mode 100644 index 00000000000..95dbc6973eb --- /dev/null +++ b/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 ` 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 ` to convert only resources of a specific kind (for example, `Kafka`, `KafkaConnect`, or `KafkaBridge`) +* `--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. \ No newline at end of file diff --git a/documentation/modules/upgrading/proc-run-conversion-tool-job.adoc b/documentation/modules/upgrading/proc-run-conversion-tool-job.adoc new file mode 100644 index 00000000000..bf321c88142 --- /dev/null +++ b/documentation/modules/upgrading/proc-run-conversion-tool-job.adoc @@ -0,0 +1,156 @@ +:_mod-docs-content-type: PROCEDURE + +[id='proc-run-conversion-tool-job-{context}'] += Running the conversion tool as a Kubernetes job + +[role="_abstract"] +[role="_abstract"] +Use the Strimzi API conversion tool with the `convert-resource` command to convert custom resources by running the tool as a Kubernetes `Job` when `kubectl` you cannot access the cluster locally or do not have a direct connection. + +.Procedure + +. Create a manifest that defines the resources required to run the conversion tool in the cluster. +Include the following: ++ +* A `ServiceAccount` that runs the job +* RBAC permissions (`ClusterRole` and `ClusterRoleBinding`) that allow access to Strimzi custom resources and CRDs +* A `Job` resource that runs the conversion tool using those permissions ++ +If you are running the job in a specific namespace, ensure that the namespace name is the same in the `ServiceAccount`, `ClusterRoleBinding`, and `Job` definitions. +The following example combines all required resources into one YAML file: ++ +[source,yaml,subs="+attributes"] +---- +apiVersion: v1 +kind: ServiceAccount +metadata: + name: strimzi-v1-api-conversion + namespace: +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRole +metadata: + name: strimzi-v1-api-conversion +rules: + - apiGroups: + - kafka.strimzi.io + resources: + - kafkas + - kafkanodepools + - kafkaconnects + - kafkaconnectors + - kafkabridges + - kafkamirrormaker2s + - kafkarebalances + - kafkatopics + - kafkausers + verbs: + - get + - list + - patch + - update + - apiGroups: + - core.strimzi.io + resources: + - strimzipodsets + verbs: + - get + - list + - patch + - update + - apiGroups: + - apiextensions.k8s.io + resources: + - customresourcedefinitions + - customresourcedefinitions/status + resourceNames: + - kafkabridges.kafka.strimzi.io + - kafkaconnectors.kafka.strimzi.io + - kafkaconnects.kafka.strimzi.io + - kafkamirrormaker2s.kafka.strimzi.io + - kafkanodepools.kafka.strimzi.io + - kafkarebalances.kafka.strimzi.io + - kafkas.kafka.strimzi.io + - kafkatopics.kafka.strimzi.io + - kafkausers.kafka.strimzi.io + - strimzipodsets.core.strimzi.io + verbs: + - get + - list + - patch + - update + - apiGroups: + - "" + resources: + # Required when converting KafkaBridge metrics configuration + - configmaps + verbs: + - get + - list + - create + - patch + - update +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRoleBinding +metadata: + name: strimzi-v1-api-conversion +subjects: + - kind: ServiceAccount + name: strimzi-v1-api-conversion + namespace: +roleRef: + kind: ClusterRole + name: strimzi-v1-api-conversion + apiGroup: rbac.authorization.k8s.io +--- +apiVersion: batch/v1 +kind: Job +metadata: + name: strimzi-v1-api-conversion + # Namespace where the job runs + namespace: +spec: + template: + spec: + serviceAccountName: strimzi-v1-api-conversion + containers: + - name: strimzi-v1-api-conversion + # Use an image that includes the conversion tool + image: {DockerClusterOperator} + command: + - /opt/v1-api-conversion/bin/v1-api-conversion.sh + - convert-resource + restartPolicy: OnFailure +---- + +. Apply the manifest to the cluster: ++ +[source,shell] +---- +kubectl apply -f strimzi-v1-api-conversion-job.yaml +---- + +. Check the job is complete: ++ +[source,shell] +---- +kubectl get jobs -n +kubectl logs job/strimzi-v1-api-conversion -n +---- + +. Verify that the converted resources now use the `kafka.strimzi.io/v1` API version. ++ +If direct CLI access is unavailable, check the logs or monitoring dashboard to confirm that the job completed successfully. + +. Ensure that all conversions complete successfully before proceeding to upgrade the CRDs. + +. (Optional) Switch the job to upgrade CRDs after all conversions complete. +Edit the container command to run `crd-upgrade` instead of `convert-resource`: ++ +[source,yaml] +---- +command: + - /opt/v1-api-conversion/bin/v1-api-conversion.sh + - crd-upgrade +---- \ No newline at end of file diff --git a/documentation/modules/upgrading/proc-upgrade-crds.adoc b/documentation/modules/upgrading/proc-upgrade-crds.adoc new file mode 100644 index 00000000000..7ce7d92159c --- /dev/null +++ b/documentation/modules/upgrading/proc-upgrade-crds.adoc @@ -0,0 +1,37 @@ +:_mod-docs-content-type: PROCEDURE + +[id='proc-upgrade-crds-to-v1-{context}'] += Upgrading CRDs to the v1 API + +[role="_abstract"] +Use the Strimzi API conversion tool with the `crd-upgrade` command to upgrade the Strimzi Custom Resource Definitions (CRDs) to use the `v1` API as the storage version. + +If you run this operation from a Kubernetes `Job`, replace `convert-resource` with `crd-upgrade` in the container command. + +.Prerequisites + +* All Strimzi custom resources have been converted to `v1`. +* Permissions to patch CRD resources and replace their status. + +.Procedure + +. Run `crd-upgrade`: ++ +[source,shell] +---- +bin/v1-api-conversion.sh crd-upgrade +---- + +. Verify that all Strimzi CRDs use the `v1` API as the storage version: ++ +[source,shell] +---- +kubectl get crd -o name | grep kafka.strimzi.io | while read crd; do + echo -n "$crd " + kubectl get "$crd" -o jsonpath='{.status.storedVersions}{"\n"}' +done +---- ++ +Confirm that all CRDs return `[v1]` as the stored version. + +. After upgrading the CRDs, use only the properties supported in the `v1` API in all custom resources. \ No newline at end of file diff --git a/documentation/modules/upgrading/ref-kafka-v1-changes.adoc b/documentation/modules/upgrading/ref-kafka-v1-changes.adoc new file mode 100644 index 00000000000..460f13a238b --- /dev/null +++ b/documentation/modules/upgrading/ref-kafka-v1-changes.adoc @@ -0,0 +1,50 @@ +:_mod-docs-content-type: REFERENCE + +[id='ref-kafka-v1-changes-{context}'] += Kafka + +[role="_abstract"] +Changes required for the `Kafka` custom resource in the `v1` API. + +**Manual changes required** + +The conversion tool does not apply the following updates. +You must make these changes manually to ensure compatibility: + +* Ensure the `.spec` section is present (required). +* Replace unsupported authentication `type: oauth` with `type: custom`. +* In `type: custom` authentication, remove the `secrets` property. Mount secrets using the `template` section instead. +* Replace unsupported authorization types `keycloak` and `opa` with `type: custom`. +* Remove the `.spec.kafka.resources` property. Define resource requests and limits in `KafkaNodePool` resources. + +**Automatic changes supported** + +The following updates are applied automatically by the conversion tool during conversion. +If the conversion tool is not used, the same changes can be made manually. + +* Removes the `.spec.zookeeper` section. ZooKeeper-based clusters are not supported. +* Removes the `.spec.jmxTrans` section. JMXTrans is not supported. +* Removes the following Kafka properties: +** `.spec.kafka.replicas` (replicas are configured through `KafkaNodePool` resources) +** `.spec.kafka.storage` (storage is configured through `KafkaNodePool` resources) +** `.spec.kafka.template.statefulset` +* Removes the following Cruise Control properties: +** `.spec.cruiseControl.tlsSidecar` +** `.spec.cruiseControl.template.tlsSidecarContainer` +** `.spec.cruiseControl.brokerCapacity.disk` +** `.spec.cruiseControl.brokerCapacity.cpuUtilization` +* Removes the `.spec.kafkaExporter.template.service` property. +* Removes the following Entity Operator properties: +** `.spec.entityOperator.tlsSidecar` +** `.spec.entityOperator.template.tlsSidecarContainer` +** `.spec.entityOperator.topicOperator.topicMetadataMaxAttempts` +** `.spec.entityOperator.topicOperator.zookeeperSessionTimeoutSeconds` +** `.spec.entityOperator.userOperator.zookeeperSessionTimeoutSeconds` +* Replaces `.spec.entityOperator.topicOperator.reconciliationIntervalSeconds` with `.spec.entityOperator.topicOperator.reconciliationIntervalMs` (value multiplied by 1000). +* Replaces `.spec.entityOperator.userOperator.reconciliationIntervalSeconds` with `.spec.entityOperator.userOperator.reconciliationIntervalMs` (value multiplied by 1000). +* Removes the following properties from YAML definitions that include the status section: +** `.status.registeredNodeIds` +** `.status.kafkaMetadataState` +** `.status.listeners[].type` + +The status removal is not required for any resources that are managed by Strimzi Cluster Operator in a Kubernetes cluster. diff --git a/documentation/modules/upgrading/ref-kafkabridge-v1-changes.adoc b/documentation/modules/upgrading/ref-kafkabridge-v1-changes.adoc new file mode 100644 index 00000000000..cad35d6a215 --- /dev/null +++ b/documentation/modules/upgrading/ref-kafkabridge-v1-changes.adoc @@ -0,0 +1,26 @@ +:_mod-docs-content-type: REFERENCE + +[id='ref-kafkabridge-v1-changes-{context}'] += KafkaBridge + +[role="_abstract"] +Changes required for the `KafkaBridge` custom resource in the `v1` API. + +== Manual changes required + +The conversion tool does not apply the following updates. +You must make these changes manually to ensure compatibility: + +* Ensure the `.spec` section is present (required). +* Replace unsupported authentication `type: oauth` with `type: custom`. + +== Automatic changes supported + +The following updates are applied automatically by the conversion tool during conversion. +If the conversion tool is not used, you can apply the same changes manually: + +* Adds the `.spec.replicas` property if missing, defaulting to `1`. +* Removes unsupported tracing `type: jaeger`. +* Removes the `.spec.enableMetrics` property. +If `.spec.enableMetrics` was set to `true`, a new `ConfigMap` is created automatically with the metrics configuration. +Adds the `.spec.metricsConfig` property to reference this `ConfigMap`. diff --git a/documentation/modules/upgrading/ref-kafkaconnect-v1-changes.adoc b/documentation/modules/upgrading/ref-kafkaconnect-v1-changes.adoc new file mode 100644 index 00000000000..7e359a097d9 --- /dev/null +++ b/documentation/modules/upgrading/ref-kafkaconnect-v1-changes.adoc @@ -0,0 +1,34 @@ +:_mod-docs-content-type: REFERENCE + +[id='ref-kafkaconnect-v1-changes-{context}'] += KafkaConnect + +[role="_abstract"] +Changes required for the `KafkaConnect` custom resource in the `v1` API. + +== Manual changes required + +The conversion tool does not apply the following updates. +You must make these changes manually to ensure compatibility: + +* Ensure the `.spec` section is present (required). +* Replace unsupported authentication `type: oauth` with `type: custom`. +* Remove the `.spec.externalConfiguration` property. Use the `.spec.template` section to add custom volumes or environment variables. + +== Automatic changes supported + +The following updates are applied automatically by the conversion tool during conversion. +If the conversion tool is not used, you can apply the same changes manually: + +* Adds the `.spec.replicas` property if missing, defaulting to `3`. +* Renames `.spec.build.output.additionalKanikoOptions` to `.spec.build.output.additionalBuildOptions`. +* Removes the `.spec.template.deployment` property. +* Removes unsupported tracing `type: jaeger`. +* Adds the following required properties and sets them from existing configuration or default values: +** `.spec.groupId`: set from `.spec.config.group.id`, or default to `connect-cluster`. +** `.spec.configStorageTopic`: set from `.spec.config.config.storage.topic`, or default to `connect-cluster-configs`. +** `.spec.offsetStorageTopic`: set from `.spec.config.offset.storage.topic`, or default to `connect-cluster-offsets`. +** `.spec.statusStorageTopic`: set from `.spec.config.status.storage.topic`, or default to `connect-cluster-status`. + +NOTE: After setting the group ID and internal topic properties, remove the corresponding values from `.spec.config`. + diff --git a/documentation/modules/upgrading/ref-kafkaconnector-v1-changes.adoc b/documentation/modules/upgrading/ref-kafkaconnector-v1-changes.adoc new file mode 100644 index 00000000000..343d8ca2b75 --- /dev/null +++ b/documentation/modules/upgrading/ref-kafkaconnector-v1-changes.adoc @@ -0,0 +1,22 @@ +:_mod-docs-content-type: REFERENCE + +[id='ref-kafkaconnector-v1-changes-{context}'] += KafkaConnector + +[role="_abstract"] +Changes required for the `KafkaConnector` custom resource in the `v1` API. + +== Manual changes required + +The conversion tool does not apply the following updates. +You must make these changes manually to ensure compatibility: + +* Ensure the `.spec` section is present (required). + +== Automatic changes supported + +The following updates are applied automatically by the conversion tool during conversion. +If the conversion tool is not used, you can apply the same changes manually: + +* Removes the `.spec.pause` property. +If `pause: true` was set, it is converted to `state: paused`. \ No newline at end of file diff --git a/documentation/modules/upgrading/ref-kafkamirrormaker2-v1-changes.adoc b/documentation/modules/upgrading/ref-kafkamirrormaker2-v1-changes.adoc new file mode 100644 index 00000000000..9de0d7341cb --- /dev/null +++ b/documentation/modules/upgrading/ref-kafkamirrormaker2-v1-changes.adoc @@ -0,0 +1,42 @@ +:_mod-docs-content-type: REFERENCE + +[id='ref-kafkamirrormaker2-v1-changes-{context}'] += KafkaMirrorMaker2 + +[role="_abstract"] +Changes required for the `KafkaMirrorMaker2` custom resource in the `v1` API. + +== Manual changes required + +The conversion tool does not apply the following updates. +You must make these changes manually to ensure compatibility: + +* Ensure the `.spec` section is present (required). +* Replace unsupported authentication `type: oauth` for source or target Kafka clusters with `type: custom`. +* Remove the `.spec.externalConfiguration` property. Use the `.spec.template` section to add custom volumes or environment variables. + +== Automatic changes supported + +The following updates are applied automatically by the conversion tool during conversion. +If the conversion tool is not used, you can apply the same changes manually: + +* Adds the `.spec.replicas` property if missing. +* Removes the `.spec.template.deployment` property. +* Removes unsupported tracing `type: jaeger`. +* Removes the heartbeat connector property: `.spec.mirrors[].heartbeatConnector`. +* Updates connector pause handling: removes `.spec.mirrors[].connectors[].pause`. +If `pause: true` was set, it is converted to `state: paused`. +* Renames exclude pattern properties: +** `.spec.mirrors[].topicBlacklistPattern` to `.spec.mirrors[].topicsExcludePattern` +** `.spec.mirrors[].groupBlacklistPattern` to `.spec.mirrors[].groupsExcludePattern` +* Replaces cluster properties: +** Removes `.spec.connectCluster`, `.spec.clusters`, `.spec.mirrors[].sourceCluster`, and `.spec.mirrors[].targetCluster`. +** Configures the target and sources using `.spec.target` and `.spec.mirrors[].source`. +* Adds the following required properties and sets them from existing configuration or default values: +** `.spec.groupId`: set from `.spec.config.group.id`, or default to `connect-cluster`. +** `.spec.configStorageTopic`: set from `.spec.config.config.storage.topic`, or default to `connect-cluster-configs`. +** `.spec.offsetStorageTopic`: set from `.spec.config.offset.storage.topic`, or default to `connect-cluster-offsets`. +** `.spec.statusStorageTopic`: set from `.spec.config.status.storage.topic`, or default to `connect-cluster-status`. + + +NOTE: After setting the target-side properties, remove the corresponding entries from the target `config`. \ No newline at end of file diff --git a/documentation/modules/upgrading/ref-kafkanodepool-v1-changes.adoc b/documentation/modules/upgrading/ref-kafkanodepool-v1-changes.adoc new file mode 100644 index 00000000000..fb5a02b6936 --- /dev/null +++ b/documentation/modules/upgrading/ref-kafkanodepool-v1-changes.adoc @@ -0,0 +1,22 @@ +:_mod-docs-content-type: REFERENCE + +[id='ref-kafkanodepool-v1-changes-{context}'] += KafkaNodePool +[role="_abstract"] +Changes required for the `KafkaNodePool` custom resource in the `v1` API. + +== Manual changes required + +The conversion tool does not apply the following updates. +You must make these changes manually to ensure compatibility: + +* Ensure the `.spec` section is present (required). + +== Automatic changes supported + +The following updates are applied automatically by the conversion tool during conversion. +If the conversion tool is not used, you can apply the same changes manually: + +* Removes the `overrides` property from `.spec.storage`. + +To configure different storage settings for specific nodes, define separate `KafkaNodePool` resources. diff --git a/documentation/modules/upgrading/ref-kafkarebalance-v1-changes.adoc b/documentation/modules/upgrading/ref-kafkarebalance-v1-changes.adoc new file mode 100644 index 00000000000..784ae09c17f --- /dev/null +++ b/documentation/modules/upgrading/ref-kafkarebalance-v1-changes.adoc @@ -0,0 +1,14 @@ +:_mod-docs-content-type: REFERENCE + +[id='ref-kafkarebalance-v1-changes-{context}'] += KafkaRebalance + +[role="_abstract"] +Changes required for the `KafkaRebalance` custom resource in the `v1` API. + +== Manual changes required + +The conversion tool does not apply the following updates. +You must make these changes manually to ensure compatibility: + +* Ensure the `.spec` section is present (required). diff --git a/documentation/modules/upgrading/ref-kafkatopic-v1-changes.adoc b/documentation/modules/upgrading/ref-kafkatopic-v1-changes.adoc new file mode 100644 index 00000000000..1f3831d3a38 --- /dev/null +++ b/documentation/modules/upgrading/ref-kafkatopic-v1-changes.adoc @@ -0,0 +1,14 @@ +:_mod-docs-content-type: REFERENCE + +[id='ref-kafkatopic-v1-changes-{context}'] += KafkaTopic + +[role="_abstract"] +Changes required for the `KafkaTopic` custom resource in the `v1` API. + +== Manual changes required + +The conversion tool does not apply the following updates. +You must make these changes manually to ensure compatibility: + +* Ensure the `.spec` section is present (required). \ No newline at end of file diff --git a/documentation/modules/upgrading/ref-kafkauser-v1-changes.adoc b/documentation/modules/upgrading/ref-kafkauser-v1-changes.adoc new file mode 100644 index 00000000000..4aff2e38dea --- /dev/null +++ b/documentation/modules/upgrading/ref-kafkauser-v1-changes.adoc @@ -0,0 +1,21 @@ +:_mod-docs-content-type: REFERENCE + +[id='ref-kafkauser-v1-changes-{context}'] += KafkaUser +[role="_abstract"] +Changes required for the `KafkaUser` custom resource in the `v1` API. + +== Manual changes required + +The conversion tool does not apply the following updates. +You must make these changes manually to ensure compatibility: + +* Ensure the `.spec` section is present (required). + +== Automatic changes supported + +The following updates are applied automatically by the conversion tool during conversion. +If the conversion tool is not used, you can apply the same changes manually: + +* Replaces the `operation` property in `.spec.authorization.acls[]` with the `operations` array. +*This change must be applied before upgrading to Strimzi versions 0.49-0.51.* diff --git a/documentation/modules/upgrading/ref-preparing-for-conversion.adoc b/documentation/modules/upgrading/ref-preparing-for-conversion.adoc new file mode 100644 index 00000000000..1e234d0847c --- /dev/null +++ b/documentation/modules/upgrading/ref-preparing-for-conversion.adoc @@ -0,0 +1,15 @@ +:_mod-docs-content-type: REFERENCE + +[id='ref-preparing-for-conversion-{context}'] += Preparing for conversion + +[role="_abstract"] +Before running the Strimzi API conversion tool, confirm that the environment meets the prerequisites for converting Strimzi custom resources and CRDs to the `v1` API. + +Before running the Strimzi API conversion tool, verify that the following conditions are met: + +* The deployed Strimzi version is 0.49 or later. +* All Strimzi custom resources and CRDs are backed up. +* The namespaces that contain Strimzi resources to be converted are identified. +* The user or service account running the tool has RBAC permissions to list, get, and replace Strimzi custom resources. +* Any deprecated or unsupported fields in the `v1` API are reviewed, and manual changes are planned as needed. \ No newline at end of file diff --git a/documentation/modules/upgrading/ref-strimzipodset-v1-changes.adoc b/documentation/modules/upgrading/ref-strimzipodset-v1-changes.adoc new file mode 100644 index 00000000000..34c4bbae783 --- /dev/null +++ b/documentation/modules/upgrading/ref-strimzipodset-v1-changes.adoc @@ -0,0 +1,14 @@ +:_mod-docs-content-type: REFERENCE + +[id='ref-strimzipodset-v1-changes-{context}'] += StrimziPodSet + +[role="_abstract"] +The `StrimziPodSet` is an internal resource managed automatically by the Cluster Operator. +Conversion is handled by Strimzi. + +Changes required for the `StrimziPodSet` custom resource in the `v1` API (for reference): + +* The `.spec` section is required. + +