generate-addon

name	generate-addon
description	Use when generating or modifying a KubeBlocks addon Helm chart, adding an engine/version/topology, or selecting KubeBlocks API references before writing addon YAML.

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.

Execute the full KubeBlocks addon development workflow for the following goal:

Goal: $ARGUMENTS

---

Phase 0: Understand the Goal

Parse the goal to identify:

1. Engine name (e.g., redis, postgresql, elasticsearch)
2. Target version(s) (e.g., 9.0.0, 7.2.4)
3. Topology requirements (standalone, replication, cluster, etc.)
4. Whether this is a new addon or adding a new major version to an existing one

Load environment and detect image registry

SCRIPT_DIR="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
[ -f "$SCRIPT_DIR/.env" ] && source "$SCRIPT_DIR/.env"
[ -n "$KUBECONFIG" ] && export KUBECONFIG

# Registry decision: probe docker.io; fall back to ALIYUN_IMAGE_REGISTRY if unreachable
if curl -s --connect-timeout 15 "https://registry-1.docker.io/v2/" -o /dev/null 2>/dev/null; then
  IMAGE_REGISTRY="docker.io"
  SKOPEO_CREDS="--no-creds"
elif [ -n "$ALIYUN_IMAGE_REGISTRY" ]; then
  IMAGE_REGISTRY="${ALIYUN_IMAGE_REGISTRY}"
  SKOPEO_CREDS="--creds ${ALIYUN_DOCKER_USERNAME}:${ALIYUN_DOCKER_PASSWORD}"
else
  IMAGE_REGISTRY="docker.io"
  SKOPEO_CREDS="--no-creds"
fi
echo "Image registry: ${IMAGE_REGISTRY}"

# Node arch/OS — used by skopeo to probe the correct manifest variant
NODE_ARCH=$(kubectl get nodes -o jsonpath='{.items[0].status.nodeInfo.architecture}' 2>/dev/null || echo "amd64")
NODE_OS=$(kubectl get nodes   -o jsonpath='{.items[0].status.nodeInfo.operatingSystem}' 2>/dev/null || echo "linux")
echo "Node arch: ${NODE_ARCH}  os: ${NODE_OS}"

Detect KubeBlocks version

# Detect installed KubeBlocks version
KB_VERSION=$(kubectl get deployment -n kb-system kubeblocks \
  -o jsonpath='{.metadata.labels.app\.kubernetes\.io/version}' 2>/dev/null \
  | grep -oE '^[0-9]+\.[0-9]+' || echo "unknown")
echo "KubeBlocks version: $KB_VERSION"

Select the API reference based on detected version:

• 1.0.x → use docs/kb-api-reference-1.0.md
• 1.1.x → use docs/kb-api-reference-1.1.md
• 1.2.x or unknown (latest) → use docs/kb-api-reference.md

Read the selected API reference file before generating any YAML.

Routing decision:

• If creating/modifying YAML → start at Phase 1 (Code)
• If deploying/testing only → skip to Phase 3 (Deploy)
• If diagnosing existing failures → skip to Phase 5 (Diagnose)

---

Phase 1: Code — Generate or Modify Addon YAML

1a. Understand existing structure

# What files already exist?
find addons/<engine>/ -type f 2>/dev/null | sort

# Check values.yaml for existing version array structure
cat addons/<engine>/values.yaml 2>/dev/null

# Check if kblib exists (needed for Chart.yaml dependency)
ls addons/kblib/ 2>/dev/null && echo "kblib present" || echo "kblib absent"

Read all existing files in addons/<engine>/. Also read a reference addon (e.g., addons/redis/) to understand the conventions used in this particular repo.

1b. Generate or modify files

Follow rules in docs/coding-rules.md and the version-specific API reference selected in Phase 0:

For a new addon:

• Chart.yaml with kblib dependency and KB annotations
• values.yaml with versions array
• templates/_helpers.tpl with naming, regex, and annotation helpers
• templates/clusterdefinition.yaml
• templates/cmpd-<component>.yaml (one per component type)
• templates/cmpv-<component>.yaml (one per component type)
• config/<engine>-config.yaml (ConfigMap for config file template)
• scripts/<engine>-start.sh (startup script)

For adding a new major version to existing addon:

• Add the new major version entry to values.yaml <engine>Versions array
• The {{- range }} loop in cmpd-*.yaml and cmpv-*.yaml auto-generates the new resources
• Add any version-specific config ConfigMap
• Add version-specific script changes (if entrypoint or config format changed)
• Do NOT modify existing entries in the versions array

Critical rules:

• All CRD resources need annotations: kubeblocks.io/crd-api-version: apps.kubeblocks.io/v1 and apps.kubeblocks.io/skip-immutable-check: "true"
• ComponentDefinition name: {{ printf "%s-%s" .componentDef $.Chart.Version }}
• compDef in ClusterDefinition: use regex helper (e.g. ^redis-\d+), not a hard-coded string
• configs[].template (not templateRef) for ConfigMap references
• roles[].isExclusive: true on leader/primary roles
• No ClusterVersion resource anywhere

1c. Validate with Helm

# Update dependencies first if Chart.yaml has kblib
helm dependency update addons/<engine>

# Then validate rendering
helm template test-addon addons/<engine>

If this fails: read the error, fix the specific issue, re-run. Retry up to 3 times. If still failing after 3 attempts, report to user.

---

Phase 2: Review — Code Quality Check

Evaluate the generated code (rules from docs/coding-rules.md review checklist):

1. Required annotations present on all ClusterDefinition, ComponentDefinition, ComponentVersion?
2. Version alignment: Do image tags, serviceVersion fields, and appVersion in Chart.yaml match the requested version?
3. Backward compatibility: Existing entries in the versions array unchanged? All existing _helpers.tpl definitions still present?
4. configs[].template field (not templateRef) used?
5. configs[].volumeName has a matching entry in runtime.volumes AND runtime.containers[*].volumeMounts?
6. roles[].isExclusive: true set for leader/primary roles?
7. Logic correctness: Are lifecycle scripts (roleProbe, postProvision, switchover) correct for this engine version? (Do not blindly copy from a different major version.)
8. Config accuracy: Does the config template for the new version use parameters valid for that specific version?

Do NOT flag: securityContext, privileged mode, resource requests/limits — intentional for DB internals.

If issues found: fix them in Phase 1, then re-run review.

---

Phase 3: Deploy — Apply to Kubernetes

3a. Check kubeconfig

kubectl cluster-info
# If this fails, the cluster is unreachable — report to user

3b. Apply the addon

helm dependency update addons/<engine>
helm template test-addon addons/<engine> --debug \
  --set "image.registry=${IMAGE_REGISTRY}" \
  | kubectl apply -f -

3c. Poll for Available status

ENGINE=<engine>
TIMEOUT=90
INTERVAL=5

for ((i=0; i<TIMEOUT; i+=INTERVAL)); do
  PHASE=$(kubectl get clusterdefinition $ENGINE -o jsonpath='{.status.phase}' 2>/dev/null)
  echo "  [${i}s] ClusterDefinition: ${PHASE:-pending}"
  [[ "$PHASE" == "Available" ]] && break
  sleep $INTERVAL
done

Also check each ComponentDefinition and ComponentVersion.

3d. Diagnose if not Available

kubectl describe componentdefinition <name>
kubectl describe clusterdefinition <name>
KB_POD=$(kubectl get pods -n kb-system -l app.kubernetes.io/name=kubeblocks \
  -o jsonpath='{.items[0].metadata.name}')
kubectl logs -n kb-system "$KB_POD" --tail=100

Common errors and fixes:

• field is immutable → missing apps.kubeblocks.io/skip-immutable-check: "true" annotation
• unknown field "templateRef" → should be template: in configs[]
• configmap "xxx" not found → the ConfigMap named in configs[].template wasn't applied

---

Phase 4: Test Instances

4a. Prerequisites

ls addons-cluster/<engine>/Chart.yaml || echo "addons-cluster not found — skipping instance tests"

4b. Get topologies and service versions

# Topologies
helm template test-addon addons/<engine> | python3 -c "
import sys, yaml
for doc in yaml.safe_load_all(sys.stdin):
    if doc and doc.get('kind') == 'ClusterDefinition':
        for t in doc.get('spec', {}).get('topologies', []):
            print(t['name'], '(default)' if t.get('default') else '')
"

# Available service versions
kubectl get componentversion <engine> -o jsonpath='{.spec.releases[*].serviceVersion}' \
  | tr ' ' '\n' | sort -V

4c. Probe image existence

for VERSION in <versions-to-test>; do
  if skopeo inspect "docker://${IMAGE_REGISTRY}/apecloud/${ENGINE}:${VERSION}" \
      --override-arch "${NODE_ARCH}" --override-os "${NODE_OS}" \
      $SKOPEO_CREDS 2>/dev/null 1>/dev/null; then
    echo "$VERSION: EXISTS"
  else
    echo "$VERSION: MISSING — will skip"
  fi
done

Skip tests for missing images. Do NOT modify version tags in YAML.

4d. Generate and apply test cluster YAML

For each (topology, version) combination where the image exists:

Create workspace/tests/<engine>-<topology>-test.yaml with:

apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
  name: kb-test-<engine>  # keep name short and unique
  namespace: default
spec:
  terminationPolicy: Delete   # required
  clusterDef: <engine>
  topology: <topology>
  componentSpecs:
    - name: <component-name>  # must match topology's component name exactly
      serviceVersion: "<version>"
      replicas: 1
      resources:
        limits:   { cpu: "0.5", memory: "512Mi" }
        requests: { cpu: "0.1", memory: "256Mi" }
      volumeClaimTemplates:
        - name: data
          spec:
            accessModes: [ReadWriteOnce]
            storageClassName: ""
            resources:
              requests:
                storage: 1Gi

For multi-component topologies (e.g., replication with sentinel), include a componentSpecs entry for each component in the topology with the correct name field.

kubectl apply -f workspace/tests/<engine>-<topology>-test.yaml

4e. Wait and check

Poll for Running phase up to 180 seconds. Check pod status every 15 seconds.

KB v1 has NO cluster-level "Failed" phase. Watch for pod-level failures:

• CrashLoopBackOff, ImagePullBackOff, ErrImagePull, CreateContainerConfigError → abort immediately
• FailedScheduling, FailedMount after 45s → infrastructure issue, abort

On failure: run Phase 5 (Diagnose) before making any code changes.

---

Phase 5: Diagnose

When cluster instances are failing:

CLUSTER=<cluster-name>

kubectl get cluster "$CLUSTER" -o yaml
kubectl get component -l app.kubernetes.io/instance="$CLUSTER" -o wide
kubectl get pods -l app.kubernetes.io/instance="$CLUSTER" -o wide

for POD in $(kubectl get pods -l app.kubernetes.io/instance="$CLUSTER" \
             -o jsonpath='{.items[*].metadata.name}'); do
  echo "=== Pod: $POD ==="
  for C in $(kubectl get pod "$POD" -o jsonpath='{.spec.initContainers[*].name}' 2>/dev/null); do
    echo "--- Init: $C ---"
    kubectl logs "$POD" -c "$C" --tail=80 2>&1
  done
  for C in $(kubectl get pod "$POD" -o jsonpath='{.spec.containers[*].name}'); do
    echo "--- Container: $C ---"
    kubectl logs "$POD" -c "$C" --tail=80 2>&1
  done
  kubectl get events --field-selector involvedObject.name="$POD" --sort-by='.lastTimestamp'
done

KB_POD=$(kubectl get pods -n kb-system -l app.kubernetes.io/name=kubeblocks \
  -o jsonpath='{.items[0].metadata.name}')
kubectl logs -n kb-system "$KB_POD" --tail=60

Identify root cause. Then:

• If YAML bug → return to Phase 1 with specific fix
• If infrastructure issue (scheduling, storage, missing image) → report to user, cannot fix in YAML

---

Completion

Summarize:

1. Files created or modified (paths)
2. Resources deployed (names, kinds)
3. Topologies tested (success/skipped/failed)
4. Any images not yet in registry (skipped tests)
5. Overall verdict: ready for production / needs further work