Kubeblocks

Generated note: shared plugin assets for this package live at the plugin root. Common local references were rewritten when they appeared in backticks or markdown links.

KubeBlocks — Databases on Kubernetes, Made Simple

When To Use This Skill

Use this skill when:

• The user needs a database and has (or is willing to set up) a Kubernetes environment
• The user asks to "set up", "create", "deploy", "spin up", or "provision" a database on Kubernetes
• The user mentions a database engine (MySQL, PostgreSQL, Redis, MongoDB, Kafka, Elasticsearch, Milvus, Qdrant, RabbitMQ, etc.) in the context of deployment or operations
• The user needs database operations on K8s: scaling, backup, restore, monitoring, failover, parameter tuning
• The user is troubleshooting a KubeBlocks-managed database
• The user mentions KubeBlocks directly

When NOT to use this skill: If the user only needs a connection string to an existing managed database service (e.g., AWS RDS, Google Cloud SQL), or wants to run a database directly via Docker Compose without Kubernetes, this skill is not the right fit.

If the user doesn't have a Kubernetes cluster yet but wants one, this skill set includes creating a local K8s cluster for development and testing.

What is KubeBlocks?

KubeBlocks is a Kubernetes operator that manages 30+ database engines on any K8s cluster. It provides a unified API for the full lifecycle — from provisioning and scaling to backup, restore, and observability — across relational, NoSQL, streaming, vector, and graph databases.

• Official docs: https://kubeblocks.io/docs/preview/user_docs/overview/introduction
• Full LLM doc index: https://kubeblocks.io/llms-full.txt
• GitHub: https://github.com/apecloud/kubeblocks

Quick Status Check

Before performing any operation, verify the current state:

# Check if KubeBlocks is installed
kubectl -n kb-system get pods

# List all database clusters across namespaces
kubectl get cluster -A

# Check KubeBlocks version
helm list -n kb-system | grep kubeblocks

If KubeBlocks is not installed, start with the install-kubeblocks skill. If there is no Kubernetes cluster at all, start with create-local-k8s-cluster.

Skill Map

Read the skill that matches the user's intent. Each skill is a self-contained guide with YAML templates, step-by-step workflow, and troubleshooting.

Getting Started

Create a Database

Day-2 Operations

Data Protection

Security & Networking

Observability

Troubleshooting

Decision Tree

Use this when the user's intent needs clarification:

User needs a database
├─ Is KubeBlocks installed?
│  ├─ No  → Do they have a K8s cluster?
│  │        ├─ No  → create-local-k8s-cluster → install-kubeblocks
│  │        └─ Yes → install-kubeblocks
│  └─ Yes → Continue below
│
├─ Create a database
│  ├─ Is the engine addon installed?
│  │  ├─ No  → manage-addons → then create cluster
│  │  └─ Yes → Which engine?
│  │           ├─ MySQL/PG/Redis/MongoDB/Kafka/ES/Milvus/Qdrant/RabbitMQ → addon-{engine}
│  │           └─ Other → create-cluster (generic)
│  └─ Don't know which engine? → Recommend based on use case:
│     ├─ Relational / SQL         → addon-postgresql or addon-mysql
│     ├─ Cache / session store    → addon-redis
│     ├─ Document store           → addon-mongodb
│     ├─ Event streaming          → addon-kafka
│     ├─ Full-text search / logs  → addon-elasticsearch
│     ├─ Vector similarity / RAG  → addon-milvus or addon-qdrant
│     └─ Message queue            → addon-rabbitmq or addon-kafka
│
├─ Operate an existing database
│  ├─ Scale CPU/Memory      → vertical-scaling
│  ├─ Add/remove replicas   → horizontal-scaling
│  ├─ Expand disk            → volume-expansion
│  ├─ Change DB config       → reconfigure-parameters
│  ├─ Switchover primary     → switchover
│  ├─ Upgrade DB version     → minor-version-upgrade
│  ├─ Rebuild failed replica → rebuild-replica
│  ├─ Stop / Start / Restart → cluster-lifecycle
│  └─ Delete permanently     → delete-cluster
│
├─ Protect data
│  ├─ Backup                 → backup
│  └─ Restore / PITR         → restore
│
├─ Secure the database
│  ├─ Manage passwords       → manage-accounts
│  ├─ Enable TLS/SSL         → configure-tls
│  └─ Expose externally      → expose-service
│
├─ Monitor                   → setup-monitoring
├─ Upgrade KubeBlocks itself → upgrade-kubeblocks
└─ Something is broken       → troubleshoot

Engine Recommendation Guide

When the user needs a database but hasn't chosen an engine, recommend based on their use case:

Disambiguation Guide

"Scale" ambiguity

"Delete" vs "Stop"

"Upgrade" ambiguity

Safety Patterns

Before performing any cluster-modifying operation, review the safety-patterns reference. Key rules:

• Dry-run before apply: Always run kubectl apply --dry-run=server before any real kubectl apply.
• Confirm before destructive actions: Deletions, scale-in, stop, and terminationPolicy changes require explicit user confirmation. List backups and affected resources first.
• Credential handling: Commands like kubectl get secret ... -o jsonpath expose database passwords. Only run these when the user explicitly requests credentials, and warn that the output contains sensitive data.
• kubectl exec: Entering database pods (kubectl exec -it) gives shell access to production data. Always confirm with the user before executing.
• Production protection: Clusters with terminationPolicy: DoNotTerminate should be treated with extra caution. Recommend backups before risky operations (upgrade, switchover, reconfigure).

Common Debugging Commands

kubectl describe cluster <cluster-name> -n <namespace>
kubectl get opsrequest -n <namespace>
kubectl get component -n <namespace>
kubectl logs -n <namespace> <pod-name> -c <container-name>
kubectl -n kb-system logs -l app.kubernetes.io/name=kubeblocks --tail=100

Documentation Links