Kubeblocks Create Cluster

Create a Database Cluster on KubeBlocks

Overview

KubeBlocks uses the Cluster CR (Custom Resource) to declaratively create and manage database clusters. A single YAML template works across all supported addons — MySQL, PostgreSQL, Redis, MongoDB, Kafka, and more.

Official docs: https://kubeblocks.io/docs/preview/user_docs/kubeblocks-for-mysql/cluster-management/create-and-connect-a-mysql-cluster Full doc index: https://kubeblocks.io/llms-full.txt

Prerequisites

• A running Kubernetes cluster with KubeBlocks installed. If not, use:
  • create-local-k8s-cluster to create a local cluster
  • install-kubeblocks to install KubeBlocks
• The target addon must be installed (check with helm list -n kb-system | grep kb-addon)

Workflow

- [ ] Step 1: Determine addon and topology
- [ ] Step 2: Apply Cluster CR
- [ ] Step 3: Verify cluster is running
- [ ] Step 4: Connect to the cluster

Step 1: Determine Addon and Topology

Ask the user which database engine they need. Use the table below to select the correct clusterDef, topology, and componentSpecs values.

Common Addon Quick Reference

Note: Topologies and versions may change across addon releases. Run kubectl get clusterdefinitions and kubectl get componentversions to see what is available in your environment.

If the user needs detailed topology options or advanced configurations for a specific addon, refer them to the addon-specific skills (e.g., kubeblocks-addon-mysql, kubeblocks-addon-postgresql, kubeblocks-addon-redis, kubeblocks-addon-mongodb, kubeblocks-addon-kafka) when available.

Step 2: Apply Cluster CR

Universal Cluster Template

Replace the placeholder values according to the addon table above:

apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
  name: <cluster-name>
  namespace: <namespace>
spec:
  clusterDef: <addon>
  topology: <topology>
  terminationPolicy: Delete
  componentSpecs:
    - name: <component>
      serviceVersion: "<version>"
      replicas: <N>
      resources:
        limits:
          cpu: "0.5"
          memory: "0.5Gi"
        requests:
          cpu: "0.5"
          memory: "0.5Gi"
      volumeClaimTemplates:
        - name: data
          spec:
            accessModes: [ReadWriteOnce]
            resources:
              requests:
                storage: 20Gi

Example: Create a MySQL Cluster (3 replicas)

apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
  name: mysql-cluster
  namespace: default
spec:
  clusterDef: apecloud-mysql
  topology: apecloud-mysql
  terminationPolicy: Delete
  componentSpecs:
    - name: mysql
      serviceVersion: "8.0.30"
      replicas: 3
      resources:
        limits:
          cpu: "0.5"
          memory: "0.5Gi"
        requests:
          cpu: "0.5"
          memory: "0.5Gi"
      volumeClaimTemplates:
        - name: data
          spec:
            accessModes: [ReadWriteOnce]
            resources:
              requests:
                storage: 20Gi

Example: Create a PostgreSQL Cluster (2 replicas)

apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
  name: pg-cluster
  namespace: default
spec:
  clusterDef: postgresql
  topology: postgresql
  terminationPolicy: Delete
  componentSpecs:
    - name: postgresql
      serviceVersion: "14.8.0"
      replicas: 2
      resources:
        limits:
          cpu: "0.5"
          memory: "0.5Gi"
        requests:
          cpu: "0.5"
          memory: "0.5Gi"
      volumeClaimTemplates:
        - name: data
          spec:
            accessModes: [ReadWriteOnce]
            resources:
              requests:
                storage: 20Gi

Example: Create a Redis Cluster (2 shards)

apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
  name: redis-cluster
  namespace: default
spec:
  clusterDef: redis
  topology: redis-cluster
  terminationPolicy: Delete
  componentSpecs:
    - name: redis
      serviceVersion: "7.2.4"
      replicas: 2
      resources:
        limits:
          cpu: "0.5"
          memory: "0.5Gi"
        requests:
          cpu: "0.5"
          memory: "0.5Gi"
      volumeClaimTemplates:
        - name: data
          spec:
            accessModes: [ReadWriteOnce]
            resources:
              requests:
                storage: 20Gi

Apply the YAML

Save the YAML to a file (e.g., cluster.yaml) and apply.

Before applying, validate with dry-run:

kubectl apply -f cluster.yaml --dry-run=server

If dry-run reports errors, fix the YAML before proceeding.

kubectl apply -f cluster.yaml

Or apply inline. Before applying, validate with dry-run:

kubectl apply -f - --dry-run=server <<'EOF'
# paste YAML here
EOF

If dry-run reports errors, fix the YAML before proceeding.

kubectl apply -f - <<'EOF'
# paste YAML here
EOF

Step 3: Verify Cluster Is Running

Watch the cluster status until it becomes Running:

kubectl get cluster <cluster-name> -n <namespace> -w

Success condition: .status.phase = Running | Typical: 1-5min | If stuck >10min: kubectl describe cluster <cluster-name> -n <namespace>

Check all pods are Ready:

kubectl get pods -n <namespace> -l app.kubernetes.io/instance=<cluster-name>

Expected output (MySQL 3-replica example):

NAME                    READY   STATUS    RESTARTS   AGE
mysql-cluster-mysql-0   4/4     Running   0          2m
mysql-cluster-mysql-1   4/4     Running   0          90s
mysql-cluster-mysql-2   4/4     Running   0          60s

If pods are not Running, check events:

kubectl describe cluster <cluster-name> -n <namespace>
kubectl get events -n <namespace> --sort-by='.lastTimestamp' | grep <cluster-name>

Step 4: Connect to the Cluster

Get Connection Credentials

KubeBlocks auto-generates a Secret with the connection credentials:

kubectl get secret <cluster-name>-conn-credential -n <namespace> -o jsonpath='{.data.username}' | base64 -d
kubectl get secret <cluster-name>-conn-credential -n <namespace> -o jsonpath='{.data.password}' | base64 -d

Port-Forward for Local Access

# MySQL
kubectl port-forward svc/<cluster-name>-mysql -n <namespace> 3306:3306

# PostgreSQL
kubectl port-forward svc/<cluster-name>-postgresql -n <namespace> 5432:5432

# Redis
kubectl port-forward svc/<cluster-name>-redis -n <namespace> 6379:6379

# MongoDB
kubectl port-forward svc/<cluster-name>-mongodb -n <namespace> 27017:27017

Decision Tree

User wants to create a cluster
├── Which addon?
│   ├── MySQL       → clusterDef: apecloud-mysql or mysql
│   ├── PostgreSQL  → clusterDef: postgresql
│   ├── Redis       → clusterDef: redis
│   ├── MongoDB     → clusterDef: mongodb
│   ├── Kafka       → clusterDef: kafka
│   └── Other       → kubectl get clusterdefinitions
├── How many replicas?
│   ├── Dev/test    → 1 replica, terminationPolicy: Delete
│   └── Production  → 3+ replicas, terminationPolicy: DoNotTerminate
└── Resource sizing?
    ├── Dev/test    → 0.5 CPU, 0.5Gi memory, 20Gi storage
    └── Production  → 2+ CPU, 4Gi+ memory, 100Gi+ storage

terminationPolicy

Important: For production clusters, always use DoNotTerminate to prevent accidental deletion.

Troubleshooting

Cluster stuck in Creating or Updating:

• Check if the addon is installed: helm list -n kb-system | grep kb-addon
• Check pod events: kubectl describe pod <pod-name> -n <namespace>
• Check resource availability: kubectl describe nodes

Image pull errors:

• Verify image registry. If in China, ensure the addon uses the Aliyun mirror registry.

Insufficient resources:

• Reduce resources.requests or add more nodes to the cluster.

For general agent safety conventions (dry-run, status confirmation, production protection), see safety-patterns.md.

Reference

For detailed Cluster CR field descriptions and more addon examples, see reference.md.