| 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
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.
