Skip to main content

定制容器镜像

本章介绍如何设置 Mount Pod 镜像，以及自行构建 CSI 驱动组件镜像。

Mount Pod 镜像拆分​

Mount Pod 中运行着 JuiceFS 客户端，而 JuiceFS 又提供「社区版」和「商业版」客户端，因此在很长一段时间，Mount 镜像中同时包含着两个版本的 JuiceFS 客户端：

  • /usr/local/bin/juicefs：社区版 JuiceFS 客户端
  • /usr/bin/juicefs：商业版 JuiceFS 客户端

为了避免误用、同时精简容器镜像，在 CSI 驱动 0.19.0 及以上版本对镜像进行了拆分，你可以在 Docker Hub 找到 CSI 驱动所使用的 Mount Pod 容器镜像，形如：

提示

如果你需要把 Mount Pod 容器镜像从 Docker Hub 搬运到其它镜像仓库，请参考文档。

# 社区版镜像标签以 ce- 开头
juicedata/mount:ce-v1.2.0

# 商业版镜像标签以 ee- 开头
juicedata/mount:ee-5.0.23-8c7c134

# 在 0.19.0 以前，镜像标签中包含社区版和商业版客户端的版本号
# 该系列镜像不再继续更新维护
juicedata/mount:v1.0.3-4.8.3

覆盖 Mount Pod 镜像​

提示

JuiceFS CSI 驱动从 0.25.0 版本开始支持平滑升级 Mount Pod，推荐优先使用这种方法升级 Mount Pod。

JuiceFS CSI 驱动 0.17.1 及以上版本支持自定义 Mount Pod 镜像，有多种修改 Mount Pod 镜像的方式，满足不同的定制需要，根据实际情况选择合适的手段。

提示

覆盖 mount 镜像后，注意：

  • 已有的 Mount Pod 不会受影响，需要随着应用 Pod 滚动升级或者删除 Mount Pod 重建，才会采用新的镜像
  • 升级 CSI 驱动时，默认会连带升级到 mount 镜像的最新稳定版。但如果你覆盖了 mount 镜像，那么这就是固定的配置了，继续升级 CSI 驱动，也不会引入连带的 mount 镜像升级

修改 ConfigMap​

如果你的 CSI 驱动版本大于 0.24.0 可以非常方便的全局配置中修改镜像版本：

values-mycluster.yaml
globalConfig:
  mountPodPatch:
    - pvcSelector:
        matchLabels:
          custom-image: "true"
      eeMountImage: "juicedata/mount:ee-5.0.17-0c63dc5"
      ceMountImage: "juicedata/mount:ce-v1.2.0"

更改之后只需滚动升级业务容器或者杀掉 Mount Pod 即可应用最新镜像。

详参：定制 Mount Pod 和 Sidecar 容器

全局修改​

如果你用 Helm 安装 CSI 驱动，修改 mount 镜像非常简单，在 values 中定义即可：

defaultMountImage:
  # 社区版
  ce: "juicedata/mount:ce-v1.2.0"
  # 企业版
  ee: "juicedata/mount:ee-5.0.23-8c7c134"

而如果是 kubectl 直接安装，那么需要在 CSI 驱动的组件中设置环境变量：

# 社区版
kubectl -n kube-system set env daemonset/juicefs-csi-node -c juicefs-plugin JUICEFS_CE_MOUNT_IMAGE=juicedata/mount:ce-v1.2.0
kubectl -n kube-system set env statefulset/juicefs-csi-controller -c juicefs-plugin JUICEFS_CE_MOUNT_IMAGE=juicedata/mount:ce-v1.2.0

# 企业版
kubectl -n kube-system set env daemonset/juicefs-csi-node -c juicefs-plugin JUICEFS_EE_MOUNT_IMAGE=juicedata/mount:ee-5.0.23-8c7c134
kubectl -n kube-system set env statefulset/juicefs-csi-controller -c juicefs-plugin JUICEFS_EE_MOUNT_IMAGE=juicedata/mount:ee-5.0.23-8c7c134

修改完毕以后，别忘了将这些配置同时加入 k8s.yaml，避免下次安装时配置丢失。正因为 kubectl 的安装方式管理配置不方便，所以建议在生产集群采用 Helm 安装方式。

动态配置​

提示

从 v0.24 开始，CSI 驱动支持在 ConfigMap 中定制 Mount Pod 镜像，本小节所介绍的方式已经不再推荐使用。

CSI 驱动允许在 StorageClass 中进行覆盖，如果你需要为不同应用配置不同的 Mount Pod 镜像，那就需要创建多个 StorageClass，为每个 StorageClass 单独指定所使用的 Mount Pod 镜像。

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: juicefs-sc
provisioner: csi.juicefs.com
parameters:
  csi.storage.k8s.io/provisioner-secret-name: juicefs-secret
  csi.storage.k8s.io/provisioner-secret-namespace: default
  csi.storage.k8s.io/node-publish-secret-name: juicefs-secret
  csi.storage.k8s.io/node-publish-secret-namespace: default
  juicefs/mount-image: juicedata/mount:ce-v1.2.0

配置完成后，在不同的 PVC 中，通过 storageClassName 指定不同的 StorageClass，便能为不同的应用设置不同的 Mount Pod 镜像了。

静态配置​

提示

从 v0.24 开始，CSI 驱动支持在 ConfigMap 中定制 Mount Pod 镜像，本小节所介绍的方式已经不再推荐使用。

对于「静态配置」用法，需要在 PV 定义中配置 Mount Pod 镜像：

apiVersion: v1
kind: PersistentVolume
metadata:
  name: juicefs-pv
  labels:
    juicefs-name: ten-pb-fs
spec:
  capacity:
    storage: 10Pi
  volumeMode: Filesystem
  accessModes:
    - ReadWriteMany
  persistentVolumeReclaimPolicy: Retain
  csi:
    driver: csi.juicefs.com
    volumeHandle: juicefs-pv
    fsType: juicefs
    nodePublishSecretRef:
      name: juicefs-secret
      namespace: default
    volumeAttributes:
      juicefs/mount-image: juicedata/mount:ce-v1.2.0

构建镜像​

构建 Mount Pod 的容器镜像​

JuiceFS CSI 驱动采用「分离架构」，Mount Pod 默认使用的容器镜像是 juicedata/mount，社区版对应的 Dockerfile 是 docker/ce.juicefs.Dockerfile。

因此，如果要自行构建挂载镜像，可以参考下方命令克隆 JuiceFS 社区版仓库，然后直接用内置的 Dockerfile 执行构建：

# 克隆 JuiceFS 社区版仓库
git clone https://github.com/juicedata/juicefs
cd juicefs

# 切换到你想要编译的分支，或者按需要修改代码
git checkout ...

# 由于 Dockerfile 在 CSI 驱动的仓库，此处需要自行下载
curl -O https://raw.githubusercontent.com/juicedata/juicefs-csi-driver/master/docker/dev.juicefs.Dockerfile

# 构建镜像，并上传至私有镜像仓库
docker build -t registry.example.com/juicefs-csi-mount:ce-latest -f dev.juicefs.Dockerfile .
docker push registry.example.com/juicefs-csi-mount:ce-latest

参照覆盖默认容器镜像来指定刚刚构建好的 Mount Pod 的镜像。

构建 CSI 驱动组件镜像​

JuiceFS CSI Controller 及 JuiceFS CSI Node 默认使用的容器镜像是 juicedata/juicefs-csi-driver，对应的 Dockerfile 是 docker/csi.Dockerfile。

若希望深入开发 JuiceFS CSI 驱动，可以参考下方命令克隆仓库，然后执行内置的构建脚本：

# 克隆 CSI 驱动仓库
git clone https://github.com/juicedata/juicefs-csi-driver
cd juicefs-csi-driver

# 切换到你想要编译的分支，或者按需要修改代码
git checkout ...

# 用 IMAGE 环境变量指定将要构建的 CSI 驱动镜像名称，并上传至私有镜像仓库
IMAGE=registry.example.com/juicefs-csi-driver make image-dev
docker push registry.example.com/juicefs-csi-driver:dev-xxx
Follow us on X
Let's chat on Slack