问题排查方法
阅读本章以了解如何对 JuiceFS CSI 驱动进行问题排查。不论面临何种错误,排查过程都需要你熟悉 CSI 驱动的各个组件及其作用,因此继续阅读前,请确保你已了解 JuiceFS CSI 驱动架构。
排查工具
CSI 控制台
安装 CSI 驱动时,默认会一同安装 CSI 控制台(CSI Dashboard),使用他能方便地观测 CSI 驱动的各项资源,能够极大简化排查操作,推荐所有 CSI 驱动用户安装。
访问控制台地址,会看到如下界面:
如图所示 ,所有的相关资源都在网页中直接呈现,本章后续介绍的所有采集排查信息的操作,都可以在这个网页中简单点选就能实现,大大简化了 CSI 驱动的问题排查。
kubectl 插件
JuiceFS 提供了一个 kubectl 插件,可以方便地在 Kubernetes 集群中进行问题排查。
安装
一键安装脚本适用于 Linux 和 macOS 系统,会根据你的硬件架构自动下载安装最新版插件。
# 默认安装到 /usr/local/bin
curl -sSL https://d.juicefs.com/kubectl-jfs-install | sh -
如果环境中已经安装了 krew,也可以使用 krew
来安装:
kubectl krew update
kubectl krew install jfs
使用
# 快速列出所有使用 JuiceFS PV 的应用 pod
$ kubectl jfs po
NAME NAMESPACE MOUNT PODS STATUS AGE
cn-wrong-7b7577678d-7j8dc default juicefs-cn-hangzhou.10.0.1.84-ce-static-handle-qhuuvh CrashLoopBackOff 10d
image-wrong default juicefs-cn-hangzhou.10.0.1.84-ce-static-handle-qhuuvh ImagePullBackOff 10d
multi-mount-pod default juicefs-cn-hangzhou.10.0.1.84-ce-another-ilkzmy, Running 11d
juicefs-cn-hangzhou.10.0.1.84-ce-static-handle-qhuuvh
normal-664f8b8846-ntfzk default juicefs-cn-hangzhou.10.0.1.84-ce-static-handle-qhuuvh Running 11d
pending default <none> Pending 11d
res-err default <none> Pending 11d
terminating default <none> Terminating 10d
wrong default juicefs-cn-hangzhou.10.0.1.84-wrong-nvblwj ContainerCreating 10d
# 快速列出所有 JuiceFS Mount Pod。默认 Mount Pod 在 kube-system 下,可以用 -m 参数指定 Mount Pod 所在命名空间
$ kubectl jfs mount
NAME NAMESPACE APP PODS STATUS CSI NODE AGE
juicefs-cn-hangzhou.10.0.1.84-ce-another-ilkzmy kube-system default/multi-mount-pod Running juicefs-csi-node-v6pq5 11d
juicefs-cn-hangzhou.10.0.1.84-ce-static-handle-qhuuvh kube-system default/cn-wrong-7b7577678d-7j8dc, Running juicefs-csi-node-v6pq5 11d
default/image-wrong,
default/multi-mount-pod,
default/normal-664f8b8846-ntfzk
juicefs-cn-hangzhou.10.0.1.84-wrong-nvblwj kube-system default/wrong Running juicefs-csi-node-v6pq5 10d
# 快速列出所有 JuiceFS PV / PVC
$ kubectl jfs pv
$ kubectl jfs pvc
对于有问题的应用 Pod、PVC、PV,还可以使用以下功能进行初步诊断,JuiceFS plugin 会提示下一步的排查方向:
# 诊断应用 pod
$ kubectl jfs debug pod wrong
Name: wrong
Namespace: default
Start Time: Mon, 24 Jun 2024 15:15:52 +0800
Status: ContainerCreating
Node:
Name: cn-hangzhou.10.0.1.84
Status: Ready
CSI Node:
Name: juicefs-csi-node-v6pq5
Namespace: kube-system
Status: Ready
PVCs:
Name Status PersistentVolume
---- ------ ----------------
wrong Bound wrong
Mount Pods:
Name Namespace Status
---- --------- ------
juicefs-cn-hangzhou.10.0.1.84-wrong-nvblwj kube-system Error
Failed Reason:
Mount pod [juicefs-cn-hangzhou.10.0.1.84-wrong-nvblwj] is not ready, please check its log.
# 诊断 JuiceFS PVC
$ kubectl jfs debug pvc <pvcName>
$ kubectl jfs debug pv <pvName>
另外,还提供了快速获取 Mount Pod 访问日志以及快速预热缓存的功能:
# 获取 Mount Pod 访问日志:kubectl jfs accesslog <pod-name> -m <mount-namespace>
$ kubectl jfs accesslog juicefs-cn-hangzhou.10.0.1.84-ce-static-handle-qhuuvh
2024.07.05 14:09:57.392403 [uid:0,gid:0,pid:201] open (9223372032559808513): OK [fh:25] <0.000054>
#
# 预热缓存:kubectl jfs warmup <pod-name> <subpath> -m <mount-namespace>
$ kubectl jfs warmup juicefs-cn-hangzhou.10.0.1.84-ce-static-handle-qhuuvh
2024/07/05 14:10:52.628976 juicefs[207] <INFO>: Successfully warmed up 2 files (1090721713 bytes) [warmup.go:226]
诊断脚本
请优先使用 kubectl 插件,如果不能满足需求再尝试使用诊断脚本。
推荐使用诊断脚本 csi-doctor.sh
来收集日志及相关信 息,本章所介绍的排查手段中,大部分采集信息的命令,都在脚本中进行了集成,使用起来更为便捷。
在集群中任意一台可以执行 kubectl
的节点上,安装诊断脚本:
wget https://raw.githubusercontent.com/juicedata/juicefs-csi-driver/master/scripts/csi-doctor.sh
chmod a+x csi-doctor.sh
如果在你的运行环境中,kubectl 被重命名(比方说需要管理多个 Kubernetes 集群时,常常用不同 alias 来调用不同集群的 kubectl),或者并未放在 PATH
下,你也可以方便地修改脚步,将 $kbctl
变量替换为实际需要运行的 kubectl:
# 假设面对两个不同集群,kubectl 分别被别名为 kubectl_1 / kubectl_2
KBCTL=kubectl_1 ./csi-doctor.sh debug my-app-pod -n default
KBCTL=kubectl_2 ./csi-doctor.sh debug my-app-pod -n default
诊断脚本中最为常用的功能,就是方便地获取 Mount Pod 相关信息。假设应用 Pod 为 default
命名空间下的 my-app-pod
:
# 获取指定应用 Pod 所用的 Mount Pod
$ ./csi-doctor.sh get-mount my-app-pod
kube-system juicefs-ubuntu-node-2-pvc-b94bd312-f5f7-4f46-afdb-2d1bc20371b5-whrrym
# 获取使用指定 Mount Pod 的所有应用 Pod
$ ./csi-doctor.sh get-app juicefs-ubuntu-node-2-pvc-b94bd312-f5f7-4f46-afdb-2d1bc20371b5-whrrym
default my-app-pod
在你熟读了「基础问题排查原则」后,还可以使用 csi-doctor.sh debug
命令,来快速收集组件版本和日志信息。各类常见问题,均能在命令输出中找到排查线索:
./csi-doctor.sh debug my-app-pod -n default
运行上方命令,检查打印出来的丰富排查信息,用下方介绍的排查原则来进行诊断。同时,该命令控制输出内容的规模,你可以根据所使用的 JuiceFS 版本,方便地拷贝并发送给开源社区,或者 Juicedata 团队,进行后续排查。
基础问题排查原则
在 JuiceFS CSI 驱动中,常见错误有两种:一种是 PV 创建失败,属于 CSI Controller 的职责;另一种是应用 Pod 创建失败,属于 CSI Node 和 Mount Pod 的职责。
PV 创建失败
在「动态配置」下,PVC 创建之后,CSI Controller 会同时配合 kubelet 自动创建 PV。在此期间,CSI Controller 会在 JuiceFS 文件系统中创建以 PV ID 为名的子目录(如果不希望以 PV ID 命名子目录,可以通过 pathPattern
来调整)。
查看 PVC 事件
一般而言,如果创建子目录失败,CSI Controller 会将错误结果存在 PVC 事件中:
$ kubectl describe pvc dynamic-ce
...
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal Scheduled 27s default-scheduler Successfully assigned default/juicefs-app to cluster-0003
Warning FailedMount 11s (x6 over 27s) kubelet MountVolume.SetUp failed for volume "juicefs-pv" : rpc error: code = Internal desc = Could not mount juicefs: juicefs auth error: Failed to fetch configuration for volume 'juicefs-pv', the token or volume is invalid.
检查 CSI Controller
若 PVC 事件中并无错误信息,我们需要检查 CSI Controller 容器是否存活,以及是否存在异常日志:
# 检查 CSI Controller 是否存活
$ kubectl -n kube-system get po -l app=juicefs-csi-controller
NAME READY STATUS RESTARTS AGE
juicefs-csi-controller-0 3/3 Running 0 8d
# 检查 CSI Controller 日志是否存在异常信息
$ kubectl -n kube-system logs juicefs-csi-controller-0 juicefs-plugin
应用 Pod 创建失败
在 CSI 驱动的架构下,JuiceFS 客户端运行在 Mount Pod 中。因此每一个应用 Pod 都伴随着一个对应的 Mount Pod。
CSI Node 会负责创建 Mount Pod 并在其中挂载 JuiceFS 文件系统,最终将挂载点 bind 到应用 Pod 内。因此如果应用 Pod 创建失败,既可能是 CSI Node 的问题,也可能是 Mount Pod 的问题,需要逐一排查。