debug-csi

name	debug-csi
description	Build, deploy, and debug the alibaba-cloud-csi-driver on a test cluster. Use this skill when the user wants to build images, deploy via helm, check logs, restart components, or troubleshoot the CSI plugin/provisioner. Also trigger for "deploy csi", "check csi logs", "restart csi", "debug csi", "build and push", or any question about how to iterate on this driver in a dev cluster.

Debug CSI Driver

This skill covers the build-deploy-debug loop for the CSI driver on an ACK test cluster.

Prerequisite: .local/test-values.yaml must exist. If it doesn't (or the cluster it refers to is unreachable), run /init-dev-env first.

Build and deploy

Uninstall component-center version (if present)

Before deploying via helm, check whether the CSI driver was installed via the ACK component center:

helm list -n kube-system

If there's a csi release, it's already a debug version — skip uninstall. Otherwise run:

../../init-dev-env/scripts/uninstall-csi-addon.sh

Build and push images

When building from a non-VPC environment (e.g. local machine), apply the yum mirror patch first so that container builds can access Alinux repos:

git apply .agents/skills/debug-csi/yum-mirror.diff

This is a local-only patch — do not commit it. Just revert it if it gets into your way, and apply it again when building again.

PLATFORM=linux/amd64 IMAGE_REPO=<registry>/<namespace> IMAGE_TAG=latest ./build/build-all-multi.sh

Refer to .local/test-values.yaml for the registry and namespace. IMAGE_TAG defaults to latest; set it to a custom tag (e.g. v1.35.3-dev) if needed. The script builds and pushes all images: csi-plugin, csi-plugin:init, csi-plugin:controller, csi-agent, csi-ossfs, csi-ossfs2, csi-alinas, mount-proxy.

To build only specific images, set IMAGES (space-separated names without tags):

IMAGES="mount-proxy csi-agent" PLATFORM=linux/amd64 IMAGE_REPO=<registry>/<namespace> ./build/build-all-multi.sh

Deploy via helm

helm upgrade -f .local/test-values.yaml -n kube-system ack-csi-plugin ./deploy/charts/alibaba-cloud-csi-driver
# One-time: set imagePullPolicy to Always
scripts/set-image-pull-policy.sh

If only images changed (no chart changes), rolling-restart instead of helm upgrade:

kubectl -n kube-system rollout restart deploy/csi-provisioner
kubectl -n kube-system rollout restart daemonset/csi-plugin

Debugging and logs

csi-plugin (daemonset, runs on each node, handles NodePublish/NodeUnpublish):

kubectl -n kube-system logs -l app=csi-plugin -c csi-plugin --tail=100

csi-provisioner (deployment, handles ControllerPublish/ControllerUnpublish):

kubectl -n kube-system logs -l app=csi-provisioner -c csi-provisioner --tail=100

Restarting components

Patching the pod template (env, imagePullPolicy, etc.) automatically triggers a rolling update. rollout restart is only needed when the patch reports "no change" (e.g. image tag is the same).

Test pod images

Use mirrors-ssl.aliyuncs.com/busybox or mirrors-ssl.aliyuncs.com/debian as test pod images. Also use these for ephemeral containers and kubectl debug commands. Docker Hub and other registries outside China are unreliable due to network issues. mirrors-ssl.aliyuncs.com mirrors all popular official Docker Hub images.

OSS / OSSFS

For OSSFS-related debugging (fuse pod image config, fuse pod logs, fuse pod lifecycle), read references/oss.md.

NAS / cnfs-nas-daemon

For NAS mount proxy debugging (enabling the proxy, testing cnfs-nas-daemon images, EFC mount flow), read references/nas.md.