KubeBlocks

This guide covers KubeBlocks deployment on existing Kubernetes clusters. Choose your preferred installation method:

Helm (recommended for production)
kbcli (simplified CLI experience)

Prerequisites

Resource Requirements

Component	Database	Recommendation
Control Plane	-	1 node (4 cores, 4GB RAM, 50GB storage)
Data Plane	MySQL	2 nodes (2 cores, 4GB RAM, 50GB storage)
	PostgreSQL	2 nodes (2 cores, 4GB RAM, 50GB storage)
	Redis	2 nodes (2 cores, 4GB RAM, 50GB storage)
	MongoDB	3 nodes (2 cores, 4GB RAM, 50GB storage)

Control Plane: Nodes running KubeBlocks components
Data Plane: Nodes hosting database instances

System Requirements

Before installation, verify your environment meets these requirements:

Kubernetes cluster (v1.21+ recommended) - create test cluster if needed
kubectl v1.21+ installed and configured with cluster access
Helm installed (installation guide)
Snapshot Controller installed (installation guide)

Install KubeBlocks

# Step 1: Install CRDs
kubectl create -f https://github.com/apecloud/kubeblocks/releases/download/v1.0.0/kubeblocks_crds.yaml

# Step 2: Configure Helm Repository
helm repo add kubeblocks https://apecloud.github.io/helm-charts
helm repo update

# Step 3: Deploy KubeBlocks
helm install kubeblocks kubeblocks/kubeblocks --namespace kb-system --create-namespace --version=v1.0.0

Need a different version?

For other versions, you can find available releases on KubeBlocks Releases or query using:

# Get latest stable release
curl -s https://api.github.com/repos/apecloud/kubeblocks/releases/latest | jq -r '.tag_name'

# Get all releases (including pre-releases)
curl -s https://api.github.com/repos/apecloud/kubeblocks/tags | jq -r '.[0].name'

Before You Begin:

Install KubeBlocks CLI
Ensure kubectl is configured with cluster access

kbcli kubeblocks install --version=v1.0.0 --create-namespace

Need a different version?

List available versions or find other releases:

# List stable releases
kbcli kubeblocks list-versions

# List all releases (including pre-releases)
kbcli kb list-versions --devel --limit=100

Or browse all releases on KubeBlocks Releases.

NOTE

Version Compatibility

KubeBlocks requires matching major versions between kbcli and the installed release:

Compatible: kbcli v1.0.0 with KubeBlocks v1.0.0
Incompatible: kbcli v0.9.0 with KubeBlocks v1.0.0

Mismatched major versions may cause unexpected behavior or errors.

By default, KubeBlocks installs in the kb-system namespace. To specify a different namespace:

kbcli kubeblocks install --version=v1.0.0 --create-namespace --namespace my-namespace

💡 Remember to replace my-namespace with your desired namespace name.

Verify Installation

Run the following command to check whether KubeBlocks is installed successfully.

kubectl -n kb-system get pods

Expected Output:

If the KubeBlocks Workloads are all ready, KubeBlocks has been installed successfully.

NAME                                             READY   STATUS    RESTARTS       AGE
kubeblocks-7cf7745685-ddlwk                      1/1     Running   0              4m39s
kubeblocks-dataprotection-95fbc79cc-b544l        1/1     Running   0              4m39s

kbcli kubeblocks status

Expected Output:

If the KubeBlocks Workloads are all ready, KubeBlocks has been installed successfully.

KubeBlocks is deployed in namespace: kb-system,version: v1.0.0

Kubernetes Cluster:
VERSION   PROVIDER   REGION   AVAILABLE ZONES
v1.29.2   Kind

KubeBlocks Workloads:
NAMESPACE   KIND         NAME                        READY PODS   CPU(CORES)   MEMORY(BYTES)   CREATED-AT
kb-system   Deployment   kubeblocks                  1/1          N/A          N/A             May 26,2025 13:53 UTC+0800
kb-system   Deployment   kubeblocks-dataprotection   1/1          N/A          N/A             May 26,2025 13:53 UTC+0800

KubeBlocks Addons:
NAME             STATUS    TYPE   PROVIDER
apecloud-mysql   Enabled   Helm   N/A
etcd             Enabled   Helm   N/A
kafka            Enabled   Helm   N/A

Advanced Configuration

Custom Image Registry

Specify image repository by specifying the following parameters.

helm install kubeblocks kubeblocks/kubeblocks --namespace kb-system --create-namespace \
--version v1.0.0 \
--set image.registry=docker.io \
--set dataProtection.image.registry=docker.io \
--set addonChartsImage.registry=docker.io

kbcli kubeblocks upgrade --version v1.0.0 \
--set image.registry=docker.io \
--set dataProtection.image.registry=docker.io \
--set addonChartsImage.registry=docker.io

Here is an introduction to the flags in the above command.

--set image.registry specifies the KubeBlocks image registry.
--set dataProtection.image.registry specifies the KubeBlocks-DataProtection image registry.
--set addonChartsImage.registry specifies Addon Charts image registry.

If you cannot access docker.io please use following registry and namespace:

registry: apecloud-registry.cn-zhangjiakou.cr.aliyuncs.com
namespace: apecloud

Specify tolerations

If you want to install KubeBlocks with custom tolerations, you can use the following command:

helm install kubeblocks kubeblocks/kubeblocks --namespace kb-system --create-namespace \
--version v1.0.0 \
--set-json 'tolerations=[ { "key": "control-plane-taint", "operator": "Equal", "effect": "NoSchedule", "value": "true" } ]' \
--set-json 'dataPlane.tolerations=[{ "key": "data-plane-taint", "operator": "Equal", "effect": "NoSchedule", "value": "true"}]'

kbcli kubeblocks install --version v1.0.0 --create-namespace \
--set image.registry=docker.io \
--set dataProtection.image.registry=docker.io \
--set addonChartsImage.registry=docker.io

Skip Addon Auto Installation

helm install kubeblocks kubeblocks/kubeblocks --namespace kb-system --create-namespace \
--version v1.0.0 \
--set autoInstalledAddons="{}"

Enable In-place Vertical Scaling

To enable in-place vertical scaling for KubeBlocks, set the feature gate parameter during installation or upgrade:

featureGates.inPlacePodVerticalScaling.enabled=true

Installation

helm install kubeblocks kubeblocks/kubeblocks \
  --namespace kb-system \
  --create-namespace \
  --version v1.0.0 \
  --set featureGates.inPlacePodVerticalScaling.enabled=true

Upgrade

helm upgrade kubeblocks kubeblocks/kubeblocks \
  --namespace kb-system \
  --version v1.0.0 \
  --set featureGates.inPlacePodVerticalScaling.enabled=true

Installation

kbcli kubeblocks install \
  --version=v1.0.0 \
  --create-namespace \
  --set featureGates.inPlacePodVerticalScaling.enabled=true

Upgrade

kbcli kubeblocks upgrade \
  --version=v1.0.0 \
  --set featureGates.inPlacePodVerticalScaling.enabled=true

Verification

After installation or upgrade, verify the feature gate is enabled:

kubectl -n kb-system get deployments.apps kubeblocks -oyaml | \
  yq '.spec' | \
  grep IN_PLACE_POD_VERTICAL_SCALING -A 1

The output should show:

- name: IN_PLACE_POD_VERTICAL_SCALING
  value: "true"

Uninstall KubeBlocks

NOTE

Please delete all clusters and backups before uninstalling KubeBlocks and kbcli.

# get cluster and backups
kubectl get cluster -A
kubectl get backup -A

# delete clusters and backups by by namespace
kubectl delete cluster <clusteName> -n <namespace>
kubectl delete backup <clusteName> -n <namespace>

List all addons

# list all addons
helm list -n kb-system | grep kb-addon

Uninstall all Addons.

helm list -n kb-system | grep kb-addon | awk '{print $1}' | xargs -I {} helm -n kb-system uninstall {}

While uninstalling, you will get messages like

Release "kb-addon-etcd" uninstalled
These resources were kept due to the resource policy:
[ConfigMap] kafka27-configuration-tpl-1.0.0
[ComponentDefinition] kafka-combine-1.0.0
[ComponentDefinition] kafka-controller-1.0.0
[ComponentDefinition] kafka-exporter-1.0.0
[ComponentDefinition] kafka27-broker-1.0.0
[ComponentDefinition] kafka-broker-1.0.0

Some resources are kept due to resource policy, then check and remove them all

Check remaining resources, such as ComponentDefinition, ConfigMaps for Configuration, and remove them all.

kubectl get componentdefinitions.apps.kubeblocks.io
kubectl get parametersdefinitions.parameters.kubeblocks.io
kubectl get configmap -n kb-system | grep configuration
kubectl get configmap -n kb-system | grep template

For example

kubectl delete componentdefinitions.apps.kubeblocks.io --all
kubectl delete parametersdefinitions.parameters.kubeblocks.io --all
kubectl get configmap -n kb-system | grep configuration  | awk '{print $1}' | xargs -I {} kubectl delete -n kb-system cm {}
kubectl get configmap -n kb-system | grep template| awk '{print $1}' | xargs -I {} kubectl delete -n kb-system cm {}

Delete Addon CRs

kubectl delete addon.extensions.kubeblocks.io --all

Verify all KubeBlocks resources are deleted

kubectl get crd  | grep kubeblocks.io | awk '{print $1}' | while read crd; do
  echo "Processing CRD: $crd"
  kubectl get "$crd" -o json | jq '.items[] | select(.metadata.finalizers != null) | .metadata.name' -r | while read resource; do
    echo "Custom Resource left: $resource in CRD: $crd"
  done
done

If the output shows any custom resource left, please remove them all.

Uninstall KubeBlocks

helm uninstall kubeblocks --namespace kb-system

Helm does not delete CRD objects. You can delete the ones KubeBlocks created with the following commands:

kubectl get crd -o name | grep kubeblocks.io | xargs kubectl delete

Verify all KubeBlocks resources are deleted

kubectl get crd  | grep kubeblocks.io | awk '{print $1}' | while read crd; do
  echo "Processing CRD: $crd"
  kubectl get "$crd" -o json | jq '.items[] | select(.metadata.finalizers != null) | .metadata.name' -r | while read resource; do
    echo "Custom Resource left: $resource in CRD: $crd"
  done
done

The output should be empty.

Check addon list

kbcli addon list | grep Enabled

set keepResource=false for all addons

# update addons values, to remove annotation 'helm.sh/resource-policy: keep' from ComponentDefinition/ConfigMaps
kbcli addon enable <addonName>  --set extra.keepResource=false

For example

kbcli addon enable apecloud-mysql   --set extra.keepResource=false
kbcli addon enable etcd             --set extra.keepResource=false
kbcli addon enable kafka            --set extra.keepResource=false
kbcli addon enable mongodb          --set extra.keepResource=false
kbcli addon enable mysql            --set extra.keepResource=false
kbcli addon enable postgresql       --set extra.keepResource=false
kbcli addon enable redis            --set extra.keepResource=false

disable all Addons

kbcli addon disable <addonName>

For example,

kbcli addon disable apecloud-mysql
kbcli addon disable etcd
kbcli addon disable kafka
kbcli addon disable mongodb
kbcli addon disable mysql
kbcli addon disable postgresql
kbcli addon disable redis

Verify all KubeBlocks resources are deleted

kubectl get crd  | grep kubeblocks.io | awk '{print $1}' | while read crd; do
  echo "Processing CRD: $crd"
  kubectl get "$crd" -o json | jq '.items[] | select(.metadata.finalizers != null) | .metadata.name' -r | while read resource; do
    echo "Custom Resource left: $resource in CRD: $crd"
  done
done

If the output shows some custom resource left, please remove them all.

uninstall KubeBlocks

kbcli kubeblocks uninstall

Verify all KubeBlocks resources are deleted

kubectl get crd  | grep kubeblocks.io | awk '{print $1}' | while read crd; do
  echo "Processing CRD: $crd"
  kubectl get "$crd" -o json | jq '.items[] | select(.metadata.finalizers != null) | .metadata.name' -r | while read resource; do
    echo "Custom Resource left: $resource in CRD: $crd"
  done
done

check there is no ConfigMap leftover:

kubectl get configmap -n kb-system