Upgrade to KubeBlocks v0.9.x

This guide walks you through upgrading KubeBlocks to version 0.9.x. The v0.9.x release series delivers significant improvements in performance, stability, and introduces powerful new features to enhance your database management experience.

Before You Begin

Verify Your Current Version

First, check which version of KubeBlocks you're currently running:

# Using helm
helm -n kb-system list | grep kubeblocks

# Using kbcli
kbcli version

Choose Your Upgrade Path

Select the appropriate upgrade path based on your current version:

Current Version	Target: v0.9.x	Upgrade Path
v0.9.x	✅ Direct upgrade	Follow Upgrade from KubeBlocks v0.9.x
v0.8.x	✅ Direct upgrade	Follow Upgrade from KubeBlocks v0.8.x
v0.7.x or earlier	⚠️ Multi-step upgrade	Upgrade to v0.8.x first, then to v0.9.x

TIP

We recommend upgrading to the latest stable version for optimal performance and access to the newest features.

Upgrade from KubeBlocks v0.9.x

This section covers upgrading between v0.9.x versions (for example, from v0.9.1 to v0.9.5). Since these are patch releases within the same major version, the upgrade process is straightforward.

NOTE

Version Placeholder:

Throughout this section, replace v0.9.5 with your target version number (e.g., v0.9.5, v0.9.4).

Step 1: Update Custom Resource Definitions (CRDs)

KubeBlocks separates CRDs from the Helm chart to reduce chart size. Start by updating the CRDs:

kubectl replace -f https://github.com/apecloud/kubeblocks/releases/download/v0.9.5/kubeblocks_crds.yaml

Step 2: Upgrade KubeBlocks Core

First, update your Helm repository to get the latest chart information:

helm repo add kubeblocks https://apecloud.github.io/helm-charts
helm repo update kubeblocks

Then upgrade KubeBlocks to the target version:

helm -n kb-system upgrade kubeblocks kubeblocks/kubeblocks --version v0.9.5 --set crd.enabled=false

NOTE

Why crd.enabled=false?

Since we're upgrading within the same v0.9.x series, no API conversion is needed. Setting crd.enabled=false skips the CRD upgrade task for faster deployment.

Step 3: (Optional) Upgrade Addons

WARNING

Addon Upgrade Impact:

Upgrading Addons may restart existing database clusters and affect availability. Only proceed during maintenance windows, or upgrade Addons individually as needed.

To upgrade Addons to the versions bundled with the new KubeBlocks version:

helm -n kb-system upgrade kubeblocks kubeblocks/kubeblocks --version v0.9.5 \
--set upgradeAddons=true \
--set crd.enabled=false

Step 1: Update kbcli

Download and install the matching version of kbcli:

curl -fsSL https://kubeblocks.io/installer/install_cli.sh | bash -s v0.9.5

Step 2: Upgrade KubeBlocks Core

Perform the core upgrade without updating Addons:

kbcli kb upgrade --version v0.9.5

Step 3: (Optional) Upgrade Addons

WARNING

Addon Upgrade Impact:

Upgrading Addons may restart existing database clusters and affect availability. Only proceed during maintenance windows, or upgrade Addons individually as needed.

To upgrade Addons to the versions bundled with the new KubeBlocks version:

kbcli kb upgrade --version v0.9.5 --set upgradeAddons=true

Upgrade from KubeBlocks v0.8.x

This section covers upgrading from v0.8.x to v0.9.x. This is a major version upgrade that requires additional preparation steps due to API changes.

NOTE

Key API Changes in v0.9.x:

Storage provider group updated from storage.kubeblocks.io to dataprotection.kubeblocks.io
Enhanced ConfigConstraint API with multi-version support

Step 1: Add the "helm.sh/resource-policy": "keep" annotation to Addons

KubeBlocks v0.9 changed the default installed Addons, so you need to add the "helm.sh/resource-policy": "keep" annotation to Addons to avoid deleting them during the upgrade.

kubectl get addons -oname | xargs -I {} kubectl annotate {} helm.sh/resource-policy=keep

Step 2: Clean Up Incompatible Resources

Remove OpsDefinition that are incompatible with v0.9.x:

# Delete specific incompatible OpsDefinitions
kubectl delete opsdefinitions.apps.kubeblocks.io kafka-quota kafka-topic kafka-user-acl switchover

# Alternative: Delete all OpsDefinitions (they will be recreated during upgrade)
kubectl delete opsdefinitions.apps.kubeblocks.io --all

Step 3: Update Custom Resource Definitions (CRDs)

Install the new Storage Provider CRD required for v0.9.x and update all KubeBlocks CRDs to the new version:

kubectl create -f https://github.com/apecloud/kubeblocks/releases/download/v0.9.5/kubeblocks_crds.yaml || kubectl replace -f https://github.com/apecloud/kubeblocks/releases/download/v0.9.5/kubeblocks_crds.yaml

NOTE

Network Optimization:

Or download the CRD YAML files locally first, then apply them using kubectl create -f <local-file-path> || kubectl replace -f <local-file-path>.

Step 3: Update Helm Repository and Upgrade KubeBlocks

Update your Helm repository to get the latest chart information:

helm repo add kubeblocks https://apecloud.github.io/helm-charts
helm repo update kubeblocks

Enable webhooks for multi-version conversion (it will convert ConfigConstraint API to the new version):

helm -n kb-system upgrade kubeblocks kubeblocks/kubeblocks --version v0.9.5 \
--set admissionWebhooks.enabled=true \
--set admissionWebhooks.ignoreReplicasCheck=true

NOTE

Configuration Options Explained:

admissionWebhooks.enabled=true: Enables webhook for ConfigConstraint API multi-version conversion
admissionWebhooks.ignoreReplicasCheck=true: Allows webhook to run with single replica deployments

Step 4: (Optional) Upgrade Addons

WARNING

Addon Upgrade Impact:

Upgrading Addons may restart existing database clusters and affect availability. Only proceed during maintenance windows. Or you can upgrade Addons individually.

helm -n kb-system upgrade kubeblocks kubeblocks/kubeblocks --version v0.9.5 \
--set upgradeAddons=true \
--set admissionWebhooks.enabled=true \
--set admissionWebhooks.ignoreReplicasCheck=true

Step 1: Update kbcli

Download and install kbcli for the target version:

curl -fsSL https://kubeblocks.io/installer/install_cli.sh | bash -s v0.9.5

Verify the installation:

kbcli version

Step 2: Upgrade KubeBlocks with Webhook Support

Upgrade KubeBlocks with enhanced API validation and multi-version support:

kbcli kb upgrade --version v0.9.5 \
--set admissionWebhooks.enabled=true \
--set admissionWebhooks.ignoreReplicasCheck=true

NOTE

Configuration Options Explained:

admissionWebhooks.enabled=true: Enables webhook for ConfigConstraint API multi-version conversion
admissionWebhooks.ignoreReplicasCheck=true: Allows webhook to run with single replica deployments (useful for development environments)

Step 3: (Optional) Upgrade Addons

WARNING

Addon Upgrade Impact:

Upgrading Addons may restart existing database clusters and affect availability. Only proceed during maintenance windows, or upgrade Addons individually as needed.

To upgrade Addons along with KubeBlocks:

kbcli kb upgrade --version v0.9.5 \
--set upgradeAddons=true \
--set admissionWebhooks.enabled=true \
--set admissionWebhooks.ignoreReplicasCheck=true

Some Addons require special handling when upgrading from v0.8.x to v0.9.x.

Required: The mysql Addon must be upgraded when moving from v0.8.x to v0.9.x. Clusters created in v0.8.x will not function properly in v0.9.x without this upgrade.
Recommended: For clickhouse, milvus, elasticsearch, and llm Addons, upgrade KubeBlocks first, then upgrade these Addons for optimal functionality.

Individual Addon Upgrades

If you chose not to upgrade Addons during the KubeBlocks upgrade, or if you need to upgrade specific Addons, follow these steps to upgrade Addons individually.

Upgrade Methods

Step 1: Configure Addon Repository

# Add the primary Addon repository
helm repo add kubeblocks-addons https://apecloud.github.io/helm-charts

# Alternative repository for users in regions with limited GitHub access
# helm repo add kubeblocks-addons https://jihulab.com/api/v4/projects/150246/packages/helm/stable

# Update repository information
helm repo update

Step 2: Find Available Versions

# Search for available versions of a specific Addon
helm search repo kubeblocks-addons/{addon-name} --versions --devel
# Example: helm search repo kubeblocks-addons/mysql --versions --devel

Step 3: Upgrade the Addon

Select a version that is compatible (same major version) with your KubeBlocks release and upgrade:

# Upgrade to a specific version
helm upgrade -i {addon-release-name} kubeblocks-addons/{addon-name} --version x.y.z -n kb-system

NOTE

Parameter Reference:

{addon-name}: Replace with the actual Addon name (e.g., mysql, postgresql)
{addon-release-name}: The release name of the installed Addon (e.g., kb-addon-mysql, kb-addon-postgresql)
x.y.z: The target version number, compatible with your KubeBlocks release

Step 1: Update Addon Index

# List available Addon indexes (the default index is `kubeblocks`)
kbcli addon index list

# Update the default KubeBlocks index
kbcli addon index update kubeblocks

Step 2: Search for Available Addon Versions

# Search for available versions of a specific Addon
kbcli addon search {addon-name}

# View currently installed Addons and their versions
kbcli addon list | grep {addon-name}

Step 3: Upgrade the Addon

Select a version that is compatible (same major version) with your KubeBlocks release and upgrade:

kbcli addon upgrade {addon-name} --version x.y.z

Force upgrade (use with caution):

kbcli addon upgrade {addon-name} --version x.y.z --force

Fresh installation (if not previously installed):

kbcli addon install {addon-name} --version x.y.z

NOTE

When to use --force:

You need to downgrade to a previous version
Use with caution as it bypasses compatibility checks

Getting Help

If you encounter issues during the upgrade process:

Check the logs: Review upgrade logs using kubectl -n kb-system logs deployment/kubeblocks
Community Support: Visit the KubeBlocks GitHub Issues for known issues and community help

Upgrade to KubeBlocks v0.9.x

Before You Begin

Verify Your Current Version

First, check which version of KubeBlocks you're currently running:

# Using helm
helm -n kb-system list | grep kubeblocks

# Using kbcli
kbcli version

Choose Your Upgrade Path

Select the appropriate upgrade path based on your current version:

Current Version	Target: v0.9.x	Upgrade Path
v0.9.x	✅ Direct upgrade	Follow Upgrade from KubeBlocks v0.9.x
v0.8.x	✅ Direct upgrade	Follow Upgrade from KubeBlocks v0.8.x
v0.7.x or earlier	⚠️ Multi-step upgrade	Upgrade to v0.8.x first, then to v0.9.x

TIP

We recommend upgrading to the latest stable version for optimal performance and access to the newest features.

Upgrade from KubeBlocks v0.9.x

This section covers upgrading between v0.9.x versions (for example, from v0.9.1 to v0.9.5). Since these are patch releases within the same major version, the upgrade process is straightforward.

NOTE

Version Placeholder:

Throughout this section, replace v0.9.5 with your target version number (e.g., v0.9.5, v0.9.4).

Step 1: Update Custom Resource Definitions (CRDs)

KubeBlocks separates CRDs from the Helm chart to reduce chart size. Start by updating the CRDs:

kubectl replace -f https://github.com/apecloud/kubeblocks/releases/download/v0.9.5/kubeblocks_crds.yaml

Step 2: Upgrade KubeBlocks Core

First, update your Helm repository to get the latest chart information:

helm repo add kubeblocks https://apecloud.github.io/helm-charts
helm repo update kubeblocks

Then upgrade KubeBlocks to the target version:

helm -n kb-system upgrade kubeblocks kubeblocks/kubeblocks --version v0.9.5 --set crd.enabled=false

NOTE

Why crd.enabled=false?

Since we're upgrading within the same v0.9.x series, no API conversion is needed. Setting crd.enabled=false skips the CRD upgrade task for faster deployment.

Step 3: (Optional) Upgrade Addons

WARNING

Addon Upgrade Impact:

Upgrading Addons may restart existing database clusters and affect availability. Only proceed during maintenance windows, or upgrade Addons individually as needed.

To upgrade Addons to the versions bundled with the new KubeBlocks version:

helm -n kb-system upgrade kubeblocks kubeblocks/kubeblocks --version v0.9.5 \
--set upgradeAddons=true \
--set crd.enabled=false

Step 1: Update kbcli

Download and install the matching version of kbcli:

curl -fsSL https://kubeblocks.io/installer/install_cli.sh | bash -s v0.9.5

Step 2: Upgrade KubeBlocks Core

Perform the core upgrade without updating Addons:

kbcli kb upgrade --version v0.9.5

Step 3: (Optional) Upgrade Addons

WARNING

Addon Upgrade Impact:

Upgrading Addons may restart existing database clusters and affect availability. Only proceed during maintenance windows, or upgrade Addons individually as needed.

To upgrade Addons to the versions bundled with the new KubeBlocks version:

kbcli kb upgrade --version v0.9.5 --set upgradeAddons=true

Upgrade from KubeBlocks v0.8.x

This section covers upgrading from v0.8.x to v0.9.x. This is a major version upgrade that requires additional preparation steps due to API changes.

NOTE

Key API Changes in v0.9.x:

Storage provider group updated from storage.kubeblocks.io to dataprotection.kubeblocks.io
Enhanced ConfigConstraint API with multi-version support

Step 1: Add the "helm.sh/resource-policy": "keep" annotation to Addons

KubeBlocks v0.9 changed the default installed Addons, so you need to add the "helm.sh/resource-policy": "keep" annotation to Addons to avoid deleting them during the upgrade.

kubectl get addons -oname | xargs -I {} kubectl annotate {} helm.sh/resource-policy=keep

Step 2: Clean Up Incompatible Resources

Remove OpsDefinition that are incompatible with v0.9.x:

# Delete specific incompatible OpsDefinitions
kubectl delete opsdefinitions.apps.kubeblocks.io kafka-quota kafka-topic kafka-user-acl switchover

# Alternative: Delete all OpsDefinitions (they will be recreated during upgrade)
kubectl delete opsdefinitions.apps.kubeblocks.io --all

Step 3: Update Custom Resource Definitions (CRDs)

Install the new Storage Provider CRD required for v0.9.x and update all KubeBlocks CRDs to the new version:

kubectl create -f https://github.com/apecloud/kubeblocks/releases/download/v0.9.5/kubeblocks_crds.yaml || kubectl replace -f https://github.com/apecloud/kubeblocks/releases/download/v0.9.5/kubeblocks_crds.yaml

NOTE

Network Optimization:

Or download the CRD YAML files locally first, then apply them using kubectl create -f <local-file-path> || kubectl replace -f <local-file-path>.

Step 3: Update Helm Repository and Upgrade KubeBlocks

Update your Helm repository to get the latest chart information:

helm repo add kubeblocks https://apecloud.github.io/helm-charts
helm repo update kubeblocks

Enable webhooks for multi-version conversion (it will convert ConfigConstraint API to the new version):

helm -n kb-system upgrade kubeblocks kubeblocks/kubeblocks --version v0.9.5 \
--set admissionWebhooks.enabled=true \
--set admissionWebhooks.ignoreReplicasCheck=true

NOTE

Configuration Options Explained:

admissionWebhooks.enabled=true: Enables webhook for ConfigConstraint API multi-version conversion
admissionWebhooks.ignoreReplicasCheck=true: Allows webhook to run with single replica deployments

Step 4: (Optional) Upgrade Addons

WARNING

Addon Upgrade Impact:

Upgrading Addons may restart existing database clusters and affect availability. Only proceed during maintenance windows. Or you can upgrade Addons individually.

helm -n kb-system upgrade kubeblocks kubeblocks/kubeblocks --version v0.9.5 \
--set upgradeAddons=true \
--set admissionWebhooks.enabled=true \
--set admissionWebhooks.ignoreReplicasCheck=true

Step 1: Update kbcli

Download and install kbcli for the target version:

curl -fsSL https://kubeblocks.io/installer/install_cli.sh | bash -s v0.9.5

Verify the installation:

kbcli version

Step 2: Upgrade KubeBlocks with Webhook Support

Upgrade KubeBlocks with enhanced API validation and multi-version support:

kbcli kb upgrade --version v0.9.5 \
--set admissionWebhooks.enabled=true \
--set admissionWebhooks.ignoreReplicasCheck=true

NOTE

Configuration Options Explained:

admissionWebhooks.enabled=true: Enables webhook for ConfigConstraint API multi-version conversion
admissionWebhooks.ignoreReplicasCheck=true: Allows webhook to run with single replica deployments (useful for development environments)

Step 3: (Optional) Upgrade Addons

WARNING

Addon Upgrade Impact:

Upgrading Addons may restart existing database clusters and affect availability. Only proceed during maintenance windows, or upgrade Addons individually as needed.

To upgrade Addons along with KubeBlocks:

kbcli kb upgrade --version v0.9.5 \
--set upgradeAddons=true \
--set admissionWebhooks.enabled=true \
--set admissionWebhooks.ignoreReplicasCheck=true

Some Addons require special handling when upgrading from v0.8.x to v0.9.x.

Required: The mysql Addon must be upgraded when moving from v0.8.x to v0.9.x. Clusters created in v0.8.x will not function properly in v0.9.x without this upgrade.
Recommended: For clickhouse, milvus, elasticsearch, and llm Addons, upgrade KubeBlocks first, then upgrade these Addons for optimal functionality.

Individual Addon Upgrades

If you chose not to upgrade Addons during the KubeBlocks upgrade, or if you need to upgrade specific Addons, follow these steps to upgrade Addons individually.

Upgrade Methods

Step 1: Configure Addon Repository

# Add the primary Addon repository
helm repo add kubeblocks-addons https://apecloud.github.io/helm-charts

# Alternative repository for users in regions with limited GitHub access
# helm repo add kubeblocks-addons https://jihulab.com/api/v4/projects/150246/packages/helm/stable

# Update repository information
helm repo update

Step 2: Find Available Versions

# Search for available versions of a specific Addon
helm search repo kubeblocks-addons/{addon-name} --versions --devel
# Example: helm search repo kubeblocks-addons/mysql --versions --devel

Step 3: Upgrade the Addon

Select a version that is compatible (same major version) with your KubeBlocks release and upgrade:

# Upgrade to a specific version
helm upgrade -i {addon-release-name} kubeblocks-addons/{addon-name} --version x.y.z -n kb-system

NOTE

Parameter Reference:

{addon-name}: Replace with the actual Addon name (e.g., mysql, postgresql)
{addon-release-name}: The release name of the installed Addon (e.g., kb-addon-mysql, kb-addon-postgresql)
x.y.z: The target version number, compatible with your KubeBlocks release

Step 1: Update Addon Index

# List available Addon indexes (the default index is `kubeblocks`)
kbcli addon index list

# Update the default KubeBlocks index
kbcli addon index update kubeblocks

Step 2: Search for Available Addon Versions

# Search for available versions of a specific Addon
kbcli addon search {addon-name}

# View currently installed Addons and their versions
kbcli addon list | grep {addon-name}

Step 3: Upgrade the Addon

Select a version that is compatible (same major version) with your KubeBlocks release and upgrade:

kbcli addon upgrade {addon-name} --version x.y.z

Force upgrade (use with caution):

kbcli addon upgrade {addon-name} --version x.y.z --force

Fresh installation (if not previously installed):

kbcli addon install {addon-name} --version x.y.z

NOTE

When to use --force:

You need to downgrade to a previous version
Use with caution as it bypasses compatibility checks

Getting Help

If you encounter issues during the upgrade process:

Check the logs: Review upgrade logs using kubectl -n kb-system logs deployment/kubeblocks
Community Support: Visit the KubeBlocks GitHub Issues for known issues and community help