In Strimzi 0.22 we introduced the v1beta2 API version to prepare Strimzi for Kubernetes 1.22. The v1beta2 API version replaces the v1beta1 and v1alpha1 API versions. This post shows you how to perform an API conversion to v1beta2 to be ready for the next Strimzi releases.

New API versions

By introducing API version v1beta2 for Strimzi resources, current Strimzi users must migrate from the old v1alpha1 and v1beta1 versions. This migration is not necessarily needed right after upgrade to Strimzi 0.22, but has to be done before upgrade to Strimzi 0.23 or later. The main reason for the migration is to prepare Strimzi to use Kubernetes CRD apiextensions/v1.

Custom resources are created and controlled using APIs added to Kubernetes by CRDs. Put another way, CRDs extend the Kubernetes API to allow the creation of custom resources. CRDs are themselves resources within Kubernetes. They are installed in a Kubernetes cluster to define the versions of API for the custom resource. Each version of the custom resource API can define its own schema for that version. Kubernetes clients, including the Strimzi Operators, access the custom resources served by the Kubernetes API server using a URL path (API path), which includes the API version

In 0.22, we still support custom resource version v1alpha1 for all custom resources and v1beta1 for Kafka, KafkaConnect, KafkaConnectS2I, KafkaMirrorMaker, KafkaUser, and KafkaTopic. However, these versions are currently deprecated and will be dropped in the Strimzi 0.23 release. That’s one of the reasons why users have to finish the migration before 0.23.

For the new API version, deprecated custom resource properties have been removed. You need to migrate custom resources to the new structure. For instance, v1beta2 only supports a new array-based listener configuration and new metrics configuration formats from config maps. logging properties have also changed. For metrics configuration, you now use metricsConfig in spec.kafka to reference the name of a config map with metrics configuration using the valueFrom property. Same for logging, but property name remains same. In addition, some old unused fields like tlsSidecar were removed as well. All the changes to properties are fully described in our documentation. You can also see a warning in the custom resource status when the deprecated property is used.

For smooth migration to new custom resources and CRDs version, we provide an api-conversion tool. Note that for proper conversion you need to have Strimzi 0.22 installed with all its CRDs.

API conversion tool

The api conversion tool is shipped with Strimzi 0.22 as a zip file and tar file. After extracting, you will find all the libs needed by the tool in libs directory and two scripts for running the tool in the directory bin. The api-conversion.sh script is for linux/mac users and api-conversion.cmd is for Windows users.

The tool operates in two modes:

  • Converting custom resources to v1beta2. It can convert resources in yaml files or resource already deployed into Kubernetes cluster.
  • Convert CRDs to use v1beta2 as a stored version and use v1beta2 in all Strimzi custom resources.

You can use the tool directly from an extracted directory as shown in the example below.

api-conversion tool help

convert-file

The convert-file (cf) command updates the YAML file of a custom resource, which is passed using an -f or --file parameter. It converts the custom resource to new API version and updates the properties into the current structure. The output is printed to stdout, or you can specify an output file with -o or --output options. You can also use the --in-file option to save changes directly to input file. For more information, run the bin/api-conversion.sh cf --help command.

convert-resources

The convert-resources (cr) command converts custom resources directly in your Kubernetes cluster. You can use -a,--all-namespaces or -n,--namespace options to specify namespace where the resources should be converted. With -k,--kind the tool will convert only a specific kind of custom resources. Or the command can convert multiple kinds. For instance, to convert Kafka and KafkaTopic you just need to pass --kind Kafka --kind KafkaTopic to the cr command.

You can use the --name option to specify a custom resource by name. This option can only be used with --namespace and single --kind options. For more information, you can run the bin/api-conversion.sh cr --help command.

crd-upgrade

The crd-upgrade (crd) command updates spec.versions in the Strimzi CRDs to declare v1beta2 as the storage API version. The command also updates the API version of existing custom resources and stores them as v1beta2.

Once you upgrade CRDs, you must use only the v1beta2 version in Strimzi Custom resources.

Conclusion

In this post we took a brief look at API conversion, which is needed for future Strimzi versions. You can find further information in our documentation.