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

User Intent	Skill
Create a local K8s test cluster	create-local-k8s-cluster
Install KubeBlocks operator	install-kubeblocks
Install/manage database engine addons	manage-addons

Create a Database

User Intent	Skill
Create a MySQL cluster	addon-mysql
Create a PostgreSQL cluster	addon-postgresql
Create a Redis cluster	addon-redis
Create a MongoDB cluster	addon-mongodb
Create a Kafka cluster	addon-kafka
Create an Elasticsearch cluster	addon-elasticsearch
Create a Milvus (vector DB) cluster	addon-milvus
Create a Qdrant (vector DB) cluster	addon-qdrant
Create a RabbitMQ cluster	addon-rabbitmq
Create any other database (generic)	create-cluster
Delete a database cluster	delete-cluster

Day-2 Operations

User Intent	Skill
Stop / Start / Restart a cluster	cluster-lifecycle
Scale CPU / Memory (vertical)	vertical-scaling
Add / remove replicas or shards	horizontal-scaling
Expand storage volume	volume-expansion
Change database parameters	reconfigure-parameters
Primary / secondary switchover	switchover
Upgrade database engine version	minor-version-upgrade
Rebuild a failed replica	rebuild-replica
Upgrade KubeBlocks operator	upgrade-kubeblocks

Data Protection

User Intent	Skill
Backup cluster data	backup
Restore from backup / PITR	restore

Security & Networking

User Intent	Skill
Manage database passwords / accounts	manage-accounts
Configure TLS / mTLS encryption	configure-tls
Expose service externally (LoadBalancer/NodePort)	expose-service

Observability

User Intent	Skill
Setup monitoring (Prometheus/Grafana)	setup-monitoring

Troubleshooting

User Intent	Skill
Cluster not working, error, failed, stuck, CrashLoopBackOff	troubleshoot

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:

Use Case	Recommended Engine	Why
Web app backend, relational data, SQL	PostgreSQL	Most versatile, strong ecosystem
Legacy app compatibility, MySQL protocol	MySQL	Drop-in for MySQL-dependent apps
Caching, sessions, rate limiting	Redis	Sub-millisecond latency, simple API
Flexible schema, document storage	MongoDB	Schema-free, horizontal scaling
Event streaming, log pipelines	Kafka	High throughput, durable ordered streams
Full-text search, log analytics	Elasticsearch	Inverted index, powerful query DSL
AI embeddings, similarity search, RAG	Milvus or Qdrant	Purpose-built vector indexes
Task queues, pub/sub messaging	RabbitMQ	Flexible routing, multiple protocols

Disambiguation Guide

"Scale" ambiguity

User says	Skill
"scale up", "more CPU", "more memory", "resize"	vertical-scaling
"add replicas", "more nodes", "scale out", "add shards"	horizontal-scaling
"more disk", "more storage", "expand volume"	volume-expansion

"Delete" vs "Stop"

User says	Skill
"delete", "remove", "destroy", "drop" (permanent)	delete-cluster
"stop", "pause", "shut down" (temporary, keeps data)	cluster-lifecycle

"Upgrade" ambiguity

User says	Skill
"upgrade MySQL/PG version", "patch database"	minor-version-upgrade
"upgrade KubeBlocks", "update operator"	upgrade-kubeblocks

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

Resource	URL
Introduction	https://kubeblocks.io/docs/preview/user_docs/overview/introduction
Supported Addons	https://kubeblocks.io/docs/preview/user_docs/overview/supported-addons
Full LLM Index	https://kubeblocks.io/llms-full.txt
GitHub Repository	https://github.com/apecloud/kubeblocks
Releases	https://github.com/apecloud/kubeblocks/releases

kubeblocks-skills

Installation