Upgrade to KubeBlocks v0.9.x

NOTE

Before upgrading, check your current KubeBlocks version:

Run helm -n kb-system list | grep kubeblocks or kbcli version.
For upgrading to different versions:
- For v0.9.2 and v0.9.1, follow this upgrade tutorial, replacing the version number with v0.9.2 or v0.9.1 respectively.
- v0.9.0 upgrade guide
- v0.8.x upgrade guide.
Installing the latest version is recommended for better performance and features.

Compatibility

KubeBlocks v0.9.3 is compatible with KubeBlocks v0.8 APIs, but compatibility with APIs from versions prior to v0.8 is not guaranteed. If you are using Addons from KubeBlocks v0.7 or earlier (v0.6, etc), DO upgrade KubeBlocks and all Addons to v0.8 first to ensure service availability before upgrading to v0.9.

If you are upgrading from v0.8 to v0.9, it's recommended to enable webhook to ensure the availability.

Upgrade from KubeBlocks v0.9.x

View Addon and check whether the "helm.sh/resource-policy": "keep" annotation exists.

KubeBlocks streamlines the default installed engines. Add the "helm.sh/resource-policy": "keep" annotation to avoid deleting Addon resources that are already in use during the upgrade.

Check whether the "helm.sh/resource-policy": "keep" annotation is added.
```
kubectl get addon -o json | jq '.items[] | {name: .metadata.name, resource_policy: .metadata.annotations["helm.sh/resource-policy"]}'
```
If the annotation doesn't exist, run the command below to add it. You can replace -l app.kubernetes.io/name=kubeblocks with your actual filter name.
```
kubectl annotate addons.extensions.kubeblocks.io -l app.kubernetes.io/name=kubeblocks helm.sh/resource-policy=keep
```
Install CRD.

To reduce the size of Helm chart, KubeBlocks v0.8 removes CRD from the Helm chart. Before upgrading, you need to install CRD.
```
kubectl replace -f https://github.com/apecloud/kubeblocks/releases/download/v0.9.3/kubeblocks_crds.yaml
```
Upgrade KubeBlocks.
```
helm -n kb-system upgrade kubeblocks kubeblocks/kubeblocks --version 0.9.3 --set crd.enabled=false
```
Upgrading from v0.9.0/v0.9.1/v0.9.2 to v0.9.3 doesn't include API change, so you can set --set crd.enabled=false to skip the API upgrade task.
WARNING
To avoid affecting existing database clusters, when upgrading to KubeBlocks v0.9.3, the versions of already-installed Addons will not be upgraded by default. If you want to upgrade the Addons to the versions built into KubeBlocks v0.9.3, execute the following command. Note that this may restart existing clusters and affect availability. Please proceed with caution.
```
helm -n kb-system upgrade kubeblocks kubeblocks/kubeblocks --version 0.9.3 \
  --set upgradeAddons=true \
  --set crd.enabled=false
```

Download kbcli v0.9.3.

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

Upgrade KubeBlocks.
```
kbcli kb upgrade --version 0.9.3
```
WARNING
To avoid affecting existing database clusters, when upgrading to KubeBlocks v0.9.3, the versions of already-installed Addons will not be upgraded by default. If you want to upgrade the Addons to the versions built into KubeBlocks v0.9.3, execute the following command. Note that this may restart existing clusters and affect availability. Please proceed with caution.
```
kbcli kb upgrade --version 0.9.3 --set upgradeAddons=true
```
kbcli will automatically add the annotation "helm.sh/resource-policy": "keep" to ensure that existing Addons are not deleted during the upgrade.

Upgrade from KubeBlocks v0.8.x

View Addon and check whether the "helm.sh/resource-policy": "keep" annotation exists.

KubeBlocks streamlines the default installed engines. Add the "helm.sh/resource-policy": "keep" annotation to avoid deleting Addon resources that are already in use during the upgrade.

Check whether the "helm.sh/resource-policy": "keep" annotation is added.
```
kubectl get addon -o json | jq '.items[] | {name: .metadata.name, resource_policy: .metadata.annotations["helm.sh/resource-policy"]}'
```
If the annotation doesn't exists, run the command below to add it. You can replace -l app.kubernetes.io/name=kubeblocks with your actual filter name.
```
kubectl annotate addons.extensions.kubeblocks.io -l app.kubernetes.io/name=kubeblocks helm.sh/resource-policy=keep
```

Delete the incompatible OpsDefinition.

kubectl delete opsdefinitions.apps.kubeblocks.io kafka-quota kafka-topic kafka-user-acl switchover

Install CRD.

To reduce the size of Helm chart, KubeBlocks v0.8 removed CRD from the Helm chart and changed the group of StorageProvider. Before upgrading, you need to install StorageProvider CRD first.

If the network is slow, it's recommended to download the CRD YAML file on your localhost before further operations.
```
kubectl create -f https://github.com/apecloud/kubeblocks/releases/download/v0.9.3/dataprotection.kubeblocks.io_storageproviders.yaml
```
Upgrade KubeBlocks.

Here are some options that need your attention before the upgrade.
- Setting admissionWebhooks.enabled=true enables the webhook, supporting the multi-version conversion of the ConfigConstraint API.
- Setting admissionWebhooks.ignoreReplicasCheck=true enables the webhook by default only when KubeBlocks is deployed with 3 replicas. If only a single replica is deployed, you can configure this variable to bypass the check.
- If the KubeBlocks you are running uses the image registry starting with infracreate-registry, it is recommended to explicitly configure the image registry during the upgrade.
```
helm repo add kubeblocks https://apecloud.github.io/helm-charts

helm repo update kubeblocks

helm -n kb-system upgrade kubeblocks kubeblocks/kubeblocks --version 0.9.3 \
  --set admissionWebhooks.enabled=true \
  --set admissionWebhooks.ignoreReplicasCheck=true
```
WARNING
To avoid affecting existing database clusters, when upgrading to KubeBlocks v0.9.3, the versions of already-installed Addons will not be upgraded by default. If you want to upgrade the Addons to the versions built into KubeBlocks v0.9.3, execute the following command. Note that this may restart existing clusters and affect availability. Please proceed with caution.
```
helm -n kb-system upgrade kubeblocks kubeblocks/kubeblocks --version 0.9.3 \
  --set upgradeAddons=true \
  --set admissionWebhooks.enabled=true \
  --set admissionWebhooks.ignoreReplicasCheck=true
```

Download kbcli v0.9.3.

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

Upgrade KubeBlocks.

Check the kbcli version and make sure you're using kbcli v0.9.3.
```
kbcli version
```
Here are some options that need your attention before the upgrade.
- Setting admissionWebhooks.enabled=true enables the webhook, supporting the multi-version conversion of the ConfigConstraint API.
- Setting admissionWebhooks.ignoreReplicasCheck=true enables the webhook by default only when KubeBlocks is deployed with 3 replicas. If only a single replica is deployed, you can configure this variable to bypass the check.
- If the KubeBlocks you are running uses the image registry starting with infracreate-registry, it is recommended to explicitly configure the image registry during the upgrade.
```
kbcli kb upgrade --version 0.9.3 \
  --set admissionWebhooks.enabled=true \
  --set admissionWebhooks.ignoreReplicasCheck=true
```
WARNING
To avoid affecting existing database clusters, when upgrading to KubeBlocks v0.9.3, the versions of already-installed Addons will not be upgraded by default. If you want to upgrade the Addons to the versions built into KubeBlocks v0.9.3, execute the following command. Note that this may restart existing clusters and affect availability. Please proceed with caution.
```
kbcli kb upgrade --version 0.9.3 \
  --set upgradeAddons=true \
  --set admissionWebhooks.enabled=true \
  --set admissionWebhooks.ignoreReplicasCheck=true
```
kbcli will automatically add the annotation "helm.sh/resource-policy": "keep" to ensure that existing Addons are not deleted during the upgrade.

Upgrade Addons

If you didn't specify upgradeAddons as true or your Addon is not included in the default installed Addons, you can upgrade Addons by running the commands provided below to use the v0.9.x API.

NOTE

If the Addon you want to upgrade is mysql, you need to upgrade this Addon and restart the cluster. Otherwise, the cluster created in KubeBlocks v0.8.x cannot be used in v0.9.x.
If the Addon you want to use is clickhouse/milvus/elasticsearch/llm, you need to upgrade KubeBlocks first and then upgrade this Addon. Otherwise, these Addons cannot be used in KubeBlocks v0.9.x normally.

# Add Helm repo
helm repo add kubeblocks-addons https://apecloud.github.io/helm-charts

# If github is not accessible or the network is very slow for you, please use following repo instead
helm repo add kubeblocks-addons https://jihulab.com/api/v4/projects/150246/packages/helm/stable

# Update helm repo
helm repo update

# Search the available Addon versions
helm search repo kubeblocks-addons/{addon-name} --versions --devel

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

# View the Addon index list
kbcli addon index list

# Update one index and the default index is kubeblocks
kbcli addon index update kubeblocks

# Search available Addon versions
kbcli addon search {addon-name}

# Install an Addon
kbcli addon install {addon-name} --version x.y.z

# Upgrade this Addon to a specified version
kbcli addon upgrade {addon-name} --version x.y.z

# Force to upgrade to a specified version
kbcli addon upgrade {addon-name} --version x.y.z --force

# View the available Addon versions
kbcli addon list | grep {addon-name}

Upgrade to KubeBlocks v0.9.x

NOTE

Before upgrading, check your current KubeBlocks version:

Run helm -n kb-system list | grep kubeblocks or kbcli version.
For upgrading to different versions:
- For v0.9.2 and v0.9.1, follow this upgrade tutorial, replacing the version number with v0.9.2 or v0.9.1 respectively.
- v0.9.0 upgrade guide
- v0.8.x upgrade guide.
Installing the latest version is recommended for better performance and features.

Compatibility

If you are upgrading from v0.8 to v0.9, it's recommended to enable webhook to ensure the availability.

Upgrade from KubeBlocks v0.9.x

View Addon and check whether the "helm.sh/resource-policy": "keep" annotation exists.

KubeBlocks streamlines the default installed engines. Add the "helm.sh/resource-policy": "keep" annotation to avoid deleting Addon resources that are already in use during the upgrade.

Check whether the "helm.sh/resource-policy": "keep" annotation is added.
```
kubectl get addon -o json | jq '.items[] | {name: .metadata.name, resource_policy: .metadata.annotations["helm.sh/resource-policy"]}'
```
If the annotation doesn't exist, run the command below to add it. You can replace -l app.kubernetes.io/name=kubeblocks with your actual filter name.
```
kubectl annotate addons.extensions.kubeblocks.io -l app.kubernetes.io/name=kubeblocks helm.sh/resource-policy=keep
```
Install CRD.

To reduce the size of Helm chart, KubeBlocks v0.8 removes CRD from the Helm chart. Before upgrading, you need to install CRD.
```
kubectl replace -f https://github.com/apecloud/kubeblocks/releases/download/v0.9.3/kubeblocks_crds.yaml
```
Upgrade KubeBlocks.
```
helm -n kb-system upgrade kubeblocks kubeblocks/kubeblocks --version 0.9.3 --set crd.enabled=false
```
Upgrading from v0.9.0/v0.9.1/v0.9.2 to v0.9.3 doesn't include API change, so you can set --set crd.enabled=false to skip the API upgrade task.
WARNING
To avoid affecting existing database clusters, when upgrading to KubeBlocks v0.9.3, the versions of already-installed Addons will not be upgraded by default. If you want to upgrade the Addons to the versions built into KubeBlocks v0.9.3, execute the following command. Note that this may restart existing clusters and affect availability. Please proceed with caution.
```
helm -n kb-system upgrade kubeblocks kubeblocks/kubeblocks --version 0.9.3 \
  --set upgradeAddons=true \
  --set crd.enabled=false
```

Download kbcli v0.9.3.

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

Upgrade KubeBlocks.
```
kbcli kb upgrade --version 0.9.3
```
WARNING
To avoid affecting existing database clusters, when upgrading to KubeBlocks v0.9.3, the versions of already-installed Addons will not be upgraded by default. If you want to upgrade the Addons to the versions built into KubeBlocks v0.9.3, execute the following command. Note that this may restart existing clusters and affect availability. Please proceed with caution.
```
kbcli kb upgrade --version 0.9.3 --set upgradeAddons=true
```
kbcli will automatically add the annotation "helm.sh/resource-policy": "keep" to ensure that existing Addons are not deleted during the upgrade.

Upgrade from KubeBlocks v0.8.x

View Addon and check whether the "helm.sh/resource-policy": "keep" annotation exists.

KubeBlocks streamlines the default installed engines. Add the "helm.sh/resource-policy": "keep" annotation to avoid deleting Addon resources that are already in use during the upgrade.

Check whether the "helm.sh/resource-policy": "keep" annotation is added.
```
kubectl get addon -o json | jq '.items[] | {name: .metadata.name, resource_policy: .metadata.annotations["helm.sh/resource-policy"]}'
```
If the annotation doesn't exists, run the command below to add it. You can replace -l app.kubernetes.io/name=kubeblocks with your actual filter name.
```
kubectl annotate addons.extensions.kubeblocks.io -l app.kubernetes.io/name=kubeblocks helm.sh/resource-policy=keep
```

Delete the incompatible OpsDefinition.

kubectl delete opsdefinitions.apps.kubeblocks.io kafka-quota kafka-topic kafka-user-acl switchover

Install CRD.

To reduce the size of Helm chart, KubeBlocks v0.8 removed CRD from the Helm chart and changed the group of StorageProvider. Before upgrading, you need to install StorageProvider CRD first.

If the network is slow, it's recommended to download the CRD YAML file on your localhost before further operations.
```
kubectl create -f https://github.com/apecloud/kubeblocks/releases/download/v0.9.3/dataprotection.kubeblocks.io_storageproviders.yaml
```
Upgrade KubeBlocks.

Here are some options that need your attention before the upgrade.
- Setting admissionWebhooks.enabled=true enables the webhook, supporting the multi-version conversion of the ConfigConstraint API.
- Setting admissionWebhooks.ignoreReplicasCheck=true enables the webhook by default only when KubeBlocks is deployed with 3 replicas. If only a single replica is deployed, you can configure this variable to bypass the check.
- If the KubeBlocks you are running uses the image registry starting with infracreate-registry, it is recommended to explicitly configure the image registry during the upgrade.
```
helm repo add kubeblocks https://apecloud.github.io/helm-charts

helm repo update kubeblocks

helm -n kb-system upgrade kubeblocks kubeblocks/kubeblocks --version 0.9.3 \
  --set admissionWebhooks.enabled=true \
  --set admissionWebhooks.ignoreReplicasCheck=true
```
WARNING
To avoid affecting existing database clusters, when upgrading to KubeBlocks v0.9.3, the versions of already-installed Addons will not be upgraded by default. If you want to upgrade the Addons to the versions built into KubeBlocks v0.9.3, execute the following command. Note that this may restart existing clusters and affect availability. Please proceed with caution.
```
helm -n kb-system upgrade kubeblocks kubeblocks/kubeblocks --version 0.9.3 \
  --set upgradeAddons=true \
  --set admissionWebhooks.enabled=true \
  --set admissionWebhooks.ignoreReplicasCheck=true
```

Download kbcli v0.9.3.

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

Upgrade KubeBlocks.

Check the kbcli version and make sure you're using kbcli v0.9.3.
```
kbcli version
```
Here are some options that need your attention before the upgrade.
- Setting admissionWebhooks.enabled=true enables the webhook, supporting the multi-version conversion of the ConfigConstraint API.
- Setting admissionWebhooks.ignoreReplicasCheck=true enables the webhook by default only when KubeBlocks is deployed with 3 replicas. If only a single replica is deployed, you can configure this variable to bypass the check.
- If the KubeBlocks you are running uses the image registry starting with infracreate-registry, it is recommended to explicitly configure the image registry during the upgrade.
```
kbcli kb upgrade --version 0.9.3 \
  --set admissionWebhooks.enabled=true \
  --set admissionWebhooks.ignoreReplicasCheck=true
```
WARNING
To avoid affecting existing database clusters, when upgrading to KubeBlocks v0.9.3, the versions of already-installed Addons will not be upgraded by default. If you want to upgrade the Addons to the versions built into KubeBlocks v0.9.3, execute the following command. Note that this may restart existing clusters and affect availability. Please proceed with caution.
```
kbcli kb upgrade --version 0.9.3 \
  --set upgradeAddons=true \
  --set admissionWebhooks.enabled=true \
  --set admissionWebhooks.ignoreReplicasCheck=true
```
kbcli will automatically add the annotation "helm.sh/resource-policy": "keep" to ensure that existing Addons are not deleted during the upgrade.

Upgrade Addons

If you didn't specify upgradeAddons as true or your Addon is not included in the default installed Addons, you can upgrade Addons by running the commands provided below to use the v0.9.x API.

NOTE

If the Addon you want to upgrade is mysql, you need to upgrade this Addon and restart the cluster. Otherwise, the cluster created in KubeBlocks v0.8.x cannot be used in v0.9.x.
If the Addon you want to use is clickhouse/milvus/elasticsearch/llm, you need to upgrade KubeBlocks first and then upgrade this Addon. Otherwise, these Addons cannot be used in KubeBlocks v0.9.x normally.

# Add Helm repo
helm repo add kubeblocks-addons https://apecloud.github.io/helm-charts

# If github is not accessible or the network is very slow for you, please use following repo instead
helm repo add kubeblocks-addons https://jihulab.com/api/v4/projects/150246/packages/helm/stable

# Update helm repo
helm repo update

# Search the available Addon versions
helm search repo kubeblocks-addons/{addon-name} --versions --devel

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

# View the Addon index list
kbcli addon index list

# Update one index and the default index is kubeblocks
kbcli addon index update kubeblocks

# Search available Addon versions
kbcli addon search {addon-name}

# Install an Addon
kbcli addon install {addon-name} --version x.y.z

# Upgrade this Addon to a specified version
kbcli addon upgrade {addon-name} --version x.y.z

# Force to upgrade to a specified version
kbcli addon upgrade {addon-name} --version x.y.z --force

# View the available Addon versions
kbcli addon list | grep {addon-name}