Upgrading to 0.18.x

This guide explains how to upgrade from 0.17.x to 0.18.x.

Caution

A Kannika Armory version sometimes contain changes that prepare existing resources for an upcoming release, such as new annotations and labels.

Make sure you always upgrade in steps and never skip a version.

Before you begin

Before you begin the upgrade process, ensure that you have a backup of your data.

The upgrade process will not touch the actual backup data, but might change the resource definitions.

Breaking changes

This release contains the following breaking changes.

Restores require Topic:DescribeConfigs

A restore that cannot read the configuration of its target topic now fails that topic and reports the missing permission. It previously continued with an empty configuration, or failed later with a misleading plugin error. Verify that the principal your restores connect with has the Topic:DescribeConfigs permission on the target topics.

Required permissionsThe full list of Kafka permissions a backup and a restore need.

Additional properties are rejected on S3 storage endpoints

sourceAdditionalProps and sinkAdditionalProps are no longer accepted on backups and restores that use an S3 storage endpoint. A resource that still carries them reports ConfigurationValid: False naming the offending keys, and its workload is not deployed or updated until they are removed. Additional properties keep working on Kafka event hubs.

Kubernetes 1.30 is the minimum version

The Helm chart now refuses to install on clusters below Kubernetes 1.30, which has been the documented minimum since 0.15.0.

Checklist

Follow the steps in this checklist to upgrade to 0.18.x.

• Grant Topic:DescribeConfigs to the restore principals
• Remove additional properties from S3 backups and restores
• Enable maintenance mode
• Upgrade CRDs
• Install application with updated Helm values
• Disable maintenance mode
• Verify the installation

Grant Topic:DescribeConfigs to the restore principals

Verify that every principal a restore connects with has the Topic:DescribeConfigs permission on the target topics, and grant it where it is missing. Do this before the upgrade, so restores that are running or resumed after the upgrade can read their topic configuration.

Remove additional properties from S3 backups and restores

Find the backups and restores that set sourceAdditionalProps or sinkAdditionalProps on an S3 storage endpoint:

$ kubectl get backups,restores -A -o json \
  | jq -r '.items[] | select(.spec.sourceAdditionalProps != null or .spec.sinkAdditionalProps != null) | "\(.kind) \(.metadata.namespace)/\(.metadata.name)"'

Remove those properties from the resources that use an S3 endpoint. Resources that keep them report ConfigurationValid: False after the upgrade and are not updated until the properties are gone.

Enable maintenance mode

Enable maintenance mode for the duration of the upgrade.

values.yaml

global:
  maintenance:
    enabled: true
    banner:
      message: "Upgrade in progress, we will be back shortly."
      variant: "info"

Upgrade CRDs

Install the new Custom Resource Definitions (CRDs) for 0.18.x.:

Using kubectl

$ kubectl apply -f https://docs.kannika.io/refs/0.18.0/crd/kannika-crd-v1alpha.yml

Using Helm

$ helm install kannika-crd oci://quay.io/kannika/charts/kannika-crd \
  --version 0.18.0

Install application with updated Helm values

Custom CA certificates from a ConfigMap

This release adds an optional Helm value to provide the API’s custom CA certificates through a ConfigMap instead of a Secret. No action is required if you do not use custom CA certificates, or already provide them through secretName. Set either configMapName or secretName, not both.

values.yaml

api:
  config:
    tls:
      customCaCertificates:
        configMapName: my-ca-certs

Custom CA certificatesLearn how to trust a private CA from the API.

Pods roll once

Credential and certificate files are now mounted under /var/run/secrets/kannika.io/ instead of /etc/kannika/, and event hub TLS certificates are mounted from their Secrets instead of being written into the ConfigMap. Nothing changes in your manifests, but every backup and restore pod rolls once after the operator is upgraded.

Install the new version of Kannika Armory

Install the new version of Kannika Armory using Helm:

$ helm upgrade --install kannika oci://quay.io/kannika/charts/kannika \
  --create-namespace \
  --namespace kannika-system \
  --version 0.18.0 \
  --values values.yaml

InstallationLearn how to install Kannika Armory

Disable maintenance mode

Once you have completed the upgrade process, disable maintenance mode by setting global.maintenance.enabled to false.

values.yaml

global:
  maintenance:
    enabled: false

Verify the installation

Verify that the upgrade was successful by checking the logs of the Kannika Armory components:

$ kubectl logs -n kannika-system -l app.kubernetes.io/name=kannika-operator # or operator
$ kubectl logs -n kannika-system -l app.kubernetes.io/name=kannika-api      # or api
$ kubectl logs -n kannika-system -l app.kubernetes.io/name=kannika-console  # or console

Verify that the backups are running as expected:

$ kubectl get backups -n [NAMESPACE]
$ kubectl get schemaregistrybackups -n [NAMESPACE]

Check that no backup or restore reports ConfigurationValid: False:

$ kubectl get backups,restores -A -o json \
  | jq -r '.items[] | select(.status.conditions[]? | .type == "ConfigurationValid" and .status == "False") | "\(.kind) \(.metadata.namespace)/\(.metadata.name)"'

If you encounter any issues during the upgrade process, do not hesitate to contact us on Slack.