deploy-addon

name	deploy-addon
description	Use when deploying a KubeBlocks addon Helm chart to Kubernetes, validating Helm rendering, applying CRDs, and waiting for ClusterDefinition, ComponentDefinition, and ComponentVersion availability.

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.

Deploy the KubeBlocks addon Helm chart to Kubernetes and verify all CRDs reach Available status.

Target: $ARGUMENTS (Engine name, e.g., redis. Omitted → infer from recently modified addon.)

---

Step 0: Load Environment

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

kubectl cluster-info --request-timeout=5s \
  || { echo "ERROR: kubectl cannot reach the cluster. Check KUBECONFIG in .env"; exit 1; }
echo "KUBECONFIG=${KUBECONFIG:-~/.kube/config}"

# 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}"

Rule: every bash block below that calls kubectl must begin with:

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

Step 1: Locate and Validate the Addon

ENGINE=<engine>

# Confirm addon exists
ls addons/$ENGINE/Chart.yaml || { echo "Addon not found: addons/$ENGINE/"; exit 1; }

# Update Helm dependencies (kblib and others)
helm dependency update addons/$ENGINE 2>&1 || echo "Note: dependency update failed (kblib may not be local)"

# Pre-flight validation
helm template test-addon addons/$ENGINE --debug

If helm template fails, do not proceed — report the error. The YAML must be fixed first.

Step 2: Apply the Addon

helm template test-addon addons/$ENGINE --debug \
  --set "image.registry=${IMAGE_REGISTRY}" \
  | kubectl apply -f -

Capture which resources were created, configured, or unchanged. Note the exact names of:

• ClusterDefinition resources
• ComponentDefinition resources
• ComponentVersion resources

Step 4: Poll for Available Status

Poll each resource with a timeout (not a fixed sleep):

ENGINE=<engine>
TIMEOUT=90
INTERVAL=5

echo "Waiting for ClusterDefinition $ENGINE..."
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

# Repeat for each ComponentDefinition applied
for CD in <list-of-componentdefinition-names>; do
  echo "Waiting for ComponentDefinition $CD..."
  for ((i=0; i<TIMEOUT; i+=INTERVAL)); do
    PHASE=$(kubectl get componentdefinition $CD \
      -o jsonpath='{.status.phase}' 2>/dev/null)
    echo "  [${i}s] $CD: ${PHASE:-pending}"
    [[ "$PHASE" == "Available" ]] && break
    sleep $INTERVAL
  done
done

# ComponentVersion: phase may be absent — check with a single get
kubectl get componentversion $ENGINE -o jsonpath='{.status.phase}' 2>/dev/null \
  && echo "" || echo "(no phase — this is acceptable for ComponentVersion)"

Step 5: Verify — Interpret Status

Success criteria:

• ClusterDefinition.status.phase == "Available" ✓
• ComponentDefinition.status.phase == "Available" ✓ for each one
• ComponentVersion: Available is ideal; no phase or empty is also acceptable

Also check conditions if phase is absent or Unknown:

kubectl get componentdefinition <name> -o json | python3 -c "
import sys, json
d = json.load(sys.stdin)
conds = d.get('status', {}).get('conditions', [])
for c in conds:
    print(f'{c[\"type\"]}: {c[\"status\"]}  ({c.get(\"reason\",\"\")})')
    if c.get('message'):
        print(f'  message: {c[\"message\"]}')
"

Step 6: Diagnose Failures

If a resource is not Available after the timeout:

# Describe for events and condition details
kubectl describe clusterdefinition $ENGINE
kubectl describe componentdefinition <name>

# Operator logs — the reconciliation error will be here
KB_POD=$(kubectl get pods -n kb-system \
  -l app.kubernetes.io/name=kubeblocks \
  -o jsonpath='{.items[0].metadata.name}' 2>/dev/null)
kubectl logs -n kb-system "$KB_POD" --tail=150

Common errors and fixes:

Operator log says	Fix
field is immutable	Add apps.kubeblocks.io/skip-immutable-check: "true" annotation
unknown field "templateRef"	Change templateRef: → template: in configs[]
configmap "<name>" not found	The ConfigMap referenced in configs[].template was not applied; apply it
unknown field "xxx"	Check the version-specific API reference (kb-api-reference-1.0.md, kb-api-reference-1.1.md, or kb-api-reference.md) for the correct field name
apiVersion "apps.kubeblocks.io/v1beta1" not found	Update to apps.kubeblocks.io/v1
Resource applied but phase never appears	KubeBlocks operator may not be running or not watching this CRD version

Step 7: Summary

## Deployment Summary

Addon: <engine>
Chart version: <version>

### Resources Applied
- ClusterDefinition/<engine>:              ✓ Available
- ComponentDefinition/<engine>-7-1.1.0:   ✓ Available
- ComponentDefinition/<engine>-8-1.1.0:   ✓ Available
- ComponentVersion/<engine>:              ✓ Available

### Status
✓ All resources Available — addon ready for /test-instances