Skip to main content

安装

安装前，请先确认：

  • Kubernetes 集群是 1.14 及以上版本
  • 集群能从外网拉取镜像，比如 Docker Hub 和 Quay，如果无法从这两个镜像仓库下载资源，考虑先「搬运镜像」。
注意

在 JuiceFS 企业版私有部署环境下，CSI 驱动的安装并没有特殊步骤。不过请注意，由于使用私有部署控制台，你需要在「文件系统认证信息」中需要填写 envs 字段，指定私有部署的控制台地址。

Helm​

相比 kubectl，Helm 允许你将 CSI 驱动中的各种资源、组件作为一个整体来管理，修改配置、启用高级特性，也只需要对 values 文件做少量编辑，无疑方便了许多，是我们更为推荐的安装方式。但如果你不熟悉 Helm，而且仅仅希望体验和评估 CSI 驱动，请参考下方的 kubectl 安装方式。

安装需要 Helm 3.1.0 及以上版本，请参照 Helm 文档进行安装。

  1. 加入 JuiceFS CSI 驱动的 Helm 仓库，并且创建出集群专属的配置文件，比方说当前集群名为 mycluster，那么推荐在 values-mycluster.yaml 中撰写该集群专属的配置。这份文件中的内容，会递归覆盖到原始的 values.yaml。

    helm repo add juicefs https://juicedata.github.io/charts/
    helm repo update

    mkdir juicefs-csi-driver && cd juicefs-csi-driver

    vi values-mycluster.yaml

  2. 检查 kubelet 根目录

    在 Kubernetes 集群中任意一个非 Master 节点上执行以下命令：

    ps -ef | grep kubelet | grep root-dir

    如果结果不为空或者 /var/lib/kubelet，则代表该集群的 kubelet 的根目录（--root-dir）做了定制，需要在 values 中将 kubeletDir 根据实际情况进行设置：

    values-mycluster.yaml
    kubeletDir: <kubelet-dir>

  3. 继续阅读 values.yaml，如果有其他需要修改的地方，一并在上方创建的 values-mycluster.yaml 中进行覆盖。常见需要根据集群调整的项目有：

    • 搜索 repository 字样，可选地调整各组件的镜像仓库，如果需要修改为集群私有镜像仓库，那么还伴随着镜像搬运工作
    • 搜索 resources 字样，可选地调整各组件的资源占用

修改结果示范：

values-mycluster.yaml
kubeletDir: <kubelet-dir>

image:
  repository: registry.example.com/juicefs-csi-driver
dashboardImage:
  repository: registry.example.com/csi-dashboard
sidecars:
  livenessProbeImage:
    repository: registry.example.com/k8scsi/livenessprobe
  nodeDriverRegistrarImage:
    repository: registry.example.com/k8scsi/csi-node-driver-registrar
  csiProvisionerImage:
    repository: registry.example.com/k8scsi/csi-provisioner
  csiResizerImage:
    repository: registry.example.com/k8scsi/csi-resizer

  1. 安装 CSI 驱动：

    # 不论是初次安装还是后续的配置变更，都可以运行这一行命令达到效果
    helm upgrade --install juicefs-csi-driver juicefs/juicefs-csi-driver -n kube-system -f ./values-mycluster.yaml

推荐将上方的 values 文件进行源码管理，这样一来就算配置不断变化，也能对其进行追溯和回滚。

kubectl​

kubectl 是较为简单直接的安装方式，如果你只是希望体验和评估 CSI 驱动，推荐这种安装方式，但在生产环境则不推荐这样安装：用 kubectl 直接安装的话，意味着后续对 CSI 驱动的任何配置修改都需要手动操作，若不熟悉极容易出错。如果你希望开启某些 CSI 驱动的高级特性（例如「启用 pathPattern」），或者想要更加体系化地管理资源，请优先选用 Helm 安装方式。

  1. 检查 kubelet 根目录

    在 Kubernetes 集群中任意一个非 Master 节点上执行以下命令：

    ps -ef | grep kubelet | grep root-dir

  2. 部署

    • 如果上一步检查命令返回的结果不为空或者 /var/lib/kubelet，则代表该集群 kubelet 定制了根目录（--root-dir），因此需要在 CSI 驱动的部署文件中更新 kubelet 根目录路径：

      # 请将下述命令中的 {{KUBELET_DIR}} 替换成 kubelet 当前的根目录路径

      # Kubernetes 版本 >= v1.18
      curl -sSL https://raw.githubusercontent.com/juicedata/juicefs-csi-driver/master/deploy/k8s.yaml | sed 's@/var/lib/kubelet@{{KUBELET_DIR}}@g' | kubectl apply -f -

      # Kubernetes 版本 < v1.18
      curl -sSL https://raw.githubusercontent.com/juicedata/juicefs-csi-driver/master/deploy/k8s_before_v1_18.yaml | sed 's@/var/lib/kubelet@{{KUBELET_DIR}}@g' | kubectl apply -f -

    • 如果上方检查命令返回的结果为空，则无需修改配置，直接部署：

      # Kubernetes 版本 >= v1.18
      kubectl apply -f https://raw.githubusercontent.com/juicedata/juicefs-csi-driver/master/deploy/k8s.yaml

      # Kubernetes 版本 < v1.18
      kubectl apply -f https://raw.githubusercontent.com/juicedata/juicefs-csi-driver/master/deploy/k8s_before_v1_18.yaml

检查部署状态​

用下方命令确认 CSI 驱动组件正常运行：

$ kubectl -n kube-system get pods -l app.kubernetes.io/name=juicefs-csi-driver
NAME                       READY   STATUS    RESTARTS   AGE
juicefs-csi-controller-0   3/3     Running   0          22m
juicefs-csi-node-v9tzb     3/3     Running   0          14m

CSI Node Service 是一个 DaemonSet，默认在所有节点部署，因此在上方命令的输出中，CSI Node Pod 数量应该与 worker 节点数相同。如果你注意到数量不一致，请检查是否有节点被打上了污点。视情况删除污点，或给 CSI Node Service 打上对应的容忍，来修复此问题。如果你有需要，也可以仅在某些节点上运行 CSI Node Service。

如果你对各组件功能仍有疑惑，请详读「架构」。

以 Sidecar 模式安装​

Sidecar 与默认的容器挂载方式有很大不同，包括无法复用挂载客户端，以及无法设置挂载点自动恢复。决定采纳之前，务必仔细阅读「Sidecar 模式注意事项」。

Helm​

Serverless 注意事项

从 v0.23.5 开始，Helm chart 支持名为 mountMode: serverless 的特殊模式。这种模式与 sidecar 相同，但移除了各种 serverless 环境中不支持的配置，比如 hostPath 挂载点，以及 privileged 权限。

serverless 模式将允许在 serverless 虚拟节点上安装 JuiceFS CSI 驱动，不再需要一个实际节点。

在 values 中修改配置：

values-mycluster.yaml
mountMode: sidecar

若集群中使用 CertManager 管理证书，需要在 values 中添加如下配置：

values-mycluster.yaml
mountMode: sidecar
webhook:
  certManager:
    enabled: true

重新安装，令配置生效：

helm upgrade --install juicefs-csi-driver juicefs/juicefs-csi-driver -n kube-system -f ./values-mycluster.yaml
注意

安装以后，必须等待所有组件运行正常以后，才能继续执行下一步打标签。如果 Controller 容器尚未健康运行，就为命名空间打好标签，该命名空间的所有 Pod 都将无法创建，卡死在 Webhook 的注入检查这一关。

对所有需要使用 JuiceFS CSI 驱动的命名空间打上下述标签，需要注意的是普通集群和 Serverless 的标签有所不同：

# 普通集群
kubectl label namespace $NS juicefs.com/enable-injection=true --overwrite
# Serverless 集群
kubectl label namespace $NS juicefs.com/enable-serverless-injection=true --overwrite

kubectl​

考虑到安装文件需要用脚本生成，不便于源码管理、以及未来升级 CSI 驱动时的配置梳理，生产环境不建议用 kubectl 进行安装。

# Sidecar 模式需要在安装过程中生成和使用证书，渲染对应的 YAML 资源，请直接使用安装脚本
wget https://raw.githubusercontent.com/juicedata/juicefs-csi-driver/master/scripts/juicefs-csi-webhook-install.sh
chmod +x ./juicefs-csi-webhook-install.sh

# 用脚本生成安装文件
./juicefs-csi-webhook-install.sh print > juicefs-csi-sidecar.yaml

# 对该文件配置进行梳理，然后安装
kubectl apply -f ./juicefs-csi-sidecar.yaml

也可以用一行命令进行更快速的直接安装：

./juicefs-csi-webhook-install.sh install
注意

安装以后，必须等待所有组件运行正常以后，才能继续执行下一步打标签。如果 Controller 容器尚未健康运行，就为命名空间打好标签，该命名空间的所有 Pod 都将无法创建，卡死在 Webhook 的注入检查这一关。

对所有需要使用 JuiceFS CSI 驱动的命名空间打上下述标签，需要注意的是普通集群和 Serverless 的标签有所不同：

# 普通集群
kubectl label namespace $NS juicefs.com/enable-injection=true --overwrite
# Serverless 集群
kubectl label namespace $NS juicefs.com/enable-serverless-injection=true --overwrite

若集群中使用 CertManager 管理证书，可以使用下方命令生成安装文件或直接安装：

# 生成配置文件
./juicefs-csi-webhook-install.sh print --with-certmanager > juicefs-csi-sidecar.yaml
kubectl apply -f ./juicefs-csi-sidecar.yaml

# 一键安装
./juicefs-csi-webhook-install.sh install --with-certmanager

如果你不得不在生产集群使用此种方式进行安装，那么一定要将生成的 juicefs-csi-sidecar.yaml 进行源码管理，方便追踪配置变更的同时，也方便未来升级 CSI 驱动时，进行配置对比梳理。

以进程挂载模式安装​

在进程挂载模式下，JuiceFS 客户端不再运行在独立的 Pod 中，而是运行在 CSI Node Service 容器中，所有需要挂载的 JuiceFS PV 都会在 CSI Node Service 容器中以进程模式挂载。详情可以参考「进程挂载模式」。

Helm​

在 values.yaml 中修改配置：

values.yaml
mountMode: process

重新安装，令配置生效：

helm upgrade --install juicefs-csi-driver juicefs/juicefs-csi-driver -n kube-system -f ./values.yaml

kubectl​

在 CSI Node Service 和 CSI Controller 的启动参数中添加 --by-process=true，就能启用进程挂载模式。

安装在 ARM64 环境​

CSI 驱动在 v0.11.1 及之后版本支持 ARM64 环境的容器镜像，如果你的集群是 ARM64 架构，需要在执行安装前，更换部分容器镜像，其他安装步骤都相同。

需要替换的镜像如下，请通过下方链接的网页，确定各镜像合适的版本（如果无法正常访问 k8s.gcr.io，请考虑先「搬运镜像」）：

原镜像名称新镜像名称
quay.io/k8scsi/livenessproberegistry.k8s.io/sig-storage/livenessprobe
quay.io/k8scsi/csi-provisionerregistry.k8s.io/sig-storage/csi-provisioner
quay.io/k8scsi/csi-node-driver-registrarregistry.k8s.io/sig-storage/csi-node-driver-registrar
quay.io/k8scsi/csi-resizer:registry.k8s.io/sig-storage/csi-resizer

Helm​

在 values.yaml 中增加 sidecars 配置，用于覆盖容器镜像：

values.yaml
sidecars:
  livenessProbeImage:
    repository: registry.k8s.io/sig-storage/livenessprobe
    tag: "v2.6.0"
  csiProvisionerImage:
    repository: registry.k8s.io/sig-storage/csi-provisioner
    tag: "v2.2.2"
  nodeDriverRegistrarImage:
    repository: registry.k8s.io/sig-storage/csi-node-driver-registrar
    tag: "v2.5.0"
  csiResizerImage:
    repository: registry.k8s.io/sig-storage/csi-resizer
    tag: "v1.8.0"

kubectl​

对 k8s.yaml 中部分镜像以及 provisioner sidecar 的启动参数进行替换（macOS 请换用 gnu-sed）：

sed --in-place --expression='s@quay.io/k8scsi/livenessprobe:v1.1.0@registry.k8s.io/sig-storage/livenessprobe:v2.6.0@' k8s.yaml
sed --in-place --expression='s@quay.io/k8scsi/csi-provisioner:v1.6.0@registry.k8s.io/sig-storage/csi-provisioner:v2.2.2@' k8s.yaml
sed --in-place --expression='s@quay.io/k8scsi/csi-node-driver-registrar:v1.3.0@registry.k8s.io/sig-storage/csi-node-driver-registrar:v2.5.0@' k8s.yaml
sed --in-place --expression='s@quay.io/k8scsi/csi-resizer:v1.0.1@registry.k8s.io/sig-storage/csi-resizer:v1.8.0@' k8s.yaml
sed --in-place --expression='s@enable-leader-election@leader-election@' k8s.yaml

卸载​

删除是安装的逆向操作，对于 Helm 安装的，执行以下命令即可：

helm uninstall juicefs-csi-driver

如果使用的是 kubectl 安装方式，只需将相应安装命令中的 apply 替换为 delete 即可，例如：

kubectl delete -f https://raw.githubusercontent.com/juicedata/juicefs-csi-driver/master/deploy/k8s.yaml
Follow us on X
Let's chat on Slack