kubeblocks

name	kubeblocks
version	0.3.0
description	Route database work on Kubernetes to the right KubeBlocks skill. Use this as the top-level entrypoint when the user needs a database, database operations, or database observability on Kubernetes. The root skill only decides the next hop; detailed workflows live in the leaf skills.
compatibility	{"required_tools":["kubectl","helm"],"optional_tools":["npx"],"notes":"Requires Kubernetes access for install, preflight, provisioning, and operations. For local development, create a cluster first."}

KubeBlocks Router

This root skill is router only. It should decide the next step, not become a second README and not restate every leaf workflow.

Use:

• AGENTS.md for the cold-start agent operating model
• README.md for repository layout, truth layers, installation, and validation

Route Order

Always route in this order:

1. No Kubernetes cluster yet Route to create-local-k8s-cluster.

2. Kubernetes exists, but KubeBlocks is not installed Route to install-kubeblocks.

3. First-time provisioning, or environment readiness is unknown Route to kubeblocks-preflight before any engine-specific provisioning.

4. Provision a database after preflight

   • MySQL → engine-mysql
   • PostgreSQL → engine-postgresql
   • Redis → engine-redis
   • MongoDB → engine-mongodb
   • Kafka → engine-kafka
   • Elasticsearch → engine-elasticsearch
   • Milvus → engine-milvus
   • Qdrant → engine-qdrant
   • RabbitMQ → engine-rabbitmq
   • ClickHouse → engine-clickhouse
   • MariaDB → engine-mariadb
   • MinIO → engine-minio
   • OpenSearch → engine-opensearch
   • Pulsar → engine-pulsar
   • TiDB → engine-tidb
   • Other engines without dedicated entry skills → engine-generic

5. Operate an existing cluster Route to the matching capability layer:

   • lifecycle → op-lifecycle
   • horizontal scale → op-horizontal-scale
   • vertical scale → op-vertical-scale
   • volume expansion → op-volume-expansion
   • parameters → op-reconfigure
   • backup → op-backup
   • restore → op-restore
   • expose → op-expose
   • switchover → op-switchover
   • engine upgrade → op-upgrade
   • account / password management → manage-accounts
   • TLS / mTLS → configure-tls
   • safe deletion → delete-cluster

6. Observability

   • Broad observability ask → observability-router
   • Existing Prometheus/Grafana stack → observability-existing-stack
   • No monitoring base yet → observability-bootstrap-stack
   • If the user only says “set up monitoring”, use the shim setup-monitoring, which routes to the right observability branch.

7. Troubleshooting Route to troubleshoot from any stage when state is unknown, capability is unclear, or observed behavior is broken. For replica recovery or HA repair after troubleshooting, also consider rebuild-replica.

Hard Routing Rules

• Do not route the Tier-1 engine set to engine-generic or to any family/taxonomy-only explanation layer.
• Do not provision a first-time database without going through kubeblocks-preflight when environment readiness is unknown.
• Do not send agents back to raw addon examples as the primary create-time path once a dedicated Tier-1 engine entry exists.
• Do not require kubeblocks-addons or KubeBlocks core repo checkouts as runtime prerequisites. The runtime path must work from this repo plus official public docs.
• Do not equate “metrics exist” with “monitoring is delivered”. Observability must declare whether it is only metrics-ready, scrape-ready, dashboard-ready, or alerting-ready.
• Do not recommend legacy kubeblocks-addon-*, kubeblocks-create-cluster, or old Day-2 names as the primary path when the corresponding kubeblocks-engine-*, kubeblocks-engine-generic, or kubeblocks-op-* entry exists.

Recommendation Bundle Contract

kubeblocks-preflight should produce an environment profile / recommendation bundle that downstream engine-entry skills can consume. At minimum it must answer:

• Recommended storageClassName
• Whether topology-aware / WaitForFirstConsumer storage is required
• Which engine entry skill to use
• Which generic paths are forbidden
• Demo vs production sizing guidance
• Whether observability should go to existing-stack or bootstrap-stack

Common Misroutes To Prevent

• ACK multi-AZ + PostgreSQL/MySQL: Route to preflight first. Do not jump directly from install to addon provisioning.
• Existing Prometheus/Grafana: Route to observability-existing-stack, not full monitoring bootstrap.
• Unknown or low-frequency engines: Only then use engine-generic as the other-addons fallback.