apecloud/kubeblocks-install

Install KubeBlocks Operator

Overview

KubeBlocks is a Kubernetes operator for managing databases (MySQL, PostgreSQL, Redis, MongoDB, Kafka, etc.). This skill guides installation of the KubeBlocks operator onto any Kubernetes cluster.

Official docs: https://kubeblocks.io/docs/preview/user_docs/overview/install-kubeblocks Full doc index: https://kubeblocks.io/llms-full.txt

Workflow

Copy this checklist and track progress:

- [ ] Step 1: Check prerequisites
- [ ] Step 2: Determine version
- [ ] Step 3: Detect network environment
- [ ] Step 4: Install CRDs
- [ ] Step 5: Install KubeBlocks via Helm
- [ ] Step 6: Verify installation

Step 1: Check Prerequisites

This skill requires an existing Kubernetes cluster. If the user does not have one, point them to the create-local-k8s-cluster skill first.

Run these checks and install any missing tools automatically:

1a: kubectl

kubectl version --client 2>/dev/null

If the command fails (not found), install it:

# macOS
brew install kubectl

# Linux (amd64)
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
chmod +x kubectl && sudo mv kubectl /usr/local/bin/

# Linux (arm64)
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/arm64/kubectl"
chmod +x kubectl && sudo mv kubectl /usr/local/bin/

1b: Helm (v3+)

helm version --short 2>/dev/null

If the command fails (not found), install it:

# macOS
brew install helm

# Linux (script, works on amd64/arm64)
curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

1c: Verify cluster access

kubectl get nodes

If this fails, the user has no accessible Kubernetes cluster. Stop here and tell the user:

• For local testing, use the create-local-k8s-cluster skill
• For production, ensure kubeconfig is properly configured (~/.kube/config or $KUBECONFIG)

Resource requirements (minimum):

• Control Plane: 1 node, 4 cores, 4GB RAM, 50GB storage
• Data Plane: 2-3 nodes, 2 cores, 4GB RAM, 50GB storage each

Step 2: Determine Version

Ask the user if they want a specific version. If not specified, fetch the latest stable release:

# Get latest stable version
curl -s https://api.github.com/repos/apecloud/kubeblocks/releases/latest | grep '"tag_name"' | cut -d'"' -f4

To list all available versions:

# Via GitHub API
curl -s https://api.github.com/repos/apecloud/kubeblocks/tags | grep '"name"' | head -20 | cut -d'"' -f4

# Or via Helm (after adding repo)
helm search repo kubeblocks/kubeblocks --versions

Known stable releases: v1.0.2, v1.0.1, v1.0.0, v0.9.5, v0.9.4, v0.9.3, v0.9.2, v0.9.1, v0.9.0

Always tell the user which version is being installed.

Step 3: Detect Network Environment

Determine which image registry to use.

Default (global access / docker.io available):

• registry: docker.io
• namespace: apecloud

China mainland (docker.io blocked/slow):

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

How to detect: Ask the user, or run a quick test:

# Test docker.io connectivity (timeout 5s)
curl -sS --connect-timeout 5 https://registry-1.docker.io/v2/ > /dev/null 2>&1 && echo "docker.io: reachable" || echo "docker.io: unreachable, use China mirror"

Step 4: Install CRDs

# Replace {VERSION} with the chosen version, e.g. v1.0.2
kubectl create -f https://github.com/apecloud/kubeblocks/releases/download/{VERSION}/kubeblocks_crds.yaml

For K8s <= 1.23, add --validate=false:

kubectl create -f https://github.com/apecloud/kubeblocks/releases/download/{VERSION}/kubeblocks_crds.yaml --validate=false

Step 5: Install KubeBlocks via Helm

5a: Add Helm Repo

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

5b: Install

Global network (docker.io accessible):

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

China mainland network:

helm install kubeblocks kubeblocks/kubeblocks \
  --namespace kb-system --create-namespace \
  --version {VERSION} \
  --set image.registry=apecloud-registry.cn-zhangjiakou.cr.aliyuncs.com \
  --set dataProtection.image.registry=apecloud-registry.cn-zhangjiakou.cr.aliyuncs.com \
  --set addonChartsImage.registry=apecloud-registry.cn-zhangjiakou.cr.aliyuncs.com

Common Extra Options

# Custom tolerations (e.g. for dedicated control-plane nodes)
--set-json 'tolerations=[{"key":"control-plane-taint","operator":"Equal","effect":"NoSchedule","value":"true"}]'

# Skip auto-installing default addons (lightweight install)
--set autoInstalledAddons="{}"

# Enable in-place vertical scaling
--set featureGates.inPlacePodVerticalScaling.enabled=true

For the full options reference, see reference.md.

Step 6: Verify Installation

# Check pods in kb-system namespace
kubectl -n kb-system get pods

# Expected: kubeblocks and kubeblocks-dataprotection pods in Running state
# Example output:
# NAME                                             READY   STATUS    RESTARTS   AGE
# kubeblocks-7cf7745685-ddlwk                      1/1     Running   0          2m
# kubeblocks-dataprotection-95fbc79cc-b544l        1/1     Running   0          2m

If pods are not Running, check events:

kubectl -n kb-system describe pods
kubectl -n kb-system get events --sort-by='.lastTimestamp'

Next Step After Install

Installation success does not mean the environment is ready for database rollout.

Before creating the first MySQL / PostgreSQL / Redis / MongoDB / Kafka cluster, run kubeblocks-preflight to decide:

• storage class
• topology risk
• recommended engine-entry path
• observability path
• demo vs production sizing defaults

Troubleshooting

CRD install fails with x-kubernetes-validations error:

• K8s version <= 1.23. Add --validate=false to the kubectl create command.

Image pull errors:

• Check registry accessibility. Switch to the China mainland mirror if in China.
• Verify the registry setting: helm get values kubeblocks -n kb-system

Helm install timeout:

• Check node resources: kubectl describe nodes
• For resource-constrained environments, skip default addons: --set autoInstalledAddons="{}"

KubeBlocks already installed:

• Check existing installation: helm list -n kb-system | grep kubeblocks
• To upgrade: helm upgrade kubeblocks kubeblocks/kubeblocks --namespace kb-system --version {VERSION}

Uninstall

See reference.md for detailed uninstall instructions.

Quick uninstall:

# Delete all clusters and backups first
kubectl get cluster -A
kubectl delete cluster --all -A

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

# Uninstall KubeBlocks
helm uninstall kubeblocks --namespace kb-system

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