JuiceFS CSI Driver 常见问题排查指南

Kubernetes 作为资源调度和应用编排的开源系统，正在成为云计算和现代 IT 基础架构的通用平台。JuiceFS CSI Driver 实现了容器编排系统的存储接口，使得用户可以在 Kubernetes 中以原生的方式使用 JuiceFS。

由于 Kubernetes 自身的复杂性，用户反馈在部署和使用 JuiceFS CSI Driver 时，会遇到不少疑难问题。本文将为大家介绍JuiceFS CSI Driver架构、常见问题排查思路。

1. JuiceFS CSI Driver 架构介绍

组件

JuiceFS CSI Driver 的架构如下图，共有两个组件：

Controller Service：以 PV id 为名在 JuiceFS 文件系统中创建子目录。

Node Service：创建 Mount Pod（JuiceFS 客户端），并挂载应用 Pod。

CSI Node 的工作机制如下图，主要将 JuiceFS 客户端放在单独的 pod 中运行，这样做有如下益处：

多个 Pod 共用 PV 时，不会新建 Mount Pod，而是对已有的 Mount Pod 做引用计数，计数归零时删除 Mount Pod。
CSI 驱动组件与客户端解耦，方便 CSI 驱动自身的升级。

创建 PV 和使用的流程

动态创建 PV（不使用 StorageClass 的跳过此步骤）：

用户创建 PVC ，使用 JuiceFS 作为 StorageClass；
CSI Controller 负责在 JuiceFS 文件系统中做初始化，默认以 PV ID 为名字创建子目录，同时创建对应的 PV；
Kubernetes (PV Controller 组件) 将上述用户创建的 PVC 与 CSI Controller 创建的 PV 进行绑定，此时 PVC 与 PV 的状态变为「Bound」；

Pod 中使用 PVC：
用户创建应用 Pod，Pod 中声明使用先前创建的 PVC；
CSI Node Service 负责在应用 Pod 所在节点创建 Mount Pod；
Mount Pod 启动，执行 JuiceFS 客户端挂载，运行 JuiceFS 客户端，挂载路径暴露在宿主机上，路径为 /var/lib/juicefs/volume/[pv-name]；
CSI Node Service 等待 Mount Pod 启动成功后，将 PV 对应的 JuiceFS 子目录 bind 到容器内，路径为其声明的 VolumeMount 路径；
Kubelet 创建应用 Pod。

PVC - PV - MountPod 的关系可以用下图表示，在同一个节点上，一个 PVC 会对应一个 Mount Pod。

2. 动态配置和静态配置使用示范

创建 Secret：

apiVersion: v1

kind: Secret

metadata:

 name: juicefs-secret

type: Opaque

stringData:

 name: <JUICEFS_NAME>

 metaurl: <META_URL>

 storage: s3

 bucket: https://<BUCKET>.s3.<REGION>.amazonaws.com

 access-key: <ACCESS_KEY>

 secret-key: <SECRET_KEY>

静态配置

在应用 YAML 中申明 PVC，同时 PVC 指定 PV。

动态配置

在应用 YAML 中申明 PVC，同时 PVC 指定 StorageClass，PV 会自动创建。

3. Mount Pod 的管理

CSI Node 负责管理 Mount Pod 的生命周期，有一些特性可以根据业务情况选择使用。

第一，多个应用 pod 使用同一个 PVC时，共用 Mount Pod。主要的做法是：

Mount Pod 的 annotation 中记录了应用的挂载路径，作为引用计数
CSI 在后台检查其记录挂载的应用是否存活，当没有应用引用时，对其进行回收

第二，Mount Pod 意外退出后，CSI 自动拉起，并恢复容器内的挂载点。该特性需要用户在应用端开启 HostToContainer 或 Bidirectional 。并且，在挂载点损坏前打开的文件不能恢复，需要用户侧做好重试。

第三，可以设置 Mount Pod 的资源请求及限制（CPU/Memory requests & limit）。

第四，Mount Pod 延迟退出，所有的应用都退出后，Mount Pod 延后退出。主要的使用场景数大量应用使用同一 PVC，且应用会频繁创建删除。

第五，Mount Pod 退出时清理缓存。默认情况下，Mount Pod 使用的缓存会留在宿主机上，且退出后不会清理；开启这个功能后，CSI 在回收 Mount Pod 时，会启动一个 job，清理宿主机上的缓存。

第六，设置 Mount Pod 所使用的缓存路径。默认情况缓存使用的是本地磁盘；也可以使用独立 PVC 作为缓存路径。

第七，设置 Mount Pod 的镜像。首先，CSI Node 的环境变量设置默认的 Mount 镜像；也可以在 PV/StorageClass 中设置特定的 Mount 镜像。

4. CSI 使用建议

对于 JuiceFS CSI Driver 的使用，有以下几点建议：

开启 Mount pod 的监控，可以实时查看当前集群的使用负载、缓存、I/O 等情况；
收集 Mount pod 的日志，利于故障排查；
开启挂载点自动恢复功能，提高可用性；
不要在 CSI 环境中使用 writeback 参数，writeback 需要有至少有一个客户端异步将数据上传到对象存储中，Mount Pod 与应用同生命周期，不会一直存在，有丢数据的风险。

5.问题排错思路

常见错误有两种：一种是 PV 创建失败，属于 CSI Controller 的职责；另一种是应用 Pod 创建失败，属于 CSI Node 和 Mount Pod 的职责。

详细问题排查思路请访问，排查方法文档。

关于更多 JuiceFS CSI Driver 的文档，包括使用方法、运维管理等，可以统一访问 JuiceFS CSI Driver 文档。

一些关于 CSI 的 Q&A

如何挂载已经存在的 JuicFS 数据？

使用静态挂载，应用声明 PVC，指定 PV；动态配置会保证每个应用使用单独的子目录作为隔离，不能访问已有的数据。

2.同一个 JuiceFS 卷，如何实现挂载不同参数？

声明不同的 PVC 和 PV/StorageClass，在 PV/StorageClass 中指定不同的挂载参数。

同一个 PVC，多个 pod 如何实现不同子目录挂载？

同一个PVC对应同一个MountPod（juicefs fuse 客户端）的，应用 pod 中可以在 volumeMount 中定义不同的 subPath 实现挂载不同的子目录。

“trash-days”等配置参数如何设置？

juicefs format 的参数，如 trash-days、inodes、capacity 等，在 secret 的 format-options 里设置。

如何在 CSI 环境中做缓存预热？

使用 kubectl exec 命令进入到 Mount Pod 中， df 命令查看挂载点，再用 juicefs warmup 命令做预热，其中社区版的二进制路径为 /usr/local/bin/juicefs，商业版的二进制路径为 /usr/bin/juicefs。

更多问题排查案例请访问排查案例文档。

如有帮助的话欢迎关注我们项目 Juicedata/JuiceFS 哟！ (0ᴗ0✿)