高级功能与配置
CSI 驱动的各种高级功能,以及使用 JuiceFS PV 的各项配置、CSI 驱动自身的配置,都在本章详述。
ConfigMap 配置
从 v0.24 开始,CSI 驱动支持在名为 juicefs-csi-driver-config
的 ConfigMap 中书写配置,支持多种多样的配置项,既可以用来配置 Mount Pod 或 sidecar,也包含 CSI 驱动自身的配置,并且支持动态更新:修改 Mount Pod 配置时不需要重建 PV,修改 CSI 自身配置时,也不需要重启 CSI Node 或者 Controller。
由于 ConfigMap 功能强大、更加灵活,它将会或已经取代从前在 CSI 驱动中各种修改配置的方式,例如下方标有「不推荐」的小节,均为旧版中灵活性欠佳的实践,请及时弃用。简而言之,如果一项配置已经在 ConfigMap 中得到支持,则在 ConfigMap 中具有最高优先级,因此请优先在 ConfigMap 中对其进行配置,弃用旧版本中的实践。
修改 ConfigMap 以后,相关改动并不会立刻生效,这是由于挂载进容器的 ConfigMap 并非实时更新,而是定期同步(详见 Kubernetes 官方文档)。
如果希望立即生效,可以给 CSI 组件临时添加 Annotation 来触发更新:
kubectl -n kube-system annotate pods -l app.kubernetes.io/name=juicefs-csi-driver useless-annotation=true
ConfigMap 生效后,后续创建的 Mount Pod 都会应用新的配置,但已有的 Mount Pod 并不会自动更新! 根据所修改的项目不同,可能需要重建应用 Pod 或者 Mount Pod,方可令修改生效。请继续阅读下方相关章节了解各自项目具体的生效条件。
下方介绍的所有相关的字段,只要是合法的 Sidecar 容器配置,那么对于 Sidecar 容器同样生效。比如:
resources
是 Mount Pod 和 Sidecar 容器都具备的配置,因此对两种场景都生效;custom-labels
的作用是为 Pod 添加自定义标签,而「标签」是 Pod 独有的属性,Container 是没有标签的,因此custom-labels
就只对 Mount Pod 生效,Sidecar 场景则会忽略该配置。
ConfigMap 中支持的所有配置项,都可以在这里找到示范,并且在本文档相关小节中进行更详细介绍。
示例
globalConfig:
# 支持模板变量,比如 ${MOUNT_POINT}、${SUB_PATH}、${VOLUME_ID}
mountPodPatch:
# 未定义 pvcSelector,则为全局配置
- lifecycle:
preStop:
exec:
command:
- sh
- -c
- +e
- umount -l ${MOUNT_POINT}; rmdir ${MOUNT_POINT}; exit 0
# 如果多个 pvcSelector 匹配的是相同的 PVC,则后定义的配置会覆盖更早定义的配置
- pvcSelector:
matchLabels:
mylabel1: "value1"
# 启用 host network
hostNetwork: true
- pvcSelector:
matchLabels:
mylabel2: "value2"
# 增加 labels
labels:
custom-labels: "mylabels"
- pvcSelector:
matchLabels:
...
# 修改资源定义
resources:
requests:
cpu: 100m
memory: 512Mi
- pvcSelector:
matchLabels:
...
readinessProbe:
exec:
command:
- stat
- ${MOUNT_POINT}/${SUB_PATH}
failureThreshold: 3
initialDelaySeconds: 10
periodSeconds: 5
successThreshold: 1
- pvcSelector:
matchLabels:
...
# 目前暂不推荐使用 liveness probe,请优先使用 readiness probe
# JuiceFS 客户端自身也会进行检活和重启,因此避免额外设置 liveness probe,从外部重启
livenessProbe:
exec:
command:
- stat
- ${MOUNT_POINT}/${SUB_PATH}
failureThreshold: 3
initialDelaySeconds: 10
periodSeconds: 5
successThreshold: 1
- pvcSelector:
matchLabels:
...
annotations:
# 延迟删除
juicefs-delete-delay: 5m
# 退出时清理 cache
juicefs-clean-cache: "true"
# 为 Mount Pod 注入环境变量
- pvcSelector:
matchLabels:
...
env:
- name: DEMO_GREETING
value: "Hello from the environment"
- name: DEMO_FAREWELL
value: "Such a sweet sorrow"
# 挂载 volumes 到 Mount Pod
- pvcSelector:
matchLabels:
...
volumeDevices:
- name: block-devices
devicePath: /dev/sda1
volumes:
- name: block-devices
persistentVolumeClaim:
claimName: block-pv
# 选择特定的 StorageClass
- pvcSelector:
matchStorageClassName: juicefs-sc
terminationGracePeriodSeconds: 60
# 选择特定的 PVC
- pvcSelector:
matchName: pvc-name
terminationGracePeriodSeconds: 60
定制 Mount Pod 或者 Sidecar 容器
通过 ConfigMap 修改配置后,推荐使用「平滑升级 Mount Pod」特性来在不重建应用 Pod 的情况下使修改生效,但是需要注意,请升级到 v0.25.2 或更新版本,v0.25.0(该功能首次发布)尚不支持某些配置平滑升级,如果希望充分利用平滑升级的能力,务必升级到最新版再操作。
如果仍在使用旧版、无法享受到平滑升级,则需要根据情况来重建应用 Pod 或 Mount Pod,具体操作在下方,请务必提前配置好「挂载点自动恢复」,避免重建 Mount Pod 后,应用 Pod 中的挂载点永久丢失。
容器镜像
使用 ConfigMap
请参考「升级 Mount Pod 容器镜像」文档。
环境变量
使用 ConfigMap
该功能最低需要 CSI 驱动版本 v0.24.5,修改后需要重建业务 Pod 生效。
mountPodPatch:
- env:
- name: DEMO_GREETING
value: "Hello from the environment"
- name: DEMO_FAREWELL
value: "Such a sweet sorrow"
使用 Secret
apiVersion: v1
kind: Secret
metadata:
name: juicefs-secret
namespace: default
labels:
# 增加该标签以启用认证信息校验
juicefs.com/validate-secret: "true"
type: Opaque
stringData:
envs: '{"BASE_URL": "http://10.0.0.1:8080/static"}'
资源限制
使用 ConfigMap
该特性需要的 CSI 驱动最低版本为 0.24.0,示例如下:
mountPodPatch:
- resources:
requests:
cpu: 100m
memory: 512Mi
阅读资源优化以了解如何恰当设置资源定义,来兼顾性能和资源占用。
挂载参数
每一个 JuiceFS 挂载点都是 juicefs mount
命令创建的,在 CSI 驱动体系中,需要通过 mountOptions
字段填写需要调整的挂载配置。
mountOptions
同时支持 JuiceFS 本身的挂载参数和 FUSE 相关选项。但要注意,虽然 FUSE 参数在命令行使用时会用 -o
传入,但在 mountOptions
中需要省略 -o
,直接在列表中追加参数即可。以下方挂载命令为例:
juicefs mount ... --cache-size=204800 -o writeback_cache,debug
翻译成 CSI 中的 mountOptions
,格式如下:
mountOptions:
# JuiceFS mount options
- cache-size=204800
# 额外的 FUSE 相关选项
- writeback_cache
- debug
使用 ConfigMap
该功能最小需要 CSI 驱动 v0.24.7。修改 ConfigMap 相关配置后,需重建业务 Pod 生效。
ConfigMap 中的配置具备最高优先级,他会递归合并覆盖 PV 中的 mountOptions
,因此为了避免出现“修改了却不生效”的误用情况,建议将所有配置迁移到 ConfigMap,不再继续使用 PV 级别的 mountOptions
。
灵活使用 pvcSelector
可实现批量修改 mountOptions
的目的。
mountPodPatch:
- pvcSelector:
matchLabels:
# 所有含有此 label 的 PVC 都将应用此配置
need-update-options: "true"
mountOptions:
- writeback
- cache-size=204800
通过 PV 定义(不推荐)
注意,如果是修改已有 PV 的挂载配置,修改后需要重建应用 Pod,才会触发重新创建 Mount Pod,令变动生效。
apiVersion: v1
kind: PersistentVolume
metadata:
name: juicefs-pv
labels:
juicefs-name: ten-pb-fs
spec:
mountOptions:
- cache-size=204800
...
通过 StorageClass 定义(不推荐)
在 StorageClass
定义中调整挂载参数。如果需要为不同应用使用不同挂载参数,则需要创建多个 StorageClass
,单独添加所需参数。
注意,StorageClass 仅仅是动态配置下用于创建 PV 的「模板」,也正因此,在 StorageClass 中修改挂载配置,不影响已经创建的 PV。如果你需要调整挂载配置,需要删除 PVC 重建,或者直接在 PV 级别调整挂载配置。
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
name: juicefs-sc
provisioner: csi.juicefs.com
mountOptions:
- cache-size=204800
parameters:
...
健康检查 & 容器回调
该特性需要的 CSI 驱动最低版本为 0.24.0,使用场景:
- 配合
readinessProbe
配合监控体系,建立告警机制; - 定制
preStopHook
,避免 sidecar 场景中,挂载容器早于业务容器退出,造成业务波动。详见 Sidecar 模式推荐设置。
- pvcSelector:
matchLabels:
custom-probe: "true"
readinessProbe:
exec:
command:
- stat
- ${MOUNT_POINT}/${SUB_PATH}
failureThreshold: 3
initialDelaySeconds: 10
periodSeconds: 5
successThreshold: 1
挂载额外的 Volume
使用场景:
- 部分对象存储服务(比如 Google 云存储)在访问时需要提供额外的认证文件,这就需要你用创建单独的 Secret 保存这些文件,然后在认证信息中引用。这样一来,CSI 驱动便会将这些文件挂载进 Mount Pod,然后在 Mount Pod 中添加对应的环境变量,令 JuiceFS 挂载时使用该文件进行对象存储的认证。
- JuiceFS 企业版支持挂载共享块设备,既可以作为缓存存储,也可以配置成数据块的永久存储。
使用 ConfigMap
该功能最低需要 CSI 驱动版本 v0.24.7,修改后需重建业务 Pod 生效。
# mount some volumes to the Mount Pod
- pvcSelector:
matchLabels:
need-block-device: "true"
volumeDevices:
- name: block-devices
devicePath: /dev/sda1
volumes:
- name: block-devices
persistentVolumeClaim:
claimName: block-pv
- pvcSelector:
matchLabels:
need-mount-secret: "true"
volumeMounts:
- name: config-1
mountPath: /root/.config/gcloud
volumes:
- name: gc-secret
secret:
secretName: gc-secret
defaultMode: 420
使用 Secret
在 JuiceFS Secret 的 configs
字段中,只能挂载额外的 Secret,无法配置共享块设备的挂载。
apiVersion: v1
kind: Secret
metadata:
name: juicefs-secret
type: Opaque
stringData:
...
# 在 configs 中填写 Secret 名称和挂载目录,将该 Secret 整体挂载进指定的目录
configs: "{gc-secret: /root/.config/gcloud}"
缓存
缓存的使用还涉及资源管理、数据预热和清理等事项,因此请移步阅读缓存来详细了解。