KubeBlocks

The quickest way to try out KubeBlocks is to create a new Kubernetes cluster and install KubeBlocks using the playground. However, production environments are more complex, with applications running in different namespaces and with resource or permission limitations. This document explains how to deploy KubeBlocks on an existing Kubernetes cluster.

KubeBlocks is Kubernetes-native, you can use Helm or kubectl with a YAML file to install it. You can also use kbcli, an intuitive CLI tool, to install KubeBlocks.

Environment preparation

Resource Requirements

• Control Plane: nodes running KubeBlocks
• Data Plane: nodes running databases instances

Prerequisites

Before proceeding, verify your environment meets these requirements:

• A functional Kubernetes cluster (v1.21+ recommended). To try out KubeBlocks on your local host, you can create a test Kubernetes cluster
• kubectl v1.21+ installed and configured with cluster access
• Helm installed (installation guide)
• Snapshot Controller installed.

Install Snapshot Controller

Snapshot Controller is a Kubernetes component that manages CSI Volume Snapshots, enabling users to create, restore, and delete snapshots of Persistent Volumes (PVs). KubeBlocks DataProtection Controller uses the Snapshot Controller to create and manage snapshots for databases.

If your Kubernetes cluster does NOT have the following CRDs, you likely also do not have a snapshot controller deployed and you need to install one.

kubectl get crd volumesnapshotclasses.snapshot.storage.k8s.io
kubectl get crd volumesnapshots.snapshot.storage.k8s.io
kubectl get crd volumesnapshotcontents.snapshot.storage.k8s.io

# v8.2.0 is the latest version of the external-snapshotter, you can replace it with the version you need.
kubectl create -f https://raw.githubusercontent.com/kubernetes-csi/external-snapshotter/v8.2.0/client/config/crd/snapshot.storage.k8s.io_volumesnapshotclasses.yaml
kubectl create -f https://raw.githubusercontent.com/kubernetes-csi/external-snapshotter/v8.2.0/client/config/crd/snapshot.storage.k8s.io_volumesnapshots.yaml
kubectl create -f https://raw.githubusercontent.com/kubernetes-csi/external-snapshotter/v8.2.0/client/config/crd/snapshot.storage.k8s.io_volumesnapshotcontents.yaml

Step 1. Deploy Snapshot Controller

You can install the Snapshot Controller using Helm or kubectl. Here are the steps to install the Snapshot Controller using Helm.

helm repo add piraeus-charts https://piraeus.io/helm-charts/
helm repo update
# Update the namespace to an appropriate value for your environment (e.g. kb-system)
helm install snapshot-controller piraeus-charts/snapshot-controller -n kb-system --create-namespace

For more information, please refer to Snapshot Controller Configuration.

Step 2. Verify Snapshot Controller installation

Check if the snapshot-controller Pod is running:

kubectl get pods -n kb-system | grep snapshot-controller

snapshot-controller-xxxx-yyyy   1/1   Running   0   30s

If the pod is in a CrashLoopBackOff state, check logs:

kubectl logs -n kb-system deployment/snapshot-controller

Install KubeBlocks

# Replace <VERSION> with your selected version
kubectl create -f https://github.com/apecloud/kubeblocks/releases/download/<VERSION>/kubeblocks_crds.yaml

kubectl create -f https://github.com/apecloud/kubeblocks/releases/download/v1.0.0/kubeblocks_crds.yaml

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

helm install kubeblocks kubeblocks/kubeblocks --namespace kb-system --create-namespace --version=<VERSION>

kbcli kubeblocks list-versions

kbcli kb list-versions --devel --limit=100

kbcli kubeblocks install --version=<VERSION> --create-namespace

kbcli kubeblocks install --version=<VERSION> --namespace <NAMESPACE> --create-namespace

Verify KubeBlocks installation

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

kubectl -n kb-system get pods

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

KubeBlocks is deployed in namespace: kb-system,version: <VERSION>

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

KubeBlocks Configurations

Specify image repository

Specify image repository by specifying the following parameters.

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

kbcli kb upgrade --version <VERSION> \
--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 <VERSION> \
--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"}]'

Skip Addon Auto Installation

helm install kubeblocks kubeblocks/kubeblocks --namespace kb-system --create-namespace \
--version <VERSION> \
--set autoInstalledAddons="{}"

Feature Gate: Enable In-place Vertical-Scaling

helm install kubeblocks kubeblocks/kubeblocks --namespace kb-system --create-namespace \
--version <VERSION> \
--set featureGates.inPlacePodVerticalScaling.enabled=true

Uninstall KubeBlocks

# 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
helm list -n kb-system | grep kb-addon

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

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

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

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 {}

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

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

helm uninstall kubeblocks --namespace kb-system

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

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

kbcli addon list | grep Enabled

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

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

kbcli addon disable <addonName>

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

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

kbcli kubeblocks uninstall

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

kubectl get configmap -n kb-system