// Module included in the following assemblies:
//
// assembly-upgrade-resources.adoc

[id='proc-upgrade-cli-tool-files-{context}']
= Converting custom resources configuration files using the API conversion tool

[role="_abstract"]
This procedure describes how to use the API conversion tool to convert YAML files describing the configuration for Strimzi custom resources into a format applicable to `{ApiVersion}`.
To do so, you use the `convert-file` (`cf`) command.

The `convert-file` command can convert YAML files containing multiple documents.
For a multi-document YAML file, all the Strimzi custom resources it contains are converted.
Any non-Strimzi Kubernetes resources are replicated unmodified in the converted output file.

After you have converted the YAML file, you must apply the configuration to update the custom resource in the cluster.
Alternatively, if the GitOps synchronization mechanism is being used for updates on your cluster, you can use it to apply the changes.
The conversion is only complete when the custom resource is updated in the Kubernetes cluster.

Alternatively, you can use the xref:proc-upgrade-cli-tool-direct-{context}[`convert-resource` procedure to convert custom resources directly].

.Prerequisites

* A Cluster Operator supporting the `{ApiVersion}` API version is up and running.
* The API conversion tool, which is provided with the release artifacts.
* The tool requires Java 11.

Use the CLI help for more information on the API conversion tool, and the flags available for the `convert-file` command:

[source,shell]
----
bin/api-conversion.sh help
bin/api-conversion.sh help convert-file
----

Use `bin/api-conversion.cmd` for this procedure if you are using Windows.

.Flags for YAML file conversion
[cols="2*",options="header",stripes="none"]
|===

|Flag
|Description

|`-f`, `--file=_NAME-OF-YAML-FILE_`
|Specifies the YAML file for the Strimzi custom resource being converted

|`-o,` `--output=_NAME-OF-CONVERTED-YAML-FILE_`
|Creates an output YAML file for the converted custom resource

|`--in-place`
|Updates the original source file with the converted YAML

|===

.Procedure

. Run the API conversion tool with the `convert-file` command and appropriate flags.
+
Example 1, converts a YAML file and displays the output, though the file does not change:
+
[source,shell]
----
bin/api-conversion.sh convert-file --file input.yaml
----
+
Example 2, converts a YAML file, and writes the changes into the original source file:
+
[source,shell]
----
bin/api-conversion.sh convert-file --file input.yaml --in-place
----
+
Example 3, converts a YAML file, and writes the changes into a new output file:
+
[source,shell]
----
bin/api-conversion.sh convert-file --file input.yaml --output output.yaml
----

. Update the custom resources using the converted configuration file.
+
[source,shell,subs=+quotes]
kubectl apply -f _CONVERTED-CONFIG-FILE_

. Verify that the custom resources have been converted.
+
[source,shell,subs=+quotes]
kubectl get _KIND_ _CUSTOM-RESOURCE-NAME_ -o yaml
