compare-operator

name	compare-operator
description	Use when comparing a KubeBlocks addon against reference operators, managed database offerings, or KubeBlocks Enterprise capability baselines and producing a gap report.

Reference resolution: when this source-derived skill mentions docs/..., resolve it from the shared support package beside the installed user skills: ~/.codex/skills/kubeblocks-addon-source-docs/docs/... for Codex or ~/.claude/skills/kubeblocks-addon-source-docs/docs/... for Claude Code. In the shared kubeblocks-addon-docs checkout, the same files live under skills/kubeblocks-addon-source-docs/docs/.... When it mentions scripts/..., resolve it from the same support package under scripts/.... If you are working inside a checkout of the original apecloud/kubeblocks-addon-skills, repo-relative paths are also valid.

Research and produce a four-column feature comparison between reference operators and KubeBlocks for the same database engine, covering both open-source and enterprise tiers.

Target: $ARGUMENTS (Format: <engine> [ref-os-operator] [ref-enterprise-product] Examples: clickhouse altinity clickhouse-cloud redis redis-operator redis-enterprise elasticsearch eck elastic-cloud If operator names are omitted they are auto-detected.)

---

Comparison Model

The four subjects compared in every feature row:

┌─────────────────────────┬──────────────────────────────────┐
│  OPEN SOURCE TIER        │  ENTERPRISE TIER                 │
├─────────────────────────┼──────────────────────────────────┤
│ A. Ref OS Operator       │ C. Ref Enterprise Product        │
│    e.g. Altinity         │    e.g. ClickHouse Cloud         │
├─────────────────────────┼──────────────────────────────────┤
│ B. KB OS + Addon         │ D. KB Enterprise + Addon         │
│    KB open-source        │    KB enterprise operator        │
│    + open-source addon   │    + same open-source addon      │
└─────────────────────────┴──────────────────────────────────┘

Key constraint: The open-source addon is shared between B and D. Features only achievable in D but not B must come from the KB enterprise operator layer, not from the addon.

Gap types produced:

• OS Gap (A > B): features Ref OS has but KB OS+Addon lacks → fix in KB Operator or Addon
• Enterprise Gap (C > D): features Ref Enterprise has but KB Ent+Addon lacks → fix in KB Enterprise
• KB Advantage (B > A or D > C): features KB has that the reference lacks → highlight as differentiators

---

Overview: Two-Phase Pipeline

To avoid "rule dilution" (formatting constraints buried under large content volumes):

• Phase 1 — Extract: Gather raw capability facts per category with no formatting
• Phase 2 — Format: Convert raw facts into structured tables and gap analysis

Do NOT merge the two phases.

---

Phase 0: Setup

0a. Parse arguments

ENGINE          = first token    (e.g., "clickhouse")
REF_OS_OP       = second token   (e.g., "altinity") — auto-detect if absent
REF_ENTERPRISE  = third token    (e.g., "clickhouse-cloud") — auto-detect if absent

0b. Load KB Enterprise feature reference (subject D)

Read docs/kb-enterprise-features.md as the authoritative capability list for Subject D (KB Enterprise + Addon). This file lists all enterprise-only (ENT), open-source-enhanced (OS+ENT), and addon-delivered (ADDON) features with layer tags.

Use it to determine D's status for every feature row without re-researching the enterprise codebase. Features tagged ENT are available only in D; features tagged OS+ENT are available in both B and D.

---

0c. Read the KubeBlocks addon (subject B / D shared layer)

find addons/${ENGINE} -type f | sort 2>/dev/null || \
find . -path "*/addons/${ENGINE}*" -type f | sort 2>/dev/null

Read every file in:

• addons/${ENGINE}/Chart.yaml and values.yaml
• addons/${ENGINE}/templates/ (all .yaml and .tpl)
• addons/${ENGINE}/scripts/ (all shell scripts)
• addons/${ENGINE}/config/ (all config templates)

Build an inventory of what the addon currently implements:

• Topologies (ClusterDefinition)
• Lifecycle hooks (roleProbe / memberJoin / memberLeave / switchover / postProvision / preTerminate)
• Backup ActionSets and BackupPolicyTemplate
• OpsDefinitions
• Config parameters (ParamsDefinition)
• System accounts
• Services and ports
• ShardingDefinition (if present)

Also check the upstream community repo for any features not yet in the local copy:

curl -s "https://api.github.com/repos/apecloud/kubeblocks-addons/contents/addons/${ENGINE}/templates" \
  2>/dev/null | python3 -c "import json,sys; [print(x['name']) for x in json.load(sys.stdin) if isinstance(x,dict)]"

0d. Auto-detect reference operators (if not provided)

Ref OS Operator — search GitHub:

curl -s "https://api.github.com/search/repositories?q=${ENGINE}+operator+kubernetes&sort=stars&per_page=5" \
  2>/dev/null | python3 -c "
import sys,json
for r in json.load(sys.stdin).get('items',[])[:5]:
    print(r['full_name'], r['stargazers_count'], r.get('description',''))
"

Ref Enterprise Product — for well-known engines use known mappings:

• clickhouse → ClickHouse Cloud (docs: clickhouse.com/docs/cloud)
• redis → Redis Enterprise (docs: redis.io/docs/latest/operate/rs)
• elasticsearch → Elastic Cloud (docs: elastic.co/guide/en/cloud)
• mongodb → MongoDB Atlas (docs: mongodb.com/docs/atlas)
• postgresql → AlloyDB / Aurora / Neon (pick most feature-complete)

Otherwise search: WebSearch("<engine> managed cloud database service features")

Record:

• REF_OS_REPO = GitHub owner/repo for the open-source operator
• REF_ENT_URL = official docs base URL for the enterprise product

---

Phase 1: Extract — Raw Capability Facts

IMPORTANT: No tables, no formatting yet. Output bullet lists only.

Extract facts for all four subjects across all 15 categories. For each fact record: <feature>: A=<Y/P/N> B=<Y/P/N> C=<Y/P/N> D=<Y/P/N> | <notes>

1a. Research Ref OS Operator (subject A)

Sources in order:

# README
curl -s "https://raw.githubusercontent.com/${REF_OS_REPO}/master/README.md" | head -300

# Docs index
curl -s "https://api.github.com/repos/${REF_OS_REPO}/contents/docs" 2>/dev/null \
  | python3 -c "import json,sys; [print(x['name']) for x in json.load(sys.stdin) if isinstance(x,dict)]"

# Fetch key docs: configuration, replication, storage, security, monitoring, schema/migration
curl -s "https://raw.githubusercontent.com/${REF_OS_REPO}/master/docs/<filename>.md"

# Source layout (reveals advanced capabilities not in docs)
curl -s "https://api.github.com/repos/${REF_OS_REPO}/git/trees/master?recursive=1" 2>/dev/null \
  | python3 -c "
import json,sys
tree = json.load(sys.stdin).get('tree',[])
for f in tree:
    p = f['path']
    if any(k in p for k in ['schemer','lifecycle','reconcil','controller','operator']):
        print(p)
" | head -40

1b. Research Ref Enterprise Product (subject C)

Use WebFetch to read the enterprise product docs. Focus on:

• Features page / what's included
• Features NOT available in the open-source version
• Enterprise-only capabilities (auto-scaling, idle suspend, PITR, compliance, etc.)

WebFetch(REF_ENT_URL + "/features", "List all features, especially enterprise-only ones")
WebFetch(REF_ENT_URL + "/security", "Security and compliance features")
WebFetch(REF_ENT_URL + "/scaling",  "Auto-scaling and resource management")
WebFetch(REF_ENT_URL + "/backup",   "Backup, restore, and PITR capabilities")

1c. Categorize each feature

For each of the 15 categories, produce raw bullets:

Category N: <Name>
- <feature 1>: A=Y B=P C=Y D=N | <brief note>
- <feature 2>: A=N B=N C=Y D=N | enterprise-only
- <feature 3>: A=N B=Y C=N D=Y | KB advantage — ref operator lacks this
...

Categories:

1.  Cluster Lifecycle        create/delete/start/stop/upgrade/rollback/suspend/troubleshoot
2.  Scaling & Resources      vertical/horizontal replicas/shards, drain, make-before-break, auto-scale
3.  High Availability        replication, failover, quorum, data-loss recovery, cross-AZ
4.  Configuration Mgmt       settings hierarchy, topology-aware config, hot reload, validation
5.  User & Access Mgmt       user CRUD, password, profiles, quotas, network ACL, SSO
6.  Security & Encryption    TLS, cert rotation, inter-node auth, secret refs, audit log, compliance
7.  Schema & Data Mgmt       schema migration on scale-out, table sync, metadata cleanup (engine-specific)
8.  Node Lifecycle Ops       graceful drain, query drain, replica lag wait, re-include conditions
9.  Storage Management       PVC expand, snapshots, watermark, tiered storage, provisioner modes
10. Backup & Restore         full/incr, schedule, PITR, retention, multi-backend, cross-region
11. Observability            metrics, operator metrics, pod monitor, per-replica, distributed tracing
12. Networking & Services    service types, role-based routing, FQDN, ports, private link
13. Day-2 Operations         ops abstraction, cancel, timeout, switchover, rebuild, custom ops
14. Templates & Reuse        pod/volume/service templates, cross-cluster reuse, override levels
15. Declarative IaC          CRD management, Helm, operator config CR, GitOps, multi-tenancy

Self-check after Phase 1:

• All 4 subjects evaluated for every feature row?
• Enterprise-only features of Ref Enterprise (C) captured and marked N/A for A/B?
• KB advantages (B or D > A or C) identified?
• Features that are Cloud-Only (not achievable in any K8s operator) marked N/A for A and B?

---

Phase 2: Format — Build Structured Output

Start only after Phase 1 is fully complete.

2a. Per-category comparison tables

Each table has four data columns:

## <N>. <Category Name>

| ID | Feature | A: Ref OS | B: KB OS+Addon | C: Ref Enterprise | D: KB Ent+Addon | Notes |
|---|---|:---:|:---:|:---:|:---:|---|
| N.1 | <feature> | Y | P | Y | P | <key difference> |
| N.2 | <feature> | N | N | Y | N | Enterprise-only |
| N.3 | <feature> | N | Y | N | Y | KB advantage |

Legend row at the top of the report:

• Y = Full support
• P = Partial support
• N = Not supported
• N/A = Not applicable (Cloud-Only or outside K8s operator scope)

2b. Summary statistics table

One row per category, columns for all four subjects:

## Summary: Coverage Statistics

| Category | Total | A Y | A P | A N | B Y | B P | B N | C Y | C P | C N | D Y | D P | D N |
|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
| 1. Cluster Lifecycle | N | | | | | | | | | | | | |
...
| **Total** | | | | | | | | | | | | | |

**A (Ref OS Operator)** coverage: XX/TT (XX%)
**B (KB OS + Addon)**   coverage: XX/TT (XX%)
**C (Ref Enterprise)**  coverage: XX/TT (XX%)  [excludes N/A items]
**D (KB Ent + Addon)**  coverage: XX/TT (XX%)  [excludes N/A items]

2c. Gap analysis — split by tier

OS Gap Analysis (A > B): implement in KB Operator or Addon

For every feature where B = N or B = P but A = Y:

## OS Gap Analysis: Ref OS Operator vs KB OS + Addon

| Layer | When to use |
|---|---|
| **KB 开源 Operator** | Generic reconciliation logic, new CRD fields, applies to all engines |
| **<Engine> Addon** | Engine-specific scripts, config templates, lifecycle hooks |
| **Operator + Addon 协作** | Operator provides hook/trigger; Addon provides engine logic |

Decision rules:
- Feature requires new reconcile loop logic or new CRD API → KB Operator
- Feature is pure engine SQL/config, KB has a lifecycle hook for it → Addon
- Needs both a new operator hook AND engine-specific script → Operator + Addon

### Per-Category Breakdown (OS gaps)

#### <Category N>
| ID | Feature | B Status | Layer | Rationale |
|---|---|:---:|---|---|

Enterprise Gap Analysis (C > D): implement in KB Enterprise

For every feature where D = N or D = P but C = Y AND the feature is not an OS gap (B is already Y):

## Enterprise Gap Analysis: Ref Enterprise vs KB Enterprise + Addon

Note: The open-source addon is shared. Features listed here require the KB Enterprise
operator layer — they CANNOT be delegated to the addon.

| ID | Feature | D Status | Why Enterprise only | Rationale |
|---|---|:---:|---|---|

Enterprise features typically include:

• Auto-scaling based on query load / idle suspend
• Advanced compliance and audit logging (SOC2, HIPAA)
• Cross-region / cross-cluster replication management
• Fleet-level template governance
• SLA monitoring and alerting integration
• Cost optimization (resource right-sizing)
• Enterprise SSO / RBAC integration

KB Advantages (B > A or D > C)

## KB Advantages (KubeBlocks leads the reference)

| ID | Feature | KB Tier | KB Status | Ref Status | Value |
|---|---|---|:---:|:---:|---|

2d. P0/P1/P2 priority checklist

Separate OS gaps and Enterprise gaps:

## Priority Checklist

### OS Gaps — P0 Must Have (X items)
Blocks professional-grade open-source management.
| Item | Feature IDs | Layer |
|---|---|---|

### OS Gaps — P1 Important (X items)
| Item | Feature IDs | Layer |
|---|---|---|

### OS Gaps — P2 Enhancement (X items)
| Item | Feature IDs | Layer |
|---|---|---|

### Enterprise Gaps — P0 Must Have (X items)
Blocks enterprise-tier positioning.
| Item | Feature IDs | Layer |
|---|---|---|

### Enterprise Gaps — P1/P2 (X items)
| Item | Feature IDs | Layer |
|---|---|---|

Priority criteria:

• P0: Users cannot adopt KB for this engine at this tier without this feature
• P1: Feature affects user experience significantly; workaround exists but is painful
• P2: Nice to have; most users won't block on it

2e. Key dependency chains

One chain for OS gaps, one for Enterprise gaps:

## Dependency Chains

### OS Gap Chain
[Operator prerequisite A] → [Operator prerequisite B]
        ↓
[Addon feature C depends on A+B]
        ↓
[Addon feature D depends on C]

### Enterprise Gap Chain
[Enterprise feature E] → [Enterprise feature F]
        ↓ (shared addon unchanged)
[Enterprise feature G]

---

Phase 3: Save Output

mkdir -p workspace
OUTFILE="workspace/${ENGINE}-operator-comparison.md"

File structure (in order):

1. Title, metadata (engine, ref OS op, ref enterprise, date, sources)
2. Comparison model diagram
3. Reading guide (legend)
4. 15 category comparison tables (4 columns each)
5. Summary statistics table
6. OS Gap analysis with implementation layers
7. Enterprise gap analysis
8. KB advantages
9. P0/P1/P2 priority checklists (OS and Enterprise separate)
10. Dependency chains
11. Coverage roadmap

┌─────────────────────────────────────────────────────┐
│  Coverage Roadmap                                   │
│                                                     │
│  OS Tier                                            │
│  Current:   B = XX%                                 │
│  + P0 done: B ≈ XX%  (parity with A)                │
│  + P1 done: B ≈ XX%  (exceeds A)                    │
│                                                     │
│  Enterprise Tier                                    │
│  Current:   D = XX%                                 │
│  + P0 done: D ≈ XX%  (parity with C)                │
│  + P1 done: D ≈ XX%  (exceeds C)                    │
└─────────────────────────────────────────────────────┘

Report to user:

Comparison report: workspace/${ENGINE}-operator-comparison.md

Subjects:
  A  Ref OS Operator : <name> (<GitHub URL>)
  B  KB OS + Addon   : kubeblocks (open-source) + ${ENGINE} addon
  C  Ref Enterprise  : <name> (<docs URL>)
  D  KB Ent + Addon  : kubeblocks (enterprise) + ${ENGINE} addon

Coverage (Y items only):
  A: XX%   B: XX%   C: XX%   D: XX%

Top OS gaps (P0):     <count> items → KB Operator: N, Addon: N, Operator+Addon: N
Top Ent gaps (P0):    <count> items → KB Enterprise
KB advantages:        <count> items where KB leads

---

Error Handling

• Ref OS repo not accessible → use WebSearch for official docs or OperatorHub listing
• Ref Enterprise docs require login → use WebSearch for feature comparison blog posts or release notes
• KB addon not found locally → read remotely from github.com/apecloud/kubeblocks-addons
• Feature category not applicable to this engine (e.g., Schema Migration for Redis) → mark entire category N/A with explanation
• Feature exists in both but implemented differently with equal completeness → both Y, note approach in Notes column
• Enterprise product has Cloud-Only features with no K8s equivalent → mark A=N/A, B=N/A, C=Y, D=N/A