Upgrading KubeDB

This guide will show you how to upgrade various KubeDB components. Here, we are going to show how to upgrade from an old KubeDB version to the new version, and how to update the license, etc.

Upgrading KubeDB from v2021.xx.xx to v2024.6.4

In order to upgrade from KubeDB v2021.xx.xx to v2024.6.4, please follow the following steps.

Please note that since v2021.08.23, we recommend installing KubeDB operator in the kubedb namespace. The upgrade instructions on this page assumes so. If you have currently installed the operator in a different namespace like kube-system, either follow the instructions with appropriate updates, or first uninstall the existing operator and then reinstall in the kubedb namespace.

1. Update KubeDB Catalog CRDs

Helm does not upgrade the CRDs bundled in a Helm chart if the CRDs already exist. So, to upgrde the KubeDB catalog CRD, please run the command below:

kubectl apply -f https://github.com/kubedb/installer/raw/v2024.6.4/crds/kubedb-catalog-crds.yaml

kubectl apply -f https://github.com/kubeops/petset/raw/v0.0.6/crds/apps.k8s.appscode.com_petsets.yaml
kubectl apply -f https://github.com/kubeops/petset/raw/v0.0.6/crds/apps.k8s.appscode.com_placementpolicies.yaml

2. Upgrade KubeDB Operator

Now, upgrade the KubeDB helm chart using the following command. You can find the latest installation guide here. We recommend that you do not follow the legacy installation guide, as the new process is much more simpler.

helm upgrade -i kubedb oci://ghcr.io/appscode-charts/kubedb \
  --version v2024.6.4 \
  --namespace kubedb --create-namespace \
  --set kubedb-catalog.skipDeprecated=false \
  --set-file global.license=/path/to/the/license.txt \
  --wait --burst-limit=10000 --debug
If you are using private Docker registries using self-signed certificates, please pass the registry domains to the operator like below:
helm upgrade -i kubedb oci://ghcr.io/appscode-charts/kubedb \
  --version v2024.6.4 \
  --namespace kubedb --create-namespace \
  --set kubedb-catalog.skipDeprecated=false \
  --set global.insecureRegistries[0]=hub.example.com \
  --set global.insecureRegistries[1]=hub2.example.com \
  --set-file global.license=/path/to/the/license.txt \
  --wait --burst-limit=10000 --debug

3. Install/Upgrade Stash Operator

Now, upgrade Stash if had previously installed Stash following the instructions here. If you had not installed Stash before, please install Stash following the instructions here.

Upgrading KubeDB from v2021.01.26(v0.16.x) and older to v2024.6.4

In KubeDB v2021.01.26(v0.16.x) and prior versions, KubeDB used separate charts for KubeDB community edition, KubeDB enterprise edition, and KubeDB catalogs. In KubeDB v2024.6.4, we have moved to a single combined chart for all the components for a better user experience. KubeDB still depends on Stash as the backup/recovery operator and Stash must be installed separately.

In order to upgrade from KubeDB v2021.01.26(v0.16.x) to v2024.6.4, please follow the following steps.

1. Uninstall KubeDB Operator

Uninstall the old KubeDB operator by following the appropriate uninstallation guide of the KubeDB version that you are currently running.

Make sure you are using the appropriate version of the uninstallation guide. Use the dropdown at the sidebar of the documentation site to navigate to the appropriate version that you are currently running.

2. Update KubeDB Catalog CRDs

Helm does not upgrade the CRDs bundled in a Helm chart if the CRDs already exist. So, to upgrde the KubeDB catalog CRD, please run the command below:

kubectl apply -f https://github.com/kubedb/installer/raw/v2024.6.4/crds/kubedb-catalog-crds.yaml

3. Reinstall new KubeDB Operator

Now, follow the latest installation guide to install the new version of the KubeDB operator. You can find the latest installation guide here. We recommend that you do not follow the legacy installation guide, as the new process is much more simpler.

4. Install/Upgrade Stash Operator

Now, upgrade Stash if had previously installed Stash following the instructions here. If you had not installed Stash before, please install Stash following the instructions here.

Updating License

KubeDB support updating license without requiring any re-installation. KubeDB creates a Secret named <helm release name>-license with the license file. You just need to update the Secret. The changes will propagate automatically to the operator and it will use the updated license going forward.

Follow the below instructions to update the license:

  • Get a new license and save it into a file.
  • Then, run the following upgrade command based on your installation.

Using Helm 3

# detect current version
helm ls -A | grep kubedb

# update license key keeping the current version
helm upgrade -i kubedb oci://ghcr.io/appscode-charts/kubedb \
  --version=<cur_version> \
  --reuse-values \
  --set-file global.license=/path/to/new/license.txt \
  --wait --burst-limit=10000 --debug

Using YAML (with helm 3)

# detect current version
helm ls -A | grep kubedb

# update license key keeping the current version
helm template kubedb oci://ghcr.io/appscode-charts/kubedb \
  --version=<cur_version> \
  --namespace kubedb --create-namespace \
  --set global.skipCleaner=true \
  --show-only appscode/kubedb/templates/license.yaml \
  --set-file global.license=/path/to/new/license.txt | kubectl apply -f -