From 6e9a666600689aae879c6d8e97325d5c919a518a Mon Sep 17 00:00:00 2001
From: Xuhui zhang <xuhui@juicedata.io>
Date: Mon, 29 Jul 2024 15:08:47 +0800
Subject: [PATCH] docs: update faq

Signed-off-by: Xuhui zhang <xuhui@juicedata.io>
---
 docs/zh_cn/FAQs.md | 43 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)

diff --git a/docs/zh_cn/FAQs.md b/docs/zh_cn/FAQs.md
index 4200919290..24626f43bb 100644
--- a/docs/zh_cn/FAQs.md
+++ b/docs/zh_cn/FAQs.md
@@ -9,6 +9,7 @@ slug: /faq
 
 * 如果你使用 JuiceFS 社区版，加入 [JuiceFS 开源社区](https://juicefs.com/zh-cn/community)以寻求帮助。
 * 如果你使用 JuiceFS 云服务，请通过[控制台](https://juicefs.com/console)右下角的 Intercom 会话联系 Juicedata 团队。
+* 使用我们的 [kubectl-jfs-plugin](https://github.com/juicedata/kubectl-jfs-plugin) kubectl 插件更详细的排查。
 
 ## 如何平滑重新挂载 JuiceFS 文件系统？ {#seamless-remount}
 
@@ -37,3 +38,45 @@ systemctl stop kubelet
 rm -rf /var/lib/containerd
 # 重装 containerd
 ```
+
+## MountPod 一直处于 pending 状态
+
+使用 `kubectl describe <MountPod Name>` 查看当前 Pod Event。
+
+可能的原因：
+
+- 节点资源是否足够
+
+```
+kubectl describe node <nodeName>
+```
+
+节点资源不足时，便无法启动。此时需要根据实际情况[调整 Mount Pod 资源声明](../guide/resource-optimization.md#mount-pod-resources)，或者扩容宿主机。
+
+- 集群 IP 资源是否充足
+
+mount pod 默认以 `HostNetwork: false` 的形式启动，可能会占用大量的集群 IP 资源，如果集群资源 IP 不足可能会导致 mount pod 启动不成功。
+
+联系对应的云厂商扩容，或者使用 `HostNetwork: true` 形式启动 mount pod，参阅：[定制 Mount Pod 和 Sidecar 容器](../zh_cn/guide/configurations.md#customize-mount-pod)
+
+## MountPod 没有创建
+
+使用 `kubectl describe <App Pod Name>` 查看当前业务 Pod Event。
+
+确认已经进入挂载流程，而不是调度失败或者其他非 mount 错误。
+
+- `driver name csi.juicefs.com not found` 或者 `csi.sock no such file`
+
+  检查对应节点上的 `csi-node` 是否运行正常
+
+- `Unable to attach or mount volumes: xxx`
+
+  查看对应的 CSI Node 日志中 过滤出对应 PV 的相关日志
+
+  如果没有找到类似于 `NodepublishVolume: volume_id is <pv name>` 日志，并且 K8s 版本低于 `v1.26.0`, `1.25.1`, `1.24.5`, `1.23.11` 可能是因为 kubelet 的一个 bug 导致没有触发 volume publish 请求，详见 [#109047](https://github.com/kubernetes/kubernetes/issues/109047)
+  
+  此时可以尝试
+  - 重启 kubelet
+  - 联系对应的云厂商或者运维。
+
+  总之 JuiceFS CSI 需要收到请求才能开始挂载流程。