Skill: earayu/kubeblocks-skills (version 0.2.0)

--- name: kubeblocks version: "0.2.0" description: Provision and manage production-grade databases on Kubernetes using KubeBlocks. Use this skill when the user needs a database — MySQL, PostgreSQL, Redis, MongoDB, Kafka, Elasticsearch, Milvus, Qdrant, RabbitMQ, or any other data infrastructure — and has (or is willing to set up) a Kubernetes environment. Trigger phrases include "I need a database", "set up MySQL", "spin up Postgres", "deploy a vector database for RAG", "I need a message queue", or any request involving database provisioning, scaling, backup, restore, monitoring, or troubleshooting on Kubernetes. Also use when the user explicitly mentions KubeBlocks, or wants to manage existing KubeBlocks-managed database clusters. compatibility: required_tools: - kubectl - helm optional_tools: - npx notes: Requires access to a Kubernetes cluster (kubeconfig). For local development, the skill can create a cluster using Kind, Minikube, or k3d. --- # 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: ```bash # 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](skills/kubeblocks-install/SKILL.md) skill. If there is no Kubernetes cluster at all, start with [create-local-k8s-cluster](skills/kubeblocks-create-local-k8s-cluster/SKILL.md). ## 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](skills/kubeblocks-create-local-k8s-cluster/SKILL.md) | | Install KubeBlocks operator | [install-kubeblocks](skills/kubeblocks-install/SKILL.md) | | Install/manage database engine addons | [manage-addons](skills/kubeblocks-manage-addons/SKILL.md) | ### Create a Database | User Intent | Skill | |---|---| | Create a MySQL cluster | [addon-mysql](skills/kubeblocks-addon-mysql/SKILL.md) | | Create a PostgreSQL cluster | [addon-postgresql](skills/kubeblocks-addon-postgresql/SKILL.md) | | Create a Redis cluster | [addon-redis](skills/kubeblocks-addon-redis/SKILL.md) | | Create a MongoDB cluster | [addon-mongodb](skills/kubeblocks-addon-mongodb/SKILL.md) | | Create a Kafka cluster | [addon-kafka](skills/kubeblocks-addon-kafka/SKILL.md) | | Create an Elasticsearch cluster | [addon-elasticsearch](skills/kubeblocks-addon-elasticsearch/SKILL.md) | | Create a Milvus (vector DB) cluster | [addon-milvus](skills/kubeblocks-addon-milvus/SKILL.md) | | Create a Qdrant (vector DB) cluster | [addon-qdrant](skills/kubeblocks-addon-qdrant/SKILL.md) | | Create a RabbitMQ cluster | [addon-rabbitmq](skills/kubeblocks-addon-rabbitmq/SKILL.md) | | Create any other database (generic) | [create-cluster](skills/kubeblocks-create-cluster/SKILL.md) | | Delete a database cluster | [delete-cluster](skills/kubeblocks-delete-cluster/SKILL.md) | ### Day-2 Operations | User Intent | Skill | |---|---| | Stop / Start / Restart a cluster | [cluster-lifecycle](skills/kubeblocks-cluster-lifecycle/SKILL.md) | | Scale CPU / Memory (vertical) | [vertical-scaling](skills/kubeblocks-vertical-scaling/SKILL.md) | | Add / remove replicas or shards | [horizontal-scaling](skills/kubeblocks-horizontal-scaling/SKILL.md) | | Expand storage volume | [volume-expansion](skills/kubeblocks-volume-expansion/SKILL.md) | | Change database parameters | [reconfigure-parameters](skills/kubeblocks-reconfigure-parameters/SKILL.md) | | Primary / secondary switchover | [switchover](skills/kubeblocks-switchover/SKILL.md) | | Upgrade database engine version | [minor-version-upgrade](skills/kubeblocks-minor-version-upgrade/SKILL.md) | | Rebuild a failed replica | [rebuild-replica](skills/kubeblocks-rebuild-replica/SKILL.md) | | Upgrade KubeBlocks operator | [upgrade-kubeblocks](skills/kubeblocks-upgrade/SKILL.md) | ### Data Protection | User Intent | Skill | |---|---| | Backup cluster data | [backup](skills/kubeblocks-backup/SKILL.md) | | Restore from backup / PITR | [restore](skills/kubeblocks-restore/SKILL.md) | ### Security & Networking | User Intent | Skill | |---|---| | Manage database passwords / accounts | [manage-accounts](skills/kubeblocks-manage-accounts/SKILL.md) | | Configure TLS / mTLS encryption | [configure-tls](skills/kubeblocks-configure-tls/SKILL.md) | | Expose service externally (LoadBalancer/NodePort) | [expose-service](skills/kubeblocks-expose-service/SKILL.md) | ### Observability | User Intent | Skill | |---|---| | Setup monitoring (Prometheus/Grafana) | [setup-monitoring](skills/kubeblocks-setup-monitoring/SKILL.md) | ### Troubleshooting | User Intent | Skill | |---|---| | Cluster not working, error, failed, stuck, CrashLoopBackOff | [troubleshoot](skills/kubeblocks-troubleshoot/SKILL.md) | ## 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](references/safety-patterns.md) 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 ```bash 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 |

path: AGENTS.md
content: This repository gives you the ability to provision and manage databases on Kubernetes using KubeBlocks.

Whenever the user needs a database — whether they mention KubeBlocks, Kubernetes, or just say "I need a MySQL" — read the root SKILL.md. It will route you to the right skill for the task.


path: README.md
content: # KubeBlocks Agent Skills

Give your AI agent the ability to provision and manage production-grade databases on Kubernetes.

These skills let any AI coding agent (Cursor, Claude Code, Codex, OpenClaw, etc.) deploy MySQL, PostgreSQL, Redis, MongoDB, Kafka, Elasticsearch, Milvus, Qdrant, RabbitMQ, and 20+ other database engines — with high availability, backup/restore, scaling, and monitoring built in. Powered by [KubeBlocks](https://kubeblocks.io/), the unified Kubernetes operator for 30+ database engines.

## Quick Start

Point your agent to the root `SKILL.md` — it routes to the right skill for any database task.

The agent will use these skills automatically whenever a database is needed, even if the user has never heard of KubeBlocks or Kubernetes.

## Available Skills

### Getting Started

| Skill | Description |
|-------|-------------|
| [kubeblocks](./SKILL.md) | Entry point for all database tasks. Routes to the right skill based on user intent. |
| [kubeblocks-create-local-k8s-cluster](./skills/kubeblocks-create-local-k8s-cluster/SKILL.md) | Create a local Kubernetes test cluster using Kind, Minikube, or k3d. |
| [kubeblocks-install](./skills/kubeblocks-install/SKILL.md) | Install the KubeBlocks operator. Handles version selection, network detection, registry configuration. |
| [kubeblocks-manage-addons](./skills/kubeblocks-manage-addons/SKILL.md) | Install, uninstall, and upgrade database engine addons. |

### Cluster Provisioning & Deletion

| Skill | Description |
|-------|-------------|
| [kubeblocks-create-cluster](./skills/kubeblocks-create-cluster/SKILL.md) | Create a database cluster (generic entry point for all addons). |
| [kubeblocks-delete-cluster](./skills/kubeblocks-delete-cluster/SKILL.md) | Safely delete a database cluster with pre-deletion checks. |

### Day-2 Operations

| Skill | Description |
|-------|-------------|
| [kubeblocks-cluster-lifecycle](./skills/kubeblocks-cluster-lifecycle/SKILL.md) | Stop, start, and restart database clusters. |
| [kubeblocks-vertical-scaling](./skills/kubeblocks-vertical-scaling/SKILL.md) | Scale CPU and memory resources. |
| [kubeblocks-horizontal-scaling](./skills/kubeblocks-horizontal-scaling/SKILL.md) | Add/remove replicas or shards. |
| [kubeblocks-volume-expansion](./skills/kubeblocks-volume-expansion/SKILL.md) | Expand persistent volume storage. |
| [kubeblocks-reconfigure-parameters](./skills/kubeblocks-reconfigure-parameters/SKILL.md) | Modify database configuration parameters. |
| [kubeblocks-minor-version-upgrade](./skills/kubeblocks-minor-version-upgrade/SKILL.md) | Upgrade database engine minor versions. |
| [kubeblocks-switchover](./skills/kubeblocks-switchover/SKILL.md) | Perform planned primary-secondary switchover. |
| [kubeblocks-rebuild-replica](./skills/kubeblocks-rebuild-replica/SKILL.md) | Rebuild a failed replica in MySQL or PostgreSQL clusters. |
| [kubeblocks-expose-service](./skills/kubeblocks-expose-service/SKILL.md) | Expose databases externally via LoadBalancer or NodePort. |
| [kubeblocks-upgrade](./skills/kubeblocks-upgrade/SKILL.md) | Upgrade the KubeBlocks operator itself via Helm. |

### Data Protection

| Skill | Description |
|-------|-------------|
| [kubeblocks-backup](./skills/kubeblocks-backup/SKILL.md) | Create on-demand, scheduled, and continuous backups. |
| [kubeblocks-restore](./skills/kubeblocks-restore/SKILL.md) | Restore from backups with full restore or Point-in-Time Recovery. |

### Security

| Skill | Description |
|-------|-------------|
| [kubeblocks-manage-accounts](./skills/kubeblocks-manage-accounts/SKILL.md) | Manage database passwords and password policies. |
| [kubeblocks-configure-tls](./skills/kubeblocks-configure-tls/SKILL.md) | Configure TLS, custom certificates, and mTLS. |

### Observability

| Skill | Description |
|-------|-------------|
| [kubeblocks-setup-monitoring](./skills/kubeblocks-setup-monitoring/SKILL.md) | Set up Prometheus monitoring and Grafana dashboards. |

### Engine-Specific Skills

| Skill | Description |
|-------|-------------|
| [kubeblocks-addon-mysql](./skills/kubeblocks-addon-mysql/SKILL.md) | MySQL topologies (semi-sync, MGR, Orchestrator, ProxySQL variants). |
| [kubeblocks-addon-postgresql](./skills/kubeblocks-addon-postgresql/SKILL.md) | PostgreSQL with Patroni-based HA replication. |
| [kubeblocks-addon-redis](./skills/kubeblocks-addon-redis/SKILL.md) | Redis standalone, replication with Sentinel, and Redis Cluster sharding. |
| [kubeblocks-addon-mongodb](./skills/kubeblocks-addon-mongodb/SKILL.md) | MongoDB ReplicaSet and Sharding topologies. |
| [kubeblocks-addon-kafka](./skills/kubeblocks-addon-kafka/SKILL.md) | Apache Kafka combined and separated broker/controller modes. |
| [kubeblocks-addon-elasticsearch](./skills/kubeblocks-addon-elasticsearch/SKILL.md) | Elasticsearch single-node and multi-node clusters for search and log analytics. |
| [kubeblocks-addon-milvus](./skills/kubeblocks-addon-milvus/SKILL.md) | Milvus vector database for AI/ML embedding similarity search. |
| [kubeblocks-addon-qdrant](./skills/kubeblocks-addon-qdrant/SKILL.md) | Qdrant vector database for vector search and RAG workloads. |
| [kubeblocks-addon-rabbitmq](./skills/kubeblocks-addon-rabbitmq/SKILL.md) | RabbitMQ message broker with AMQP, MQTT, and STOMP support. |

### Troubleshooting

| Skill | Description |
|-------|-------------|
| [kubeblocks-troubleshoot](./skills/kubeblocks-troubleshoot/SKILL.md) | Diagnostic guide for cluster errors, CrashLoopBackOff, stuck operations, and other failures. |

## Install

**One-liner (requires Node.js):**

```bash
npx skills add https://github.com/apecloud/kubeblocks-skills
```

**Or install for a specific platform:**

| Platform | Install |
|----------|---------|
| **Cursor** (2.4+) | Settings → Rules → Add Rule → Remote Rule (GitHub) → `https://github.com/apecloud/kubeblocks-skills` |
| **OpenAI Codex** | `$skill-installer https://github.com/apecloud/kubeblocks-skills` |
| **Claude Code** | `git clone https://github.com/apecloud/kubeblocks-skills ~/.claude/skills/kubeblocks` |
| **OpenClaw / Other** | `git clone https://github.com/apecloud/kubeblocks-skills ~/.agents/skills/kubeblocks` |

All skills follow the [Agent Skills](https://agentskills.io/) open standard and work with any agent that reads `SKILL.md` files.

## Repository Structure

```
├── SKILL.md              # Entry point — routes to the right skill for any database task
├── AGENTS.md             # Agent instructions for this repository
├── references/           # Shared references (safety patterns, etc.)
├── skills/               # All operation skills
│   ├── kubeblocks-install/
│   │   ├── SKILL.md
│   │   └── references/
│   ├── kubeblocks-create-cluster/
│   │   ├── SKILL.md
│   │   └── references/
│   ├── kubeblocks-addon-mysql/
│   │   ├── SKILL.md
│   │   └── references/
│   └── ...
```

Each skill directory contains:
- **SKILL.md**: Concise step-by-step workflow with YAML templates (< 500 lines).
- **references/**: Detailed configuration options, addon-specific differences, and extended examples (optional).

## Architecture

```
SKILL.md (kubeblocks) ─── Entry point for all database tasks
        │
        ├── Getting Started:   create-local-k8s-cluster → install-kubeblocks → manage-addons
        │
        ├── Provisioning:      create-cluster ←→ addon-{mysql,postgresql,redis,mongodb,kafka,
        │                      elasticsearch,milvus,qdrant,rabbitmq}
        │                      delete-cluster
        │
        ├── Operations:        cluster-lifecycle, vertical-scaling, horizontal-scaling,
        │                      volume-expansion, reconfigure-parameters, switchover,
        │                      minor-version-upgrade, rebuild-replica, expose-service,
        │                      upgrade-kubeblocks
        │
        ├── Data Protection:   backup, restore
        │
        ├── Security:          manage-accounts, configure-tls
        │
        ├── Observability:     setup-monitoring
        │
        └── Troubleshooting:   troubleshoot
```

Generic operation skills (e.g., `kubeblocks-vertical-scaling`) provide universal OpsRequest templates. Engine-specific skills (e.g., `kubeblocks-addon-mysql`) provide topology selection, cluster YAML examples, and connection methods. They cross-reference each other.

## Documentation

- [KubeBlocks Official Docs](https://kubeblocks.io/docs/preview/user_docs/overview/introduction)
- [KubeBlocks GitHub](https://github.com/apecloud/kubeblocks)
- [KubeBlocks LLM Index](https://kubeblocks.io/llms-full.txt)
- [Supported Addons](https://kubeblocks.io/docs/preview/user_docs/overview/supported-addons)

## Contributing

To add a new skill:

1. Create a new directory under `skills/` (e.g., `skills/kubeblocks-addon-clickhouse/`)
2. Add a `SKILL.md` with YAML frontmatter (`name`, `version`, and `description` fields)
3. Optionally add a `references/` subdirectory for detailed supplementary material
4. Update this README's skill tables
5. Update the root `SKILL.md` skill map

## License

[Apache 2.0](LICENSE)


path: references/safety-patterns.md
content: # Safety Patterns for Agent Operations

This document defines the safety conventions that all KubeBlocks skills should follow. When writing or updating a skill, reference this document instead of duplicating the rules.

## 1. Dry-Run Before Apply

Every `kubectl apply` of a Cluster, OpsRequest, Backup, or any other KubeBlocks CR should be preceded by a server-side dry-run. This catches RBAC issues, webhook rejections, quota violations, and schema errors before any real change occurs.

```bash
kubectl apply -f <yaml-file-or-stdin> --dry-run=server
```

If the dry-run reports errors, fix the YAML before proceeding. Only after a clean dry-run should the agent run the actual `kubectl apply`.

For `kubectl delete`, dry-run is not applicable — use the pre-deletion checklist instead (see section 3).

## 2. Status Confirmation After Apply

After applying a change, confirm the operation reached its expected end-state. Use `kubectl get <resource> -w` to watch status transitions.

Each watch step should have three things clearly defined:

- **Success condition**: the specific `.status.phase` value that means "done"
- **Typical duration**: how long this normally takes
- **Timeout threshold**: how long to wait before suspecting a problem and running `kubectl describe`

### Status Condition Quick Reference

| Resource | Success Condition | Typical Duration | Timeout / Investigate After |
|---|---|---|---|
| Cluster (create/restore) | `.status.phase` = `Running` | 1-5 min | 10 min |
| Cluster (stop) | `.status.phase` = `Stopped` | 1-3 min | 5 min |
| Cluster (start/restart) | `.status.phase` = `Running` | 1-3 min | 5 min |
| OpsRequest (general) | `.status.phase` = `Succeed` | 1-5 min | 10 min |
| OpsRequest (reconfigure, static params) | `.status.phase` = `Succeed` (may pass through `Restarting`) | 2-8 min | 15 min |
| Backup (full) | `.status.phase` = `Completed` | Varies by data size | 30 min |
| Backup (continuous) | `.status.phase` = `Running` (stays running) | 1 min to start | 5 min |

### When Timeout Is Reached

If the resource has not reached its success condition within the timeout threshold:

```bash
# For Cluster
kubectl describe cluster <name> -n <ns>
kubectl get events -n <ns> --sort-by='.lastTimestamp' | grep <name>

# For OpsRequest
kubectl describe ops <name> -n <ns>

# For Backup
kubectl describe backup <name> -n <ns>

# For Pods
kubectl describe pod <pod-name> -n <ns>
kubectl logs <pod-name> -n <ns> --tail=50
```

Report the findings to the user rather than continuing blindly.

## 3. Pre-Deletion Checklist

Before deleting any cluster, list what will be affected and get explicit confirmation from the user:

1. Show the cluster's `terminationPolicy`:
   ```bash
   kubectl get cluster <name> -n <ns> -o jsonpath='{.spec.terminationPolicy}'
   ```
2. If `WipeOut`, warn that backups will also be deleted
3. List existing backups:
   ```bash
   kubectl get backup -n <ns> -l app.kubernetes.io/instance=<name>
   ```
4. List running OpsRequests (must be cancelled first):
   ```bash
   kubectl get opsrequest -n <ns> -l app.kubernetes.io/instance=<name>
   ```
5. Ask the user to confirm before proceeding

## 4. Production Cluster Protection

If a cluster has `terminationPolicy: DoNotTerminate`, treat it as a production cluster:

- **Any destructive operation** (delete, scale-in, stop) should trigger a warning and explicit confirmation
- **Changing terminationPolicy** requires the agent to explain the implications before patching
- Recommend creating a backup before any risky operation (switchover, upgrade, reconfigure)

## 5. Pre-Check Before Day-2 Operations

Before executing any Day-2 operation, verify the cluster is in a healthy state:

```bash
# Cluster must be Running (not Updating, Creating, or Stopped)
kubectl get cluster <name> -n <ns> -o jsonpath='{.status.phase}'

# No pending OpsRequests (only one OpsRequest can run at a time)
kubectl get opsrequest -n <ns> -l app.kubernetes.io/instance=<name> --field-selector=status.phase!=Succeed
```

If the cluster is not `Running` or has a pending OpsRequest, inform the user and wait rather than stacking operations.


path: skills/kubeblocks-addon-kafka/references/reference.md
content: # Kafka Topologies Reference

## Combined Mode with Monitoring

```yaml
apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
  name: kafka-combined-monitor
  namespace: demo
spec:
  clusterDef: kafka
  topology: combined_monitor
  terminationPolicy: Delete
  componentSpecs:
    - name: kafka-combine
      serviceVersion: "3.3.2"
      replicas: 3
      resources:
        limits: {cpu: "0.5", memory: "0.5Gi"}
        requests: {cpu: "0.5", memory: "0.5Gi"}
      env:
        - name: KB_KAFKA_BROKER_HEAP
          value: "-Xmx256m -Xms256m"
        - name: KB_KAFKA_CONTROLLER_HEAP
          value: "-Xmx256m -Xms256m"
      volumeClaimTemplates:
        - name: data
          spec:
            accessModes: [ReadWriteOnce]
            resources: {requests: {storage: 20Gi}}
        - name: metadata
          spec:
            accessModes: [ReadWriteOnce]
            resources: {requests: {storage: 5Gi}}
    - name: kafka-exporter
      replicas: 1
      resources:
        limits: {cpu: "0.5", memory: "0.5Gi"}
        requests: {cpu: "0.5", memory: "0.5Gi"}
```

## Separated Mode with Monitoring (Full Production)

```yaml
apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
  name: kafka-prod
  namespace: demo
spec:
  clusterDef: kafka
  topology: separated_monitor
  terminationPolicy: DoNotTerminate
  componentSpecs:
    - name: kafka-broker
      serviceVersion: "3.3.2"
      replicas: 3
      resources:
        limits: {cpu: "2", memory: "4Gi"}
        requests: {cpu: "2", memory: "4Gi"}
      env:
        - name: KB_KAFKA_BROKER_HEAP
          value: "-Xmx2g -Xms2g"
      volumeClaimTemplates:
        - name: data
          spec:
            accessModes: [ReadWriteOnce]
            resources: {requests: {storage: 100Gi}}
        - name: metadata
          spec:
            accessModes: [ReadWriteOnce]
            resources: {requests: {storage: 10Gi}}
    - name: kafka-controller
      serviceVersion: "3.3.2"
      replicas: 3
      resources:
        limits: {cpu: "1", memory: "2Gi"}
        requests: {cpu: "1", memory: "2Gi"}
      env:
        - name: KB_KAFKA_CONTROLLER_HEAP
          value: "-Xmx1g -Xms1g"
      volumeClaimTemplates:
        - name: metadata
          spec:
            accessModes: [ReadWriteOnce]
            resources: {requests: {storage: 10Gi}}
    - name: kafka-exporter
      replicas: 1
      resources:
        limits: {cpu: "0.5", memory: "0.5Gi"}
        requests: {cpu: "0.5", memory: "0.5Gi"}
```

## Environment Variables

| Variable | Description | Default | Notes |
|---|---|---|---|
| `KB_KAFKA_BROKER_HEAP` | Broker JVM heap | `-Xmx256m -Xms256m` | Set to ~60% of container memory limit |
| `KB_KAFKA_CONTROLLER_HEAP` | Controller JVM heap | `-Xmx256m -Xms256m` | Controllers need less memory than brokers |
| `KB_KAFKA_ENABLE_SASL` | Enable SASL auth | (unset) | Set to `true` for authentication |
| `KB_KAFKA_PUBLIC_ACCESS` | External access mode | (unset) | Set to `true` for NodePort/LB exposure |

## Topology Component and Volume Matrix

| Topology | Components | Volumes per Component |
|---|---|---|
| `combined` | kafka-combine | data + metadata |
| `combined_monitor` | kafka-combine, kafka-exporter | data + metadata (combine only) |
| `separated` | kafka-broker, kafka-controller | broker: data + metadata; controller: metadata only |
| `separated_monitor` | kafka-broker, kafka-controller, kafka-exporter | same as separated |

Key points:
- Brokers store message data (`data`) and cluster metadata (`metadata`)
- Controllers only store metadata — they don't hold message data
- 3 controller replicas are required for KRaft consensus (Raft majority quorum)
- Exporter components have no volumes — they only scrape and expose metrics


path: skills/kubeblocks-addon-mongodb/references/reference.md
content: # MongoDB Addon Reference

Detailed YAML examples and configurations for the MongoDB addon on KubeBlocks v1.0.x.

Source: https://kubeblocks.io/docs/preview/user_docs/kubeblocks-for-mongodb/cluster-management/create-and-connect-a-mongodb-cluster

## ClusterDefinition and Topologies

- **clusterDef:** `mongodb`
- **Topologies:** `replicaset`, `sharding`

## ReplicaSet Cluster

```yaml
apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
  name: mongo-replicaset
  namespace: demo
spec:
  clusterDef: mongodb
  topology: replicaset
  terminationPolicy: Delete
  componentSpecs:
    - name: mongodb
      serviceVersion: "7.0.12"
      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}}
```

## Sharded Cluster (Full Example)

A sharded cluster consists of three component types:

1. **Shards** — store the distributed data (defined in `spec.shardings`)
2. **Config Server** — stores sharding metadata (defined in `spec.componentSpecs`)
3. **Mongos** — query router (defined in `spec.componentSpecs`)

```yaml
apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
  name: mongo-sharded
  namespace: demo
spec:
  clusterDef: mongodb
  topology: sharding
  terminationPolicy: Delete
  shardings:
    - name: shard
      shards: 2
      template:
        name: mongodb
        serviceVersion: "7.0.12"
        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}}
  componentSpecs:
    - name: config-server
      serviceVersion: "7.0.12"
      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}}
    - name: mongos
      serviceVersion: "7.0.12"
      replicas: 2
      resources:
        limits: {cpu: "0.5", memory: "0.5Gi"}
        requests: {cpu: "0.5", memory: "0.5Gi"}
```

### Production Sharded Cluster

```yaml
apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
  name: mongo-sharded-prod
  namespace: demo
spec:
  clusterDef: mongodb
  topology: sharding
  terminationPolicy: Halt
  shardings:
    - name: shard
      shards: 3
      template:
        name: mongodb
        serviceVersion: "7.0.12"
        replicas: 3
        resources:
          limits: {cpu: "2", memory: "4Gi"}
          requests: {cpu: "2", memory: "4Gi"}
        volumeClaimTemplates:
          - name: data
            spec:
              accessModes: [ReadWriteOnce]
              resources: {requests: {storage: 100Gi}}
  componentSpecs:
    - name: config-server
      serviceVersion: "7.0.12"
      replicas: 3
      resources:
        limits: {cpu: "1", memory: "2Gi"}
        requests: {cpu: "1", memory: "2Gi"}
      volumeClaimTemplates:
        - name: data
          spec:
            accessModes: [ReadWriteOnce]
            resources: {requests: {storage: 20Gi}}
    - name: mongos
      serviceVersion: "7.0.12"
      replicas: 3
      resources:
        limits: {cpu: "1", memory: "2Gi"}
        requests: {cpu: "1", memory: "2Gi"}
```

## Sharding Architecture

```
Client
  │
  ▼
mongos (query router, stateless)
  │
  ├─── config-server (metadata, 3 replicas)
  │
  ├─── shard-0 (ReplicaSet, 3 replicas)
  ├─── shard-1 (ReplicaSet, 3 replicas)
  └─── shard-N (ReplicaSet, 3 replicas)
```

- Clients connect to **mongos** on port 27017
- mongos routes queries to the appropriate shard(s)
- Each shard is an independent ReplicaSet
- Config-server stores chunk distribution metadata

## Supported Versions

| Version | serviceVersion | Notes |
|---|---|---|
| MongoDB 4.0 | `4.0` | Legacy |
| MongoDB 4.2 | `4.2` | Legacy |
| MongoDB 4.4 | `4.4` | Legacy |
| MongoDB 5.0 | `5.0` | Stable |
| MongoDB 6.0 | `6.0` | Stable |
| MongoDB 7.0 | `7.0.12` | Latest, recommended |

## Connection Details

| Property | Value |
|---|---|
| Port | 27017 |
| Root Secret | `<cluster>-mongodb-account-root` |
| Secret Keys | `username`, `password` |

### Connection Strings

```bash
# ReplicaSet
mongosh "mongodb://root:<password>@<cluster>-mongodb-0.<cluster>-mongodb-headless.<namespace>.svc:27017,<cluster>-mongodb-1.<cluster>-mongodb-headless.<namespace>.svc:27017,<cluster>-mongodb-2.<cluster>-mongodb-headless.<namespace>.svc:27017/admin?replicaSet=<cluster>-mongodb"

# Sharded (via mongos service)
mongosh "mongodb://root:<password>@<cluster>-mongos.<namespace>.svc:27017/admin"
```

## Useful MongoDB Commands

```bash
# ReplicaSet status
kubectl -n demo exec -it <cluster>-mongodb-0 -- mongosh --eval "rs.status()"

# Sharding status
kubectl -n demo exec -it <cluster>-mongos-0 -- mongosh --eval "sh.status()"

# Enable sharding on a database
kubectl -n demo exec -it <cluster>-mongos-0 -- mongosh --eval 'sh.enableSharding("mydb")'

# Shard a collection
kubectl -n demo exec -it <cluster>-mongos-0 -- mongosh --eval 'sh.shardCollection("mydb.mycol", {"_id": "hashed"})'
```

## Termination Policies

| Policy | Behavior |
|---|---|
| `DoNotTerminate` | Block deletion |
| `Halt` | Delete workloads, keep PVCs and secrets |
| `Delete` | Delete workloads and PVCs, keep backups |
| `WipeOut` | Delete everything including backups |

## Documentation Links

- Create Cluster: https://kubeblocks.io/docs/preview/user_docs/kubeblocks-for-mongodb/cluster-management/create-and-connect-a-mongodb-cluster
- Scaling: https://kubeblocks.io/docs/preview/user_docs/kubeblocks-for-mongodb/cluster-management/scale-for-a-mongodb-cluster


path: skills/kubeblocks-addon-mysql/references/reference.md
content: # MySQL Addon Reference

Detailed YAML examples and configurations for the MySQL addon on KubeBlocks v1.0.x.

Source: https://kubeblocks.io/docs/preview/user_docs/kubeblocks-for-mysql/cluster-management/create-and-connect-a-mysql-cluster

## ClusterDefinition and Topologies

- **clusterDef:** `mysql`
- **Topologies:** `semisync`, `semisync-proxysql`, `mgr`, `mgr-proxysql`, `orc`, `orc-proxysql`

## Semi-Synchronous Replication (semisync)

```yaml
apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
  name: mysql-semisync
  namespace: demo
spec:
  clusterDef: mysql
  topology: semisync
  terminationPolicy: Delete
  componentSpecs:
    - name: mysql
      serviceVersion: "8.0.35"
      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}}
```

## Semi-Sync with ProxySQL (semisync-proxysql)

```yaml
apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
  name: mysql-semisync-proxy
  namespace: demo
spec:
  clusterDef: mysql
  topology: semisync-proxysql
  terminationPolicy: Delete
  componentSpecs:
    - name: mysql
      serviceVersion: "8.0.35"
      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}}
    - name: proxysql
      replicas: 1
      resources:
        limits: {cpu: "0.5", memory: "0.5Gi"}
        requests: {cpu: "0.5", memory: "0.5Gi"}
```

ProxySQL listens on port 6033 and routes read/write queries automatically.

## Group Replication (mgr)

```yaml
apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
  name: mysql-mgr
  namespace: demo
spec:
  clusterDef: mysql
  topology: mgr
  terminationPolicy: Delete
  componentSpecs:
    - name: mysql
      serviceVersion: "8.0.35"
      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}}
```

MGR requires a minimum of 3 replicas to form a consensus group.

## MGR with ProxySQL (mgr-proxysql)

```yaml
apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
  name: mysql-mgr-proxy
  namespace: demo
spec:
  clusterDef: mysql
  topology: mgr-proxysql
  terminationPolicy: Delete
  componentSpecs:
    - name: mysql
      serviceVersion: "8.0.35"
      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}}
    - name: proxysql
      replicas: 1
      resources:
        limits: {cpu: "0.5", memory: "0.5Gi"}
        requests: {cpu: "0.5", memory: "0.5Gi"}
```

## Orchestrator (orc)

```yaml
apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
  name: mysql-orc
  namespace: demo
spec:
  clusterDef: mysql
  topology: orc
  terminationPolicy: Delete
  componentSpecs:
    - name: mysql
      serviceVersion: "8.0.35"
      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}}
    - name: orchestrator
      replicas: 1
      resources:
        limits: {cpu: "0.5", memory: "0.5Gi"}
        requests: {cpu: "0.5", memory: "0.5Gi"}
```

Orchestrator provides external topology discovery and automated failover management.

## Orchestrator with ProxySQL (orc-proxysql)

```yaml
apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
  name: mysql-orc-proxy
  namespace: demo
spec:
  clusterDef: mysql
  topology: orc-proxysql
  terminationPolicy: Delete
  componentSpecs:
    - name: mysql
      serviceVersion: "8.0.35"
      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}}
    - name: orchestrator
      replicas: 1
      resources:
        limits: {cpu: "0.5", memory: "0.5Gi"}
        requests: {cpu: "0.5", memory: "0.5Gi"}
    - name: proxysql
      replicas: 1
      resources:
        limits: {cpu: "0.5", memory: "0.5Gi"}
        requests: {cpu: "0.5", memory: "0.5Gi"}
```

## Backup Methods

### XtraBackup

Physical backup using Percona XtraBackup. Fast and efficient for large databases.

```yaml
apiVersion: dataprotection.kubeblocks.io/v1alpha1
kind: Backup
metadata:
  name: mysql-xtrabackup
  namespace: demo
spec:
  backupMethod: xtrabackup
  backupPolicyName: mysql-cluster-mysql-backup-policy
```

### Volume Snapshot

Uses the storage provider's snapshot capability. Fastest method but requires CSI driver support.

```yaml
apiVersion: dataprotection.kubeblocks.io/v1alpha1
kind: Backup
metadata:
  name: mysql-snapshot
  namespace: demo
spec:
  backupMethod: volume-snapshot
  backupPolicyName: mysql-cluster-mysql-backup-policy
```

### Binlog Archive (for PITR)

Continuously archives binary logs for point-in-time recovery.

```yaml
apiVersion: dataprotection.kubeblocks.io/v1alpha1
kind: Backup
metadata:
  name: mysql-binlog
  namespace: demo
spec:
  backupMethod: archive-binlog
  backupPolicyName: mysql-cluster-mysql-backup-policy
```

## Supported Versions

| Version | serviceVersion | Notes |
|---|---|---|
| MySQL 5.7 | `5.7.44` | Legacy support |
| MySQL 8.0 | `8.0.33` | Stable |
| MySQL 8.0 | `8.0.35` | Latest 8.0, recommended |
| MySQL 8.4 | `8.4.2` | Innovation release |

## Connection Details

| Property | Value |
|---|---|
| Port | 3306 |
| ProxySQL Port | 6033 |
| Root Secret | `<cluster>-mysql-account-root` |
| Secret Keys | `username`, `password` |

## Termination Policies

| Policy | Behavior |
|---|---|
| `DoNotTerminate` | Block deletion |
| `Halt` | Delete workloads, keep PVCs and secrets |
| `Delete` | Delete workloads and PVCs, keep backups |
| `WipeOut` | Delete everything including backups |

## Documentation Links

- Create Cluster: https://kubeblocks.io/docs/preview/user_docs/kubeblocks-for-mysql/cluster-management/create-and-connect-a-mysql-cluster
- Scaling: https://kubeblocks.io/docs/preview/user_docs/kubeblocks-for-mysql/cluster-management/scale-for-a-mysql-cluster
- Backup & Restore: https://kubeblocks.io/docs/preview/user_docs/kubeblocks-for-mysql/backup-and-restore/backup


path: skills/kubeblocks-addon-postgresql/references/reference.md
content: # PostgreSQL Addon Reference

Detailed YAML examples and configurations for the PostgreSQL addon on KubeBlocks v1.0.x.

Source: https://kubeblocks.io/docs/preview/user_docs/kubeblocks-for-postgresql/cluster-management/create-and-connect-a-postgresql-cluster

## ClusterDefinition and Topology

- **clusterDef:** `postgresql`
- **Topology:** `replication`

The PostgreSQL addon uses Patroni (via the Spilo image) for high availability. All pods run the same PostgreSQL + Patroni stack; Patroni elects a leader and manages streaming replication.

## Replication Cluster

```yaml
apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
  name: pg-cluster
  namespace: demo
spec:
  clusterDef: postgresql
  topology: replication
  terminationPolicy: Delete
  componentSpecs:
    - name: postgresql
      serviceVersion: "14.7.2"
      replicas: 2
      disableExporter: false
      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}}
```

## Vanilla PostgreSQL Variant

KubeBlocks also provides a vanilla PostgreSQL (without Patroni/Spilo) as a separate addon. This is useful for simpler single-instance deployments where HA is not needed.

```yaml
apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
  name: pg-vanilla
  namespace: demo
spec:
  clusterDef: vanilla-postgresql
  topology: standalone
  terminationPolicy: Delete
  componentSpecs:
    - name: postgresql
      serviceVersion: "14.7.2"
      replicas: 1
      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}}
```

The vanilla-postgresql addon uses the official PostgreSQL image without Patroni.

## Supported Versions

| Major Version | serviceVersion | Notes |
|---|---|---|
| PostgreSQL 12 | `12.14.0` | Legacy |
| PostgreSQL 12 | `12.14.1` | Legacy, patch |
| PostgreSQL 12 | `12.15.0` | Legacy |
| PostgreSQL 14 | `14.7.2` | Stable, widely used |
| PostgreSQL 14 | `14.8.0` | Stable |
| PostgreSQL 15 | `15.7.0` | Current |
| PostgreSQL 16 | `16.4.0` | Current |
| PostgreSQL 17 | `17.4.0` | Latest stable |
| PostgreSQL 18 | `18.0.0` | Latest |

## Backup Methods

### pg-basebackup

Standard PostgreSQL base backup tool. Creates a full backup.

```yaml
apiVersion: dataprotection.kubeblocks.io/v1alpha1
kind: Backup
metadata:
  name: pg-basebackup
  namespace: demo
spec:
  backupMethod: pg-basebackup
  backupPolicyName: pg-cluster-postgresql-backup-policy
```

### Volume Snapshot

Uses the storage provider's snapshot capability. Requires CSI snapshot support.

```yaml
apiVersion: dataprotection.kubeblocks.io/v1alpha1
kind: Backup
metadata:
  name: pg-snapshot
  namespace: demo
spec:
  backupMethod: volume-snapshot
  backupPolicyName: pg-cluster-postgresql-backup-policy
```

### WAL Archive (for PITR)

Continuously archives WAL (Write-Ahead Log) files for point-in-time recovery.

```yaml
apiVersion: dataprotection.kubeblocks.io/v1alpha1
kind: Backup
metadata:
  name: pg-wal
  namespace: demo
spec:
  backupMethod: wal-archive
  backupPolicyName: pg-cluster-postgresql-backup-policy
```

To restore to a specific point in time:

```yaml
apiVersion: dataprotection.kubeblocks.io/v1alpha1
kind: Restore
metadata:
  name: pg-pitr-restore
  namespace: demo
spec:
  backup:
    name: pg-basebackup
    namespace: demo
  restoreTime: "2024-01-15T10:30:00Z"
```

## Connection Details

| Property | Value |
|---|---|
| Port | 5432 |
| Superuser Secret | `<cluster>-postgresql-account-postgres` |
| Secret Keys | `username`, `password` |

## Patroni Commands

Useful Patroni commands via kubectl exec:

```bash
# List cluster members and roles
kubectl -n demo exec -it pg-cluster-postgresql-0 -- patronictl list

# Switchover to a different primary
kubectl -n demo exec -it pg-cluster-postgresql-0 -- patronictl switchover

# Reinitialize a replica
kubectl -n demo exec -it pg-cluster-postgresql-0 -- patronictl reinit pg-cluster-postgresql <member>
```

## Termination Policies

| Policy | Behavior |
|---|---|
| `DoNotTerminate` | Block deletion |
| `Halt` | Delete workloads, keep PVCs and secrets |
| `Delete` | Delete workloads and PVCs, keep backups |
| `WipeOut` | Delete everything including backups |

## Documentation Links

- Create Cluster: https://kubeblocks.io/docs/preview/user_docs/kubeblocks-for-postgresql/cluster-management/create-and-connect-a-postgresql-cluster
- Scaling: https://kubeblocks.io/docs/preview/user_docs/kubeblocks-for-postgresql/cluster-management/scale-for-a-postgresql-cluster
- Backup & Restore: https://kubeblocks.io/docs/preview/user_docs/kubeblocks-for-postgresql/backup-and-restore/backup


path: skills/kubeblocks-addon-redis/references/reference.md
content: # Redis Addon Reference

Detailed YAML examples and configurations for the Redis addon on KubeBlocks v1.0.x.

Source: https://kubeblocks.io/docs/preview/user_docs/kubeblocks-for-redis/cluster-management/create-and-connect-a-redis-cluster

## Topologies Overview

| Topology | Spec Field | clusterDef | topology | componentDef |
|---|---|---|---|---|
| Standalone | `componentSpecs` | `redis` | `standalone` | — |
| Replication | `componentSpecs` | `redis` | `replication` | — |
| Sharding | `shardings` | — | — | `redis-cluster-7` |

## Standalone

```yaml
apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
  name: redis-standalone
  namespace: demo
spec:
  clusterDef: redis
  topology: standalone
  terminationPolicy: Delete
  componentSpecs:
    - name: redis
      serviceVersion: "7.2.4"
      replicas: 1
      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}}
```

## Replication with Sentinel

```yaml
apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
  name: redis-replication
  namespace: demo
spec:
  clusterDef: redis
  topology: replication
  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}}
    - name: redis-sentinel
      serviceVersion: "7.2.4"
      replicas: 3
      resources:
        limits: {cpu: "0.2", memory: "256Mi"}
        requests: {cpu: "0.2", memory: "256Mi"}
      volumeClaimTemplates:
        - name: data
          spec:
            accessModes: [ReadWriteOnce]
            resources: {requests: {storage: 20Gi}}
```

## Redis Cluster (Sharding)

### Basic Sharding

```yaml
apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
  name: redis-cluster
  namespace: demo
spec:
  terminationPolicy: Delete
  shardings:
    - name: shard
      shards: 3
      template:
        name: redis-shard
        componentDef: redis-cluster-7
        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}}
```

### Sharding with NodePort (External Access)

To expose Redis Cluster nodes externally using NodePort services:

```yaml
apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
  name: redis-cluster-external
  namespace: demo
spec:
  terminationPolicy: Delete
  shardings:
    - name: shard
      shards: 3
      template:
        name: redis-shard
        componentDef: redis-cluster-7
        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}}
        services:
          - name: nodeport
            serviceType: NodePort
            podService: true
```

Setting `podService: true` creates a separate NodePort service per pod, which is required for Redis Cluster since clients need direct access to each node.

## Sharding vs componentSpecs

**Critical difference:** Redis Cluster (sharding) uses `spec.shardings` instead of `spec.componentSpecs`.

| Field | Standalone / Replication | Sharding |
|---|---|---|
| Spec field | `spec.componentSpecs` | `spec.shardings` |
| `clusterDef` | `redis` | Not set |
| `topology` | `standalone` / `replication` | Not set |
| `componentDef` | Not needed (from clusterDef) | `redis-cluster-7` |
| Scaling | Change `replicas` | Change `shards` count |

## Supported Versions

| Version | serviceVersion | Notes |
|---|---|---|
| Redis 7.0 | `7.0.6` | Stable |
| Redis 7.2 | `7.2.4` | Latest, recommended |

## Connection Details

| Property | Value |
|---|---|
| Port | 6379 |
| Sentinel Port | 26379 |
| Default Secret | `<cluster>-redis-account-default` |
| Secret Keys | `username`, `password` |

## Sentinel Commands

```bash
# List monitored masters
kubectl -n demo exec -it redis-replication-redis-sentinel-0 -- redis-cli -p 26379 SENTINEL masters

# Get current master address
kubectl -n demo exec -it redis-replication-redis-sentinel-0 -- redis-cli -p 26379 SENTINEL get-master-addr-by-name
```

## Redis Cluster Commands

```bash
# Cluster info
kubectl -n demo exec -it <shard-pod> -- redis-cli -c CLUSTER INFO

# Cluster nodes
kubectl -n demo exec -it <shard-pod> -- redis-cli -c CLUSTER NODES

# Check slot distribution
kubectl -n demo exec -it <shard-pod> -- redis-cli -c CLUSTER SLOTS
```

## Termination Policies

| Policy | Behavior |
|---|---|
| `DoNotTerminate` | Block deletion |
| `Halt` | Delete workloads, keep PVCs and secrets |
| `Delete` | Delete workloads and PVCs, keep backups |
| `WipeOut` | Delete everything including backups |

## Documentation Links

- Create Cluster: https://kubeblocks.io/docs/preview/user_docs/kubeblocks-for-redis/cluster-management/create-and-connect-a-redis-cluster
- Scaling: https://kubeblocks.io/docs/preview/user_docs/kubeblocks-for-redis/cluster-management/scale-for-a-redis-cluster


path: skills/kubeblocks-backup/references/reference.md
content: # Backup Reference

Detailed configuration for BackupRepo, storage providers, continuous backups, and BackupPolicy customization.

Source: https://kubeblocks.io/docs/preview/user_docs/concepts/backup-and-restore/introduction

## BackupRepo Setup

### BackupRepo Credential Secret

Create a Secret with storage provider credentials before creating the BackupRepo:

**S3:**

```yaml
apiVersion: v1
kind: Secret
metadata:
  name: s3-credential
  namespace: kb-system
type: Opaque
stringData:
  [REDACTED_SECRET]
  secretAccessKey: <AWS_SECRET_ACCESS_KEY>
```

**OSS (Alibaba Cloud):**

```yaml
apiVersion: v1
kind: Secret
metadata:
  name: oss-credential
  namespace: kb-system
type: Opaque
stringData:
  [REDACTED_SECRET]
  secretAccessKey: <ALIBABA_SECRET_ACCESS_KEY>
```

**GCS:**

```yaml
apiVersion: v1
kind: Secret
metadata:
  name: gcs-credential
  namespace: kb-system
type: Opaque
stringData:
  [REDACTED_SECRET]
  secretAccessKey: <GCS_SECRET_ACCESS_KEY>
```

**MinIO:**

```yaml
apiVersion: v1
kind: Secret
metadata:
  name: minio-credential
  namespace: kb-system
type: Opaque
stringData:
  [REDACTED_SECRET]
  secretAccessKey: <MINIO_SECRET_KEY>
```

### BackupRepo CR Examples

**S3:**

```yaml
apiVersion: dataprotection.kubeblocks.io/v1alpha1
kind: BackupRepo
metadata:
  name: s3-backuprepo
spec:
  storageProviderRef: s3
  accessMethod: Tool
  pvReclaimPolicy: Retain
  config:
    bucket: <bucket-name>
    region: <region>
    endpoint: ""
  credential:
    name: s3-credential
    namespace: kb-system
```

**OSS (Alibaba Cloud):**

```yaml
apiVersion: dataprotection.kubeblocks.io/v1alpha1
kind: BackupRepo
metadata:
  name: oss-backuprepo
spec:
  storageProviderRef: oss
  accessMethod: Tool
  pvReclaimPolicy: Retain
  config:
    bucket: <bucket-name>
    region: <region>
    endpoint: ""
  credential:
    name: oss-credential
    namespace: kb-system
```

**GCS:**

```yaml
apiVersion: dataprotection.kubeblocks.io/v1alpha1
kind: BackupRepo
metadata:
  name: gcs-backuprepo
spec:
  storageProviderRef: gcs
  accessMethod: Tool
  pvReclaimPolicy: Retain
  config:
    bucket: <bucket-name>
    region: <region>
    endpoint: ""
  credential:
    name: gcs-credential
    namespace: kb-system
```

**MinIO:**

```yaml
apiVersion: dataprotection.kubeblocks.io/v1alpha1
kind: BackupRepo
metadata:
  name: minio-backuprepo
spec:
  storageProviderRef: minio
  accessMethod: Tool
  pvReclaimPolicy: Retain
  config:
    bucket: <bucket-name>
    endpoint: <minio-endpoint>    # e.g. http://minio.minio-system.svc.cluster.local:9000
  credential:
    name: minio-credential
    namespace: kb-system
```

### Supported Storage Providers

| Provider | `storageProviderRef` | Notes |
|----------|---------------------|-------|
| AWS S3   | `s3`                | Standard S3 API |
| Alibaba OSS | `oss`           | Alibaba Cloud Object Storage |
| Tencent COS | `cos`           | Tencent Cloud Object Storage |
| Google GCS | `gcs`             | Google Cloud Storage |
| Huawei OBS | `obs`             | Huawei Cloud Object Storage |
| MinIO    | `minio`             | S3-compatible, self-hosted |

### Verify BackupRepo

```bash
kubectl get backuprepo
```

Status should show `Ready`:

```
NAME              STATUS   STORAGEPROVIDER   ACCESSMETHOD   AGE
s3-backuprepo     Ready    s3                Tool           5m
```

## BackupPolicy Customization

BackupPolicies are auto-created per cluster. To customize, edit the existing policy:

```bash
kubectl edit backuppolicy <cluster>-<component>-backup-policy -n <ns>
```

Key fields:

```yaml
spec:
  backupMethods:
  - name: xtrabackup
    actionSetName: xtrabackup-for-apecloud-mysql
    snapshotVolumes: false
    target:
      role: secondary    # backup from secondary to avoid primary impact
    env:
    - name: BACKUP_THREADS
      value: "4"
  - name: volume-snapshot
    snapshotVolumes: true
    target:
      role: secondary
```

## Continuous Backup for PITR

### MySQL (archive-binlog)

```yaml
apiVersion: dataprotection.kubeblocks.io/v1alpha1
kind: Backup
metadata:
  name: <cluster>-binlog-continuous
  namespace: <ns>
spec:
  backupMethod: archive-binlog
  backupPolicyName: <cluster>-mysql-backup-policy
  deletionPolicy: Delete
```

### PostgreSQL (wal-archive)

```yaml
apiVersion: dataprotection.kubeblocks.io/v1alpha1
kind: Backup
metadata:
  name: <cluster>-wal-continuous
  namespace: <ns>
spec:
  backupMethod: wal-archive
  backupPolicyName: <cluster>-postgresql-backup-policy
  deletionPolicy: Delete
```

### PITR Prerequisites

1. A completed **full backup** (xtrabackup / pg-basebackup)
2. A running **continuous backup** (archive-binlog / wal-archive)
3. Both must use the same BackupPolicy

### Check Continuous Backup Status

```bash
kubectl get backup -n <ns> | grep Running
```

Continuous backups stay in `Running` status as they continuously stream logs.

## Backup Deletion Policies

| Policy | Behavior |
|--------|----------|
| `Delete` | Backup data deleted when Backup CR is deleted |
| `Retain` | Backup data retained even after Backup CR deletion |
| `DoNotDelete` | Backup CR cannot be deleted (protected) |

## Documentation Links

- Backup & Restore Overview: https://kubeblocks.io/docs/preview/user_docs/concepts/backup-and-restore/introduction
- Configure BackupRepo: https://kubeblocks.io/docs/preview/user_docs/concepts/backup-and-restore/backup-repo
- On-demand Backup: https://kubeblocks.io/docs/preview/user_docs/handle-an-exception/full-backup
- Scheduled Backup: https://kubeblocks.io/docs/preview/user_docs/handle-an-exception/scheduled-backup
- PITR: https://kubeblocks.io/docs/preview/user_docs/handle-an-exception/pitr


path: skills/kubeblocks-cluster-lifecycle/references/reference.md
content: # Cluster Lifecycle Reference

## OpsRequest API Reference

Full API docs: https://kubeblocks.io/docs/preview/user_docs/references/api-reference/operations

### Stop OpsRequest

```yaml
apiVersion: apps.kubeblocks.io/v1beta1
kind: OpsRequest
metadata:
  name: stop-<cluster-name>
  namespace: <namespace>
spec:
  clusterName: <cluster-name>
  type: Stop
```

### Start OpsRequest

```yaml
apiVersion: apps.kubeblocks.io/v1beta1
kind: OpsRequest
metadata:
  name: start-<cluster-name>
  namespace: <namespace>
spec:
  clusterName: <cluster-name>
  type: Start
```

### Restart OpsRequest

```yaml
apiVersion: apps.kubeblocks.io/v1beta1
kind: OpsRequest
metadata:
  name: restart-<cluster-name>
  namespace: <namespace>
spec:
  clusterName: <cluster-name>
  type: Restart
  restart:
    - componentName: <component-name>
```

Restart supports multiple components in a single OpsRequest:

```yaml
  restart:
    - componentName: mysql
    - componentName: proxy
```

## Component Names by Engine

| Engine | Component Names |
|--------|----------------|
| MySQL (semi-sync) | `mysql` |
| MySQL (MGR) | `mysql` |
| MySQL (orchestrator) | `mysql`, `orchestrator` |
| MySQL (with ProxySQL) | `mysql`, `proxysql` |
| PostgreSQL | `postgresql` |
| Redis (standalone) | `redis` |
| Redis (replication) | `redis`, `redis-sentinel` |
| Redis (cluster/sharding) | `redis-shard` |
| MongoDB (replicaset) | `mongodb` |
| MongoDB (sharding) | `mongos`, `configsvr`, `shard` |
| Kafka (combined) | `kafka-combine` |
| Kafka (separated) | `kafka-broker`, `kafka-controller` |
| Elasticsearch | `elasticsearch` |
| Milvus (standalone) | `milvus` |
| Milvus (cluster) | `milvus-proxy`, `milvus-mixcoord`, `milvus-datanode`, `milvus-indexnode`, `milvus-querynode` |

## kubectl Patch Alternative

### Stop via patch

```bash
kubectl patch cluster <cluster-name> -n <namespace> \
  --type merge \
  -p '{"spec":{"componentSpecs":[{"name":"<component-name>","stop":true}]}}'
```

### Start via patch

```bash
kubectl patch cluster <cluster-name> -n <namespace> \
  --type merge \
  -p '{"spec":{"componentSpecs":[{"name":"<component-name>","stop":false}]}}'
```

### Stop specific components only

You can stop individual components by setting `stop: true` on specific componentSpecs. This is useful for stopping proxy or monitoring components while keeping the database running.

## Cluster Status Transitions

```
Running ──Stop──→ Stopping ──→ Stopped
Stopped ──Start─→ Starting ──→ Running
Running ──Restart→ Updating ──→ Running
```

### Status Meanings

| Status | Description |
|--------|-------------|
| `Running` | All components healthy and serving |
| `Stopped` | All pods terminated, PVCs retained |
| `Stopping` | Stop in progress, pods being terminated |
| `Starting` | Start in progress, pods being created |
| `Updating` | Restart in progress, rolling restart active |
| `Failed` | Operation failed, check events |

## Behavior Details

### Stop behavior
- All pods in the cluster are terminated (scaled to 0 replicas)
- PVCs are retained — no data loss
- Services are retained but have no endpoints
- Cluster status changes to `Stopped`
- Cost savings: no compute charges while stopped (only storage charges remain)

### Start behavior
- Pods are recreated from the same PVC data
- Data is preserved exactly as it was before stop
- Replication and HA are re-established automatically
- Cluster returns to `Running` once all pods are ready

### Restart behavior
- Performs a rolling restart: one pod at a time
- For HA clusters: secondary pods restart first, then primary
- Automatic switchover occurs before restarting the primary to minimize downtime
- No data loss
- Useful after static parameter changes that require a restart

## Common Patterns

### Cost-saving: stop dev/test clusters on schedule

Combine with a CronJob or external scheduler:

```bash
kubectl apply -f - <<'EOF'
apiVersion: apps.kubeblocks.io/v1beta1
kind: OpsRequest
metadata:
  name: stop-dev-cluster-nightly
  namespace: dev
spec:
  clusterName: dev-mysql
  type: Stop
EOF
```

### Restart after static parameter change

After modifying a static parameter (e.g., `innodb_buffer_pool_size` for MySQL), a restart is required:

```bash
kubectl apply -f - <<'EOF'
apiVersion: apps.kubeblocks.io/v1beta1
kind: OpsRequest
metadata:
  name: restart-after-reconfig
  namespace: default
spec:
  clusterName: mysql-cluster
  type: Restart
  restart:
    - componentName: mysql
EOF
```

## Documentation Links

| Resource | URL |
|----------|-----|
| MySQL lifecycle | https://kubeblocks.io/docs/preview/kubeblocks-for-mysql/04-operations/01-stop_start_restart |
| PostgreSQL lifecycle | https://kubeblocks.io/docs/preview/kubeblocks-for-postgresql/04-operations/01-stop-start-restart |
| Redis lifecycle | https://kubeblocks.io/docs/preview/kubeblocks-for-redis/04-operations/01-stop-start-restart |
| MongoDB lifecycle | https://kubeblocks.io/docs/preview/kubeblocks-for-mongodb/04-operations/01-stop-start-restart |
| Kafka lifecycle | https://kubeblocks.io/docs/preview/kubeblocks-for-kafka/04-operations/01-stop-start-restart |
| Operations API | https://kubeblocks.io/docs/preview/user_docs/references/api-reference/operations |


path: skills/kubeblocks-configure-tls/references/reference.md
content: # Configure TLS Reference

## TLS Modes Overview

| Mode | Issuer Name | cert-manager Required | CA Management | Best For |
|------|-------------|----------------------|---------------|----------|
| Built-in | `KubeBlocks` | Yes | Automatic (self-signed) | Dev/test, quick setup |
| User-provided | `UserProvided` | No | Manual (your PKI) | Production with existing CA |
| mTLS | Either | Depends | Server + client certs | High-security, zero-trust |

## Cluster CR TLS Configuration

### Built-in TLS (KubeBlocks-managed)

```yaml
apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
  name: my-cluster
  namespace: default
spec:
  componentSpecs:
    - name: mysql
      tls: true
      issuer:
        name: KubeBlocks
```

### User-provided TLS

```yaml
apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
  name: my-cluster
  namespace: default
spec:
  componentSpecs:
    - name: mysql
      tls: true
      issuer:
        name: UserProvided
        secretRef:
          name: my-cluster-tls
          ca: ca.crt
          cert: tls.crt
          key: tls.key
```

## Creating TLS Secrets

### From existing certificate files

```bash
kubectl create secret generic my-cluster-tls -n default \
  --from-file=ca.crt=ca.crt \
  --from-file=tls.crt=server.crt \
  --from-file=tls.key=server.key
```

### Full certificate generation workflow

```bash
# 1. Generate CA
openssl genrsa -out ca.key 4096
openssl req -x509 -new -nodes -key ca.key \
  -subj "/CN=KubeBlocksCA/O=MyOrg" -days 3650 -out ca.crt

# 2. Generate server key
openssl genrsa -out server.key 2048

# 3. Create SAN config (critical for proper cert validation)
cat > san.cnf <<SANEOF
[req]
distinguished_name = req_dn
req_extensions = v3_req

[req_dn]
CN = my-cluster-mysql

[v3_req]
subjectAltName = @alt_names

[alt_names]
DNS.1 = *.my-cluster-mysql-headless.default.svc.cluster.local
DNS.2 = *.my-cluster-mysql.default.svc.cluster.local
DNS.3 = my-cluster-mysql-headless.default.svc.cluster.local
DNS.4 = localhost
IP.1 = 127.0.0.1
SANEOF

# 4. Generate CSR and sign
openssl req -new -key server.key -subj "/CN=my-cluster-mysql" \
  -config san.cnf -out server.csr
openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key \
  -CAcreateserial -out server.crt -days 365 \
  -extensions v3_req -extfile san.cnf

# 5. Create secret
kubectl create secret generic my-cluster-tls -n default \
  --from-file=ca.crt=ca.crt \
  --from-file=tls.crt=server.crt \
  --from-file=tls.key=server.key
```

### Client certificate generation (for mTLS)

```bash
openssl genrsa -out client.key 2048
openssl req -new -key client.key -subj "/CN=dbclient/O=MyOrg" -out client.csr
openssl x509 -req -in client.csr -CA ca.crt -CAkey ca.key \
  -CAcreateserial -out client.crt -days 365
```

## Engine-Specific TLS Details

### MySQL

- Mount path: `/var/run/secrets/tls/`
- Config parameters set automatically: `ssl_ca`, `ssl_cert`, `ssl_key`, `require_secure_transport`
- Verify TLS:
  ```sql
  SHOW VARIABLES LIKE '%ssl%';
  SHOW STATUS LIKE 'Ssl_cipher';
  ```
- Connect with TLS:
  ```bash
  mysql -h <host> -P 3306 -u root -p --ssl-mode=REQUIRED \
    --ssl-ca=ca.crt --ssl-cert=client.crt --ssl-key=client.key
  ```
- Require X509 for specific users:
  ```sql
  CREATE USER 'secureuser'@'%' REQUIRE X509;
  ALTER USER 'secureuser'@'%' REQUIRE X509;
  ```

### PostgreSQL

- Mount path: `/var/run/secrets/tls/`
- Config parameters set automatically: `ssl = on`, `ssl_ca_file`, `ssl_cert_file`, `ssl_key_file`
- Verify TLS:
  ```sql
  SHOW ssl;
  SELECT * FROM pg_stat_ssl;
  ```
- Connect with TLS:
  ```bash
  psql "host=<host> port=5432 user=postgres dbname=postgres \
    sslmode=verify-full sslrootcert=ca.crt sslcert=client.crt sslkey=client.key"
  ```
- pg_hba.conf for mTLS: set `clientcert=verify-full` via reconfigure-parameters

### Redis

- Redis TLS support depends on the addon version
- Config parameters: `tls-port`, `tls-cert-file`, `tls-key-file`, `tls-ca-cert-file`
- Connect with TLS:
  ```bash
  redis-cli -h <host> -p 6380 --tls \
    --cacert ca.crt --cert client.crt --key client.key
  ```

### MongoDB

- Config parameters set automatically: `net.tls.mode`, `net.tls.certificateKeyFile`, `net.tls.CAFile`
- Connect with TLS:
  ```bash
  mongosh "mongodb://<host>:27017/?tls=true" \
    --tlsCAFile ca.crt --tlsCertificateKeyFile client.pem
  ```

## cert-manager Prerequisites

### Install cert-manager

```bash
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/latest/download/cert-manager.yaml
kubectl wait --for=condition=Ready pods --all -n cert-manager --timeout=120s
```

### Verify cert-manager

```bash
kubectl get pods -n cert-manager
# Expected: cert-manager, cert-manager-cainjector, cert-manager-webhook all Running
```

## Certificate Inspection Commands

```bash
# View mounted certificates in a pod
kubectl exec -it <pod> -n <ns> -- ls -la /var/run/secrets/tls/

# View certificate details
kubectl exec -it <pod> -n <ns> -- \
  openssl x509 -in /var/run/secrets/tls/tls.crt -text -noout

# Check certificate expiration
kubectl exec -it <pod> -n <ns> -- \
  openssl x509 -in /var/run/secrets/tls/tls.crt -enddate -noout

# Verify certificate chain
openssl verify -CAfile ca.crt server.crt
```

## Troubleshooting

### Common Issues

| Symptom | Cause | Fix |
|---------|-------|-----|
| Pod CrashLoopBackOff after enabling TLS | Secret missing or wrong key names | Verify secret exists with `ca.crt`, `tls.crt`, `tls.key` |
| `certificate verify failed` | CA mismatch between client and server | Ensure client uses the same CA that signed the server cert |
| `SSL: no alternative certificate subject name matches` | Missing SAN entries | Regenerate cert with correct DNS SANs for the headless service |
| cert-manager not issuing certificates | cert-manager not installed or not running | Install cert-manager and verify pods are running |
| Certificate expired | Built-in: cert-manager renewal failed; User-provided: manual renewal needed | Check cert-manager logs or regenerate certs |

## Documentation Links

| Resource | URL |
|----------|-----|
| MySQL TLS overview | https://kubeblocks.io/docs/preview/kubeblocks-for-mysql/07-tls/01-tls-overview |
| MySQL custom TLS certs | https://kubeblocks.io/docs/preview/kubeblocks-for-mysql/07-tls/02-tls-custom-cert |
| MySQL mTLS | https://kubeblocks.io/docs/preview/kubeblocks-for-mysql/07-tls/03-mtls |
| PostgreSQL TLS overview | https://kubeblocks.io/docs/preview/kubeblocks-for-postgresql/07-tls/01-tls-overview |
| PostgreSQL custom TLS | https://kubeblocks.io/docs/preview/kubeblocks-for-postgresql/07-tls/02-tls-custom-cert |


path: skills/kubeblocks-create-cluster/references/reference.md
content: # Create Cluster Reference

Detailed Cluster CR fields, terminationPolicy comparison, and addon quick-start examples.

Source: https://kubeblocks.io/docs/preview/user_docs/kubeblocks-for-mysql/cluster-management/create-and-connect-a-mysql-cluster

## Cluster CR Field Reference

### metadata

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | Cluster name. Must be unique within the namespace. |
| `namespace` | string | Yes | Kubernetes namespace to create the cluster in. |
| `labels` | map | No | Custom labels for the cluster. |
| `annotations` | map | No | Custom annotations for the cluster. |

### spec

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `clusterDef` | string | Yes | Name of the ClusterDefinition (e.g., `mysql`, `postgresql`, `redis`). |
| `topology` | string | Yes | Topology name defined in the ClusterDefinition. Determines the component layout. |
| `terminationPolicy` | string | Yes | Controls what happens on cluster deletion. One of: `DoNotTerminate`, `Delete`, `WipeOut`. |
| `componentSpecs` | []ComponentSpec | Yes | List of component specifications. |
| `services` | []Service | No | Additional cluster-level services to expose. |
| `backup` | BackupSpec | No | Backup configuration for the cluster. |
| `schedulingPolicy` | SchedulingPolicy | No | Scheduling constraints (nodeSelector, tolerations, affinity). |

### spec.componentSpecs[]

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | Component name. Must match a component defined in the topology. |
| `serviceVersion` | string | No | Database engine version (e.g., `"8.0.30"`, `"14.8.0"`). |
| `replicas` | int | Yes | Number of replicas for this component. |
| `resources` | ResourceRequirements | No | CPU and memory requests/limits. |
| `volumeClaimTemplates` | []VolumeClaimTemplate | No | Persistent volume claims for this component. |
| `serviceAccountName` | string | No | Custom ServiceAccount for the component pods. |
| `services` | []Service | No | Component-level service overrides. |
| `systemAccounts` | []SystemAccount | No | Override system account credentials. |
| `schedulingPolicy` | SchedulingPolicy | No | Component-level scheduling constraints. |
| `configs` | []ConfigTemplate | No | Custom configuration template overrides. |

### spec.componentSpecs[].resources

| Field | Type | Description |
|-------|------|-------------|
| `requests.cpu` | string | Minimum CPU (e.g., `"0.5"`, `"2"`). |
| `requests.memory` | string | Minimum memory (e.g., `"0.5Gi"`, `"4Gi"`). |
| `limits.cpu` | string | Maximum CPU. |
| `limits.memory` | string | Maximum memory. |

### spec.componentSpecs[].volumeClaimTemplates[]

| Field | Type | Description |
|-------|------|-------------|
| `name` | string | Volume name. Typically `data`. Some addons also use `log` or `metadata`. |
| `spec.accessModes` | []string | Access modes. Usually `[ReadWriteOnce]`. |
| `spec.storageClassName` | string | StorageClass name. Defaults to the cluster default StorageClass. |
| `spec.resources.requests.storage` | string | Storage size (e.g., `"20Gi"`, `"100Gi"`). |

### spec.schedulingPolicy

| Field | Type | Description |
|-------|------|-------------|
| `nodeSelector` | map | Node labels for scheduling. |
| `tolerations` | []Toleration | Pod tolerations. |
| `affinity` | Affinity | Pod affinity/anti-affinity rules. |
| `topologySpreadConstraints` | []TopologySpreadConstraint | Topology spread constraints. |

## terminationPolicy Comparison

| Policy | Delete Pods | Delete PVCs | Delete Backups | Blocks `kubectl delete` |
|--------|:-----------:|:-----------:|:--------------:|:----------------------:|
| `DoNotTerminate` | No | No | No | Yes |
| `Delete` | Yes | Yes | No | No |
| `WipeOut` | Yes | Yes | Yes | No |

**Guidance:**
- **Production:** Use `DoNotTerminate`. Requires explicit policy change before deletion.
- **Dev / Test:** Use `Delete`. Cleans up resources but retains backups.
- **Disposable / CI:** Use `WipeOut`. Removes everything.

To change the policy on an existing cluster:

```bash
kubectl patch cluster <name> -n <ns> --type merge -p '{"spec":{"terminationPolicy":"Delete"}}'
```

## Common Addon Quick-Start Table

Full field values for the most common addons:

### MySQL (ApeCloud — recommended)

```yaml
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
```

### MySQL (Community — replication)

```yaml
apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
  name: mysql-community
  namespace: default
spec:
  clusterDef: mysql
  topology: mysql-replication
  terminationPolicy: Delete
  componentSpecs:
    - name: mysql
      serviceVersion: "8.0.33"
      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
```

### PostgreSQL

```yaml
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
```

### Redis (Cluster mode)

```yaml
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: 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
```

### Redis (Standalone / Replication)

```yaml
apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
  name: redis-standalone
  namespace: default
spec:
  clusterDef: redis
  topology: redis
  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
```

### MongoDB (ReplicaSet)

```yaml
apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
  name: mongo-cluster
  namespace: default
spec:
  clusterDef: mongodb
  topology: mongodb-replicaset
  terminationPolicy: Delete
  componentSpecs:
    - name: mongodb
      serviceVersion: "6.0.16"
      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
```

### Kafka (Combined mode)

```yaml
apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
  name: kafka-cluster
  namespace: default
spec:
  clusterDef: kafka
  topology: kafka-combined
  terminationPolicy: Delete
  componentSpecs:
    - name: kafka-combine
      serviceVersion: "3.7.2"
      replicas: 3
      resources:
        limits:
          cpu: "0.5"
          memory: "1Gi"
        requests:
          cpu: "0.5"
          memory: "1Gi"
      volumeClaimTemplates:
        - name: data
          spec:
            accessModes: [ReadWriteOnce]
            resources:
              requests:
                storage: 20Gi
        - name: metadata
          spec:
            accessModes: [ReadWriteOnce]
            resources:
              requests:
                storage: 5Gi
```

## Volume Name Reference

Different addons use different volume names:

| Addon | Volume Names | Description |
|-------|-------------|-------------|
| MySQL | `data` | Data directory |
| PostgreSQL | `data` | Data directory |
| Redis | `data` | Data directory |
| MongoDB | `data` | Data directory |
| Kafka | `data`, `metadata` | Data logs and metadata |

## Listing Available ClusterDefinitions and Topologies

```bash
kubectl get clusterdefinitions

kubectl get clusterdefinitions <name> -o yaml | grep -A 20 'topologies:'
```

## Listing Available Component Versions

```bash
kubectl get componentversions
```

## Documentation Links

- Cluster Management: https://kubeblocks.io/docs/preview/user_docs/kubeblocks-for-mysql/cluster-management/create-and-connect-a-mysql-cluster
- Supported Addons: https://kubeblocks.io/docs/preview/user_docs/overview/supported-addons
- Full Doc Index: https://kubeblocks.io/llms-full.txt


path: skills/kubeblocks-expose-service/references/reference.md
content: # Expose Service Reference

## OpsRequest API Reference

Full API docs: https://kubeblocks.io/docs/preview/user_docs/references/api-reference/operations

### Enable External Access

```yaml
apiVersion: operations.kubeblocks.io/v1alpha1
kind: OpsRequest
metadata:
  name: <cluster>-expose
  namespace: <ns>
spec:
  clusterName: <cluster>
  type: Expose
  expose:
    - componentName: <component>
      switch: Enable
      services:
        - name: <cluster>-<component>-internet
          roleSelector: primary
          serviceType: LoadBalancer
```

### Disable External Access

```yaml
apiVersion: operations.kubeblocks.io/v1alpha1
kind: OpsRequest
metadata:
  name: <cluster>-unexpose
  namespace: <ns>
spec:
  clusterName: <cluster>
  type: Expose
  expose:
    - componentName: <component>
      switch: Disable
      services:
        - name: <cluster>-<component>-internet
          roleSelector: primary
          serviceType: LoadBalancer
```

## Service Types

| Type | External IP | Port Range | Use Case |
|------|------------|------------|----------|
| LoadBalancer | Cloud LB assigns public/private IP | Any | Cloud environments (AWS, Azure, GCP, Alibaba) |
| NodePort | Node IP + assigned port | 30000-32767 | On-premises, bare-metal, local dev |
| ClusterIP | None (internal only) | Any | Default, no action needed |

## Role Selectors

| roleSelector | Behavior | Use Case |
|-------------|----------|----------|
| `primary` | Routes to the current primary/leader node | Read-write access, single endpoint |
| (omitted) | Routes to all pods in the component | Read scaling with client-side routing |

## Cloud Provider Annotations

### AWS (Network Load Balancer)

```yaml
annotations:
  service.beta.kubernetes.io/aws-load-balancer-type: nlb
  service.beta.kubernetes.io/aws-load-balancer-internal: "false"
```

Internal NLB (VPC-only access):

```yaml
annotations:
  service.beta.kubernetes.io/aws-load-balancer-type: nlb
  service.beta.kubernetes.io/aws-load-balancer-internal: "true"
```

### Azure

```yaml
annotations:
  service.beta.kubernetes.io/azure-load-balancer-internal: "false"
```

Internal LB:

```yaml
annotations:
  service.beta.kubernetes.io/azure-load-balancer-internal: "true"
```

### GCP

```yaml
annotations:
  networking.gke.io/load-balancer-type: External
```

Internal LB:

```yaml
annotations:
  networking.gke.io/load-balancer-type: Internal
```

### Alibaba Cloud

Internet-facing:

```yaml
annotations:
  service.beta.kubernetes.io/alibaba-cloud-loadbalancer-address-type: internet
```

Intranet (VPC-only):

```yaml
annotations:
  service.beta.kubernetes.io/alibaba-cloud-loadbalancer-address-type: intranet
```

## Engine-Specific Default Ports

| Engine | Default Port | Service Name Pattern |
|--------|-------------|---------------------|
| MySQL | 3306 | `<cluster>-mysql-internet` |
| PostgreSQL | 5432 | `<cluster>-postgresql-internet` |
| Redis | 6379 | `<cluster>-redis-internet` |
| MongoDB | 27017 | `<cluster>-mongodb-internet` |
| Kafka | 9092 | `<cluster>-kafka-combine-internet` |
| Elasticsearch | 9200 | `<cluster>-elasticsearch-internet` |

## Exposing Multiple Components

You can expose multiple components in a single OpsRequest:

```yaml
spec:
  clusterName: my-cluster
  type: Expose
  expose:
    - componentName: mysql
      switch: Enable
      services:
        - name: my-cluster-mysql-internet
          roleSelector: primary
          serviceType: LoadBalancer
    - componentName: proxysql
      switch: Enable
      services:
        - name: my-cluster-proxysql-internet
          serviceType: LoadBalancer
```

## Exposing Read Replicas

To expose read replicas separately for read-scaling:

```yaml
  expose:
    - componentName: mysql
      switch: Enable
      services:
        - name: my-cluster-mysql-primary
          roleSelector: primary
          serviceType: LoadBalancer
        - name: my-cluster-mysql-readonly
          roleSelector: secondary
          serviceType: LoadBalancer
```

## Connection Examples After Exposure

### LoadBalancer

```bash
# Get the external IP
kubectl get svc -n <ns> | grep internet

# MySQL
mysql -h <EXTERNAL-IP> -P 3306 -u root -p

# PostgreSQL
psql -h <EXTERNAL-IP> -p 5432 -U postgres

# Redis
redis-cli -h <EXTERNAL-IP> -p 6379 -a <password>

# MongoDB
mongosh "mongodb://<user>:<password>@<EXTERNAL-IP>:27017"
```

### NodePort

```bash
# Get node IP and assigned port
NODE_IP=$(kubectl get nodes -o jsonpath='{.items[0].status.addresses[?(@.type=="InternalIP")].address}')
NODE_PORT=$(kubectl get svc <svc-name> -n <ns> -o jsonpath='{.spec.ports[0].nodePort}')

mysql -h $NODE_IP -P $NODE_PORT -u root -p
```

## Local Development (No Cloud LB)

For local Kind/Minikube/k3d clusters without a cloud LB controller:

**Option 1: Use NodePort instead of LoadBalancer**

**Option 2: Install MetalLB for local LoadBalancer support**

```bash
kubectl apply -f https://raw.githubusercontent.com/metallb/metallb/v0.14.9/config/manifests/metallb-native.yaml
kubectl wait --for=condition=Ready pods --all -n metallb-system --timeout=120s
```

Then configure an IP address pool matching your local network.

**Option 3: Use kubectl port-forward (simplest for development)**

```bash
kubectl port-forward svc/<cluster>-<component> -n <ns> <local-port>:<db-port>
```

## Security Considerations

- LoadBalancer services are **publicly accessible** by default on cloud providers
- Use internal LB annotations for VPC-only access when possible
- Always combine with TLS (see configure-tls skill) for encrypted connections
- Set firewall rules / security groups to restrict source IPs
- Consider using Kubernetes NetworkPolicies for additional access control

## Troubleshooting

| Symptom | Cause | Fix |
|---------|-------|-----|
| `EXTERNAL-IP` stuck in `<pending>` | No LB controller (local cluster) or cloud quota | Use NodePort, install MetalLB, or check cloud quotas |
| Connection timeout | Firewall/security group blocking | Open the database port in cloud security groups |
| Service exists but no endpoints | Pod selector mismatch or pods not running | Check pod status and labels |
| Wrong node receives traffic (NodePort) | Normal — NodePort routes via kube-proxy | Use `externalTrafficPolicy: Local` for direct routing |

## Documentation Links

| Resource | URL |
|----------|-----|
| MySQL expose service | https://kubeblocks.io/docs/preview/kubeblocks-for-mysql/04-operations/05-manage-loadbalancer |
| PostgreSQL expose service | https://kubeblocks.io/docs/preview/kubeblocks-for-postgresql/04-operations/05-manage-loadbalancer |
| Redis expose service | https://kubeblocks.io/docs/preview/kubeblocks-for-redis/04-operations/05-manage-loadbalancer |
| MongoDB expose service | https://kubeblocks.io/docs/preview/kubeblocks-for-mongodb/04-operations/05-manage-loadbalancer |
| Kafka expose service | https://kubeblocks.io/docs/preview/kubeblocks-for-kafka/04-operations/05-manage-loadbalancer |
| Redis network modes blog | https://kubeblocks.io/blog/5-network-modes-for-kubeblocks-for-redis |
| Operations API | https://kubeblocks.io/docs/preview/user_docs/references/api-reference/operations |


path: skills/kubeblocks-horizontal-scaling/references/reference.md
content: # Horizontal Scaling Reference

## OpsRequest API Reference

Full API docs: https://kubeblocks.io/docs/preview/user_docs/references/api-reference/operations

### Scale Out

```yaml
apiVersion: apps.kubeblocks.io/v1beta1
kind: OpsRequest
metadata:
  name: scaleout-<cluster>
  namespace: <ns>
spec:
  clusterName: <cluster>
  type: HorizontalScaling
  horizontalScaling:
    - componentName: <component>
      scaleOut:
        replicaChanges: <count>
```

### Scale In

```yaml
apiVersion: apps.kubeblocks.io/v1beta1
kind: OpsRequest
metadata:
  name: scalein-<cluster>
  namespace: <ns>
spec:
  clusterName: <cluster>
  type: HorizontalScaling
  horizontalScaling:
    - componentName: <component>
      scaleIn:
        replicaChanges: <count>
```

### Decommission Specific Instances

```yaml
  horizontalScaling:
    - componentName: <component>
      scaleIn:
        replicaChanges: <count>
        onlineInstancesToOffline:
          - "<pod-name-1>"
          - "<pod-name-2>"
```

## Engine-Specific Scaling Behaviors

### MySQL

| Topology | Component | Min Replicas | Scaling Notes |
|----------|-----------|-------------|---------------|
| Semi-sync | `mysql` | 2 | New replicas auto-join as secondaries. Semi-sync replication configured automatically. |
| MGR (Group Replication) | `mysql` | 3 | Raft-based consensus requires odd numbers. Min 3 for fault tolerance. |
| Orchestrator | `mysql` | 2 | Orchestrator auto-discovers and manages new replicas. |

- Scale-out: new replicas provision from backup or full clone of primary
- Scale-in: cannot remove the primary; switchover happens automatically if needed
- Docs: https://kubeblocks.io/docs/preview/kubeblocks-for-mysql/04-operations/03-horizontal-scaling

### PostgreSQL

| Topology | Component | Min Replicas | Scaling Notes |
|----------|-----------|-------------|---------------|
| Patroni replication | `postgresql` | 1 | Patroni manages replication slots and leader election. |

- Scale-out: new replicas stream from primary via pg_basebackup
- Scale-in: Patroni handles slot cleanup; cannot remove current leader
- Docs: https://kubeblocks.io/docs/preview/kubeblocks-for-postgresql/04-operations/03-horizontal-scaling

### Redis

| Topology | Component | Min Replicas | Scaling Notes |
|----------|-----------|-------------|---------------|
| Standalone | `redis` | 1 | Cannot scale (single instance) |
| Replication | `redis` | 2 | Sentinel manages failover. Min 1 primary + 1 replica. |
| Cluster (sharding) | `redis-shard` | 3 shards | Each shard = 1 primary + N replicas. Auto-resharding on scale. |

- **Replication topology**: scaling adds/removes read replicas
- **Cluster topology**: scaling adds/removes entire shard groups
  - Scale-out: new shard created, hash slots automatically redistributed
  - Scale-in: data migrated from removed shard, then shard terminated
  - Monitor resharding: `redis-cli --cluster check <host>:<port>`
- Docs: https://kubeblocks.io/docs/preview/kubeblocks-for-redis/04-operations/03-horizontal-scaling

### MongoDB

| Topology | Component | Min Replicas | Scaling Notes |
|----------|-----------|-------------|---------------|
| ReplicaSet | `mongodb` | 1 | New members auto-join the replica set. |
| Sharding — mongos | `mongos` | 1 | Stateless query routers, safe to scale freely. |
| Sharding — configsvr | `configsvr` | 3 | Config servers, typically stay at 3. |
| Sharding — shard | `shard` | 1+ | Each shard is a replica set. |

- **ReplicaSet**: scaling adds/removes secondaries
- **Sharding**: scaling the `shard` component adds/removes entire shard groups
  - The MongoDB balancer auto-redistributes chunks after shard changes
  - Large datasets may take significant time to rebalance
  - Monitor: `db.adminCommand({ balancerStatus: 1 })` inside mongos
- Docs: https://kubeblocks.io/docs/preview/kubeblocks-for-mongodb/04-operations/03-horizontal-scaling

### Kafka

| Topology | Component | Min Replicas | Scaling Notes |
|----------|-----------|-------------|---------------|
| Combined | `kafka-combine` | 1 | Broker + controller co-located |
| Separated — broker | `kafka-broker` | 1 | Data brokers only |
| Separated — controller | `kafka-controller` | 3 | Raft-based, odd numbers recommended |

- Scale-out: new brokers join the cluster, but existing topic partitions are NOT automatically rebalanced
- Scale-in: remove only brokers with no partition assignments (or reassign first)
- Partition reassignment must be done manually or via tools like `kafka-reassign-partitions.sh`
- Docs: https://kubeblocks.io/docs/preview/kubeblocks-for-kafka/04-operations/03-horizontal-scaling

### Elasticsearch

| Topology | Component | Min Replicas | Scaling Notes |
|----------|-----------|-------------|---------------|
| Default | `elasticsearch` | 1 | New nodes auto-join. Shard rebalancing is automatic. |

- Docs: https://kubeblocks.io/docs/preview/kubeblocks-for-elasticsearch/04-operations/03-horizontal-scaling

## kubectl Patch Alternative

For simple replica count changes without OpsRequest:

```bash
kubectl patch cluster <cluster> -n <ns> \
  --type merge \
  -p '{"spec":{"componentSpecs":[{"name":"<component>","replicas":<new-total>}]}}'
```

This sets the absolute replica count (not a delta).

## Replicas vs Shards: Key Differences

| Concept | Replicas | Shards |
|---------|----------|--------|
| Data model | Each replica holds a full copy of data | Each shard holds a subset (partition) of data |
| Purpose | High availability, read scaling | Horizontal data partitioning, write scaling |
| Engines | All engines | Redis Cluster, MongoDB Sharding |
| Scaling effect | More read capacity, better HA | More storage capacity, more write throughput |
| Data movement | New replica syncs full dataset | Hash slots / chunks redistribute across shards |

## Decommissioning Specific Instances

When scaling in, by default KubeBlocks removes the last-created instance. To choose a specific instance:

```yaml
  horizontalScaling:
    - componentName: mysql
      scaleIn:
        replicaChanges: 1
        onlineInstancesToOffline:
          - "mysql-cluster-mysql-2"
```

Use cases:
- Remove a replica on a specific node being decommissioned
- Remove an unhealthy instance
- Remove an instance in a specific availability zone

Docs: https://kubeblocks.io/blog/take-specified-instances-offline

## Pre-scaling Checklist

- [ ] Sufficient node resources for new pods (CPU, memory, storage)
- [ ] StorageClass can provision new PVCs
- [ ] For scale-in: verify the cluster won't go below the minimum replica count for its topology
- [ ] For sharding: ensure data rebalancing time is acceptable for your SLA

## Documentation Links

| Resource | URL |
|----------|-----|
| MySQL horizontal scaling | https://kubeblocks.io/docs/preview/kubeblocks-for-mysql/04-operations/03-horizontal-scaling |
| PostgreSQL horizontal scaling | https://kubeblocks.io/docs/preview/kubeblocks-for-postgresql/04-operations/03-horizontal-scaling |
| Redis horizontal scaling | https://kubeblocks.io/docs/preview/kubeblocks-for-redis/04-operations/03-horizontal-scaling |
| MongoDB horizontal scaling | https://kubeblocks.io/docs/preview/kubeblocks-for-mongodb/04-operations/03-horizontal-scaling |
| Kafka horizontal scaling | https://kubeblocks.io/docs/preview/kubeblocks-for-kafka/04-operations/03-horizontal-scaling |
| Elasticsearch horizontal scaling | https://kubeblocks.io/docs/preview/kubeblocks-for-elasticsearch/04-operations/03-horizontal-scaling |
| Milvus horizontal scaling | https://kubeblocks.io/docs/preview/kubeblocks-for-milvus/04-operations/03-horizontal-scaling |
| Decommission specific instance | https://kubeblocks.io/blog/take-specified-instances-offline |
| Operations API | https://kubeblocks.io/docs/preview/user_docs/references/api-reference/operations |


path: skills/kubeblocks-install/references/reference.md
content: # KubeBlocks Installation Reference

Detailed options, configurations, and procedures for KubeBlocks installation.

Source: https://kubeblocks.io/docs/preview/user_docs/references/kubeblocks_options

## Helm Chart Options

To view all available options for a specific version:

```bash
helm show values kubeblocks/kubeblocks --version {VERSION}
```

### KubeBlocks Core Options

| Parameter | Description | Default |
|-----------|-------------|---------|
| `image.registry` | KubeBlocks image registry | `apecloud-registry.cn-zhangjiakou.cr.aliyuncs.com` |
| `image.repository` | KubeBlocks image repository | `apecloud/kubeblocks` |
| `image.pullPolicy` | Image pull policy | `IfNotPresent` |
| `image.tag` | Image tag (defaults to chart appVersion) | `""` |
| `image.imagePullSecrets` | Image pull secrets | `[]` |
| `replicaCount` | Replica count | `1` |

### Data Protection Options

| Parameter | Description | Default |
|-----------|-------------|---------|
| `dataProtection.enabled` | Enable data protection controllers | `true` |
| `dataProtection.image.registry` | Data protection image registry | `""` (uses `image.registry`) |
| `dataProtection.image.repository` | Data protection image repository | `apecloud/kubeblocks-dataprotection` |
| `dataProtection.enableBackupEncryption` | Enable backup encryption | `false` |
| `dataProtection.gcFrequencySeconds` | Garbage collection frequency | `3600` |

### Addon Options

| Parameter | Description | Default |
|-----------|-------------|---------|
| `addonController.enabled` | Enable Addon controller (requires `cluster-admin` ClusterRole) | `true` |
| `addonChartsImage.registry` | Addon charts image registry | `""` (uses `image.registry`) |
| `addonChartsImage.repository` | Addon charts image repository | `apecloud/kubeblocks-charts` |
| `autoInstalledAddons` | Addons to auto-install | `["apecloud-mysql","etcd","kafka","mongodb","mysql","postgresql","qdrant","redis","rabbitmq"]` |
| `keepAddons` | Keep Addon CRs when uninstalling | `true` |

### Feature Gates

| Parameter | Description | Default |
|-----------|-------------|---------|
| `featureGates.inPlacePodVerticalScaling.enabled` | Enable in-place Pod vertical scaling | `false` |

### Controller Options

| Parameter | Description | Default |
|-----------|-------------|---------|
| `controllers.apps.enabled` | Enable apps controller | `true` |
| `controllers.workloads.enabled` | Enable workloads controller | `true` |
| `controllers.operations.enabled` | Enable operations controller | `true` |
| `controllers.experimental.enabled` | Enable experimental controller | `false` |

## Image Registry Reference

### Global (default for non-China environments)

```
registry: docker.io
namespace: apecloud
```

Example full image: `docker.io/apecloud/kubeblocks:{VERSION}`

### China Mainland Mirror

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

Example full image: `apecloud-registry.cn-zhangjiakou.cr.aliyuncs.com/apecloud/kubeblocks:{VERSION}`

### Alternative Helm Repository for China

If GitHub Pages is slow, use the JiHuLab mirror for addon charts:

```bash
helm repo add kubeblocks-addons https://jihulab.com/api/v4/projects/150246/packages/helm/stable
```

## Managing Addons

After KubeBlocks is installed, some addons are auto-installed by default. To manage addons:

### List Installed Addons

```bash
helm list -n kb-system | grep kb-addon
```

### Install an Additional Addon

```bash
# View available versions
helm search repo kubeblocks/{addon-name} --versions

# Install
helm install kb-addon-{addon-name} kubeblocks/{addon-name} \
  --namespace kb-system --create-namespace \
  --version {ADDON_VERSION}
```

Addon version must match KubeBlocks major version (e.g., KubeBlocks v1.0.x with Addon v1.0.x).

### Uninstall an Addon

```bash
helm uninstall kb-addon-{addon-name} --namespace kb-system
```

## Detailed Uninstall Procedure

### Step 1: Delete All Clusters and Backups

```bash
kubectl get cluster -A
kubectl get backup -A

kubectl delete cluster <name> -n <namespace>
kubectl delete backup <name> -n <namespace>
```

### Step 2: Uninstall All Addons

```bash
helm list -n kb-system | grep kb-addon | awk '{print $1}' | xargs -I {} helm -n kb-system uninstall {}
```

### Step 3: Clean Up Remaining Resources

Some resources are kept due to Helm resource policy. Remove them:

```bash
kubectl delete componentdefinitions.apps.kubeblocks.io --all
kubectl delete parametersdefinitions.parameters.kubeblocks.io --all
kubectl get configmap -n kb-system | grep configuration | awk '{print $1}' | xargs -I {} kubectl delete -n kb-system cm {}
kubectl get configmap -n kb-system | grep template | awk '{print $1}' | xargs -I {} kubectl delete -n kb-system cm {}
kubectl delete addon.extensions.kubeblocks.io --all
```

### Step 4: Uninstall KubeBlocks

```bash
helm uninstall kubeblocks --namespace kb-system
```

### Step 5: Remove CRDs

```bash
kubectl get crd -o name | grep kubeblocks.io | xargs kubectl delete
```

### Step 6: Verify Clean Removal

```bash
kubectl get crd | grep kubeblocks.io | awk '{print $1}' | while read crd; do
  echo "Processing CRD: $crd"
  kubectl get "$crd" -o json | jq '.items[] | select(.metadata.finalizers != null) | .metadata.name' -r | while read resource; do
    echo "Custom Resource left: $resource in CRD: $crd"
  done
done
```

The output should be empty if everything is cleaned up.

## Upgrading KubeBlocks

```bash
# Update Helm repo
helm repo update

# Upgrade KubeBlocks
helm upgrade kubeblocks kubeblocks/kubeblocks \
  --namespace kb-system \
  --version {NEW_VERSION}
```

For major version upgrades (e.g., v0.9.x to v1.0.x), refer to:
https://kubeblocks.io/docs/preview/user_docs/upgrade/upgrade-to-v10x

## Creating a Local Test Cluster

If the user has no Kubernetes cluster, use the [create-local-k8s-cluster](../../kubeblocks-create-local-k8s-cluster/SKILL.md) skill to create one with Kind, Minikube, or k3d.

## Version Compatibility Matrix

| KubeBlocks | Addon Version | kbcli Version | Min K8s |
|------------|---------------|---------------|---------|
| v1.0.x     | v1.0.x        | v1.0.x        | v1.21   |
| v0.9.x     | v0.9.x        | v0.9.x        | v1.21   |
| v0.8.x     | v0.8.x        | v0.8.x        | v1.21   |

Mismatched major versions between KubeBlocks, addons, and kbcli may cause unexpected errors.

## Documentation Links

- Installation: https://kubeblocks.io/docs/preview/user_docs/overview/install-kubeblocks
- Options Reference: https://kubeblocks.io/docs/preview/user_docs/references/kubeblocks_options
- Addons Management: https://kubeblocks.io/docs/preview/user_docs/references/install-addons
- Install kbcli: https://kubeblocks.io/docs/preview/user_docs/references/install-kbcli
- Local K8s Cluster: https://kubeblocks.io/docs/preview/user_docs/references/prepare-a-local-k8s-cluster
- Supported Addons: https://kubeblocks.io/docs/preview/user_docs/overview/supported-addons
- Full Doc Index: https://kubeblocks.io/llms-full.txt
- KubeBlocks GitHub: https://github.com/apecloud/kubeblocks
- KubeBlocks Releases: https://github.com/apecloud/kubeblocks/releases


path: skills/kubeblocks-manage-addons/references/reference.md
content: # KubeBlocks Addons Reference

Complete list of supported database addons and their feature compatibility.

Source: https://kubeblocks.io/docs/preview/user_docs/overview/supported-addons

## Supported Addons by Category

### Relational Databases

| Addon | Engine | Helm Chart Name |
|---|---|---|
| MySQL | MySQL Community | `mysql` |
| ApeCloud MySQL | ApeCloud MySQL (Raft-based HA) | `apecloud-mysql` |
| MariaDB | MariaDB | `mariadb` |
| PostgreSQL | PostgreSQL (with Patroni HA) | `postgresql` |
| Vanilla PostgreSQL | PostgreSQL (single-node, no HA) | `vanilla-postgresql` |
| OrioleDB | OrioleDB (PostgreSQL-based) | `orioledb` |

### NoSQL Databases

| Addon | Engine | Helm Chart Name |
|---|---|---|
| MongoDB | MongoDB | `mongodb` |
| Redis | Redis | `redis` |
| etcd | etcd | `etcd` |
| ZooKeeper | Apache ZooKeeper | `zookeeper` |

### OLAP & Search

| Addon | Engine | Helm Chart Name |
|---|---|---|
| Elasticsearch | Elasticsearch | `elasticsearch` |
| OpenSearch | OpenSearch | `opensearch` |
| StarRocks CE | StarRocks Community Edition | `starrocks-ce` |
| ClickHouse | ClickHouse | `clickhouse` |

### Distributed SQL

| Addon | Engine | Helm Chart Name |
|---|---|---|
| TiDB | TiDB (PingCAP) | `tidb` |
| OceanBase CE | OceanBase Community Edition | `oceanbase-ce` |
| PolarDB-X | PolarDB-X (Alibaba) | `polardb-x` |

### Message Queues & Streaming

| Addon | Engine | Helm Chart Name |
|---|---|---|
| Kafka | Apache Kafka | `kafka` |
| RabbitMQ | RabbitMQ | `rabbitmq` |
| Pulsar | Apache Pulsar | `pulsar` |

### Vector Databases

| Addon | Engine | Helm Chart Name |
|---|---|---|
| Qdrant | Qdrant | `qdrant` |
| Weaviate | Weaviate | `weaviate` |
| Milvus | Milvus | `milvus` |

### Time Series Databases

| Addon | Engine | Helm Chart Name |
|---|---|---|
| InfluxDB | InfluxDB | `influxdb` |
| VictoriaMetrics | VictoriaMetrics | `victoria-metrics` |
| GreptimeDB | GreptimeDB | `greptimedb` |
| TDengine | TDengine | `tdengine` |

### Graph Databases

| Addon | Engine | Helm Chart Name |
|---|---|---|
| NebulaGraph | NebulaGraph | `nebula` |

### Object Storage

| Addon | Engine | Helm Chart Name |
|---|---|---|
| MinIO | MinIO | `minio` |

## Feature Compatibility Matrix

The table below shows which KubeBlocks operations are supported for each major addon. Features may vary by topology (e.g., standalone vs. replication vs. cluster mode).

**Legend:** Y = Supported, N = Not supported, - = Not applicable

### Relational Databases

| Feature | MySQL | ApeCloud MySQL | PostgreSQL | MariaDB |
|---|---|---|---|---|
| Vertical Scaling | Y | Y | Y | Y |
| Horizontal Scaling | Y | Y | Y | N |
| Volume Expansion | Y | Y | Y | Y |
| Stop/Start | Y | Y | Y | Y |
| Restart | Y | Y | Y | Y |
| Backup | Y | Y | Y | N |
| Restore | Y | Y | Y | N |
| Point-in-Time Recovery | Y | Y | Y | N |
| Reconfigure Parameters | Y | Y | Y | Y |
| Switchover | Y | Y | Y | N |
| Minor Version Upgrade | Y | Y | Y | N |
| Monitoring | Y | Y | Y | Y |
| Accounts Management | Y | Y | Y | Y |
| TLS | N | Y | Y | N |

### NoSQL Databases

| Feature | MongoDB | Redis | etcd |
|---|---|---|---|
| Vertical Scaling | Y | Y | Y |
| Horizontal Scaling | Y | Y | Y |
| Volume Expansion | Y | Y | Y |
| Stop/Start | Y | Y | Y |
| Restart | Y | Y | Y |
| Backup | Y | Y | N |
| Restore | Y | Y | N |
| Point-in-Time Recovery | Y | N | N |
| Reconfigure Parameters | Y | Y | Y |
| Switchover | Y | N | N |
| Minor Version Upgrade | Y | Y | N |
| Monitoring | Y | Y | Y |
| Accounts Management | Y | Y | N |
| TLS | Y | Y | N |

### Message Queues

| Feature | Kafka | RabbitMQ | Pulsar |
|---|---|---|---|
| Vertical Scaling | Y | Y | Y |
| Horizontal Scaling | Y | Y | Y |
| Volume Expansion | Y | Y | Y |
| Stop/Start | Y | Y | Y |
| Restart | Y | Y | Y |
| Backup | N | N | N |
| Restore | N | N | N |
| Reconfigure Parameters | Y | Y | Y |
| Monitoring | Y | Y | Y |

### Vector Databases

| Feature | Qdrant | Weaviate | Milvus |
|---|---|---|---|
| Vertical Scaling | Y | Y | Y |
| Horizontal Scaling | Y | Y | Y |
| Volume Expansion | Y | Y | Y |
| Stop/Start | Y | Y | Y |
| Restart | Y | Y | Y |
| Backup | Y | N | N |
| Restore | Y | N | N |
| Monitoring | Y | Y | Y |

### OLAP & Search

| Feature | Elasticsearch | StarRocks CE | ClickHouse | OpenSearch |
|---|---|---|---|---|
| Vertical Scaling | Y | Y | Y | Y |
| Horizontal Scaling | Y | Y | Y | Y |
| Volume Expansion | Y | Y | Y | Y |
| Stop/Start | Y | Y | Y | Y |
| Restart | Y | Y | Y | Y |
| Backup | N | N | N | N |
| Restore | N | N | N | N |
| Monitoring | Y | Y | Y | Y |

## Addon Installation Quick Reference

Install any addon with:

```bash
helm install kb-addon-<name> kubeblocks/<chart-name> \
  --namespace kb-system \
  --version <VERSION>
```

Where `<chart-name>` is the "Helm Chart Name" from the tables above, and `<VERSION>` should match your KubeBlocks major version (e.g., `1.0.2` for KubeBlocks v1.0.x).

### Common Addon Install Examples

```bash
# Elasticsearch
helm install kb-addon-elasticsearch kubeblocks/elasticsearch --namespace kb-system --version 1.0.2

# StarRocks CE
helm install kb-addon-starrocks-ce kubeblocks/starrocks-ce --namespace kb-system --version 1.0.2

# Milvus (vector DB)
helm install kb-addon-milvus kubeblocks/milvus --namespace kb-system --version 1.0.2

# ClickHouse
helm install kb-addon-clickhouse kubeblocks/clickhouse --namespace kb-system --version 1.0.2

# TiDB
helm install kb-addon-tidb kubeblocks/tidb --namespace kb-system --version 1.0.2

# OceanBase CE
helm install kb-addon-oceanbase-ce kubeblocks/oceanbase-ce --namespace kb-system --version 1.0.2

# MinIO
helm install kb-addon-minio kubeblocks/minio --namespace kb-system --version 1.0.2
```

## Documentation Links

- Supported Addons: https://kubeblocks.io/docs/preview/user_docs/overview/supported-addons
- Install Addons: https://kubeblocks.io/docs/preview/user_docs/references/install-addons
- Full LLM Index: https://kubeblocks.io/llms-full.txt


path: skills/kubeblocks-restore/references/reference.md
content: # Restore Reference

## Table of Contents

- [Addon-Specific Restore Behaviors](#addon-specific-restore-behaviors)
- [PITR Time Range Details](#pitr-time-range-details)
- [Restore Annotation Schema](#restore-annotation-schema)
- [Volume Restore Policies](#volume-restore-policies)

## Addon-Specific Restore Behaviors

### MySQL

- Full backup method: `xtrabackup`
- Continuous backup method: `archive-binlog` (streams binlogs to BackupRepo)
- PITR supported: Yes — requires both a completed xtrabackup and a running archive-binlog backup
- Restore creates a new cluster; the restored MySQL instance replays binlogs to reach the target timestamp
- Docs: https://kubeblocks.io/docs/preview/kubeblocks-for-mysql/05-backup-restore/05-restoring-from-full-backup
- PITR docs: https://kubeblocks.io/docs/preview/kubeblocks-for-mysql/05-backup-restore/06-restore-with-pitr

### PostgreSQL

- Full backup method: `pg-basebackup`
- Continuous backup method: `wal-archive` (streams WAL segments)
- PITR supported: Yes — requires both a completed pg-basebackup and a running wal-archive backup
- The restored PostgreSQL instance uses `recovery_target_time` in the recovery configuration
- Docs: https://kubeblocks.io/docs/preview/kubeblocks-for-postgresql/05-backup-restore/05-restoring-from-full-backup
- PITR docs: https://kubeblocks.io/docs/preview/kubeblocks-for-postgresql/05-backup-restore/06-restore-with-pitr

### Redis

- Full backup method: `datafile` (RDB dump)
- Continuous backup method: not available for Redis in KubeBlocks
- PITR supported: Limited — Redis PITR depends on AOF if configured; KubeBlocks primarily supports full restores
- Docs: https://kubeblocks.io/docs/preview/kubeblocks-for-redis/05-backup-restore/05-restoring-from-full-backup

### MongoDB

- Full backup method: `datafile`
- Continuous backup method: not available in standard KubeBlocks MongoDB addon
- PITR supported: No (full restore only)
- For replica set restore, the new cluster re-initializes replication from the restored data

### Qdrant

- Full backup method: `datafile`
- PITR supported: No
- Docs: https://kubeblocks.io/docs/preview/kubeblocks-for-qdrant/05-backup-restore/05-restoring-from-full-backup

## PITR Time Range Details

The recoverable time window for PITR is determined by:

1. **Start time**: the completion timestamp of the earliest full backup
2. **End time**: the latest timestamp in the continuous backup's log stream

To find the valid time range:

```bash
# Check continuous backup status
kubectl describe backup <continuous-backup-name> -n <ns>
```

Look for `status.timeRange`:

```yaml
status:
  timeRange:
    start: "2025-01-01T00:00:00Z"
    end: "2025-01-15T14:30:00Z"
```

The `restoreTime` in the restore annotation must fall within `[start, end]`.

If the continuous backup has been running for a while but no full backup exists, PITR is not possible — you need at least one completed full backup as the base.

## Restore Annotation Schema

The restore annotation `kubeblocks.io/restore-from-backup` is a JSON string with this structure:

```json
{
  "<component-name>": {
    "name": "<backup-name>",
    "namespace": "<backup-namespace>",
    "volumeRestorePolicy": "Parallel|Serial",
    "restoreTime": "2025-01-01T12:00:00Z"
  }
}
```

| Field | Required | Description |
|---|---|---|
| `name` | Yes | Name of the Backup CR to restore from |
| `namespace` | Yes | Namespace where the Backup CR lives |
| `volumeRestorePolicy` | No | `Parallel` (default) or `Serial` |
| `restoreTime` | No | RFC 3339 UTC timestamp for PITR; omit for full restore |

Multiple components can be restored simultaneously by adding multiple keys.

## Volume Restore Policies

| Policy | Behavior | When to use |
|---|---|---|
| `Parallel` | Restores all PVCs simultaneously | Default; faster for most cases |
| `Serial` | Restores PVCs one at a time | Use when storage backend has IOPS limits or when restoring very large volumes |

General reference: https://kubeblocks.io/docs/preview/user_docs/concepts/backup-and-restore/restore/restore-data-from-backup-set


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)