Skip to main content

Installation

JuiceFS CSI Driver requires Kubernetes 1.14 and above, follow below steps to install.

Helm

In comparison to kubectl, Helm allows you to manage CSI Driver resources as a whole, and also makes it easier to modify configurations, or enable advanced features. Overall, Helm is recommended over kubectl.

Helm is a tool for managing Kubernetes charts. Charts are packages of pre-configured Kubernetes resources.

Installation requires Helm 3.1.0 and above, refer to the Helm Installation Guide.

  1. Download the Helm chart for JuiceFS CSI Driver

    helm repo add juicefs https://juicedata.github.io/charts/
    helm repo update
    helm fetch --untar juicefs/juicefs-csi-driver
    cd juicefs-csi-driver
    # Installation configurations is included in values.yaml, review this file and modify to your needs
    cat values.yaml
  2. Check kubelet root directory

    Execute the following command.

    ps -ef | grep kubelet | grep root-dir

    If the result is not empty or the default /var/lib/kubelet, it means that the kubelet root directory is customized, you need to set kubeletDir to the current kubelet root directly in values.yaml.

    values.yaml
    kubeletDir: <kubelet-dir>
  3. Deploy

    Execute below commands to deploy JuiceFS CSI Driver:

    helm repo add juicefs https://juicedata.github.io/charts/
    helm repo update
    helm install juicefs-csi-driver juicefs/juicefs-csi-driver -n kube-system -f ./values.yaml
  4. Verify installation

    Verify all CSI Driver components are running:

    $ 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

    Learn about JuiceFS CSI Driver architecture, and components functionality in Introduction.

It's recommended that you include the CSI Driver Helm chart in the version control system, so that any changes to values.yaml can be restored.

kubectl

If installed using kubectl, any configuration changes require manual editing, and can easily cause trouble if you are not familiar with CSI Controller. If you'd like to enable advanced features (e.g. enable pathPattern), or just want to manage resources easier, consider installing via Helm.

  1. Check kubelet root directory

    Execute the following command on any non-Master node in the Kubernetes cluster.

    ps -ef | grep kubelet | grep root-dir
  2. Deploy

    • If above command returns a non-empty result other than /var/lib/kubelet, it means kubelet root directory (--root-dir) was customized, you need to update the kubelet path in the CSI Driver's deployment file.

      # Replace {{KUBELET_DIR}} in the below command with the actual root directory path of kubelet.

      # Kubernetes version >= 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 version < 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 -
    • If the command returns an empty result, deploy without modifications:

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

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

Verify installation

Verify all CSI components are up and running:

$ 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 is a DaemonSet, and by default runs on all Kubernetes worker nodes, so CSI Node pod amount should match node count. If the numbers don't match, check if any of the nodes are tainted, and resolve them according to the actual situation. You can also run CSI Node Service on selected nodes.

Learn about JuiceFS CSI Driver architecture, and components functionality in Introduction.

ARM64 caveats

From v0.11.1 and above, JuiceFS CSI Driver supports using container images in the ARM64 environment, if you are faced with an ARM64 cluster, you need to change some image tags before installation. No other steps are required for ARM64 environments.

Images that need to replaced is listed below, find our the suitable version for your cluster via the links:

Original container image nameNew container image name
quay.io/k8scsi/livenessprobek8s.gcr.io/sig-storage/livenessprobe
quay.io/k8scsi/csi-provisionerk8s.gcr.io/sig-storage/csi-provisioner
quay.io/k8scsi/csi-node-driver-registrark8s.gcr.io/sig-storage/csi-node-driver-registrar

Helm

Add sidecars to values.yaml, to overwrite selected images:

sidecars:
livenessProbeImage:
repository: k8s.gcr.io/sig-storage/livenessprobe
tag: "v2.6.0"
csiProvisionerImage:
repository: k8s.gcr.io/sig-storage/csi-provisioner
tag: "v2.2.2"
nodeDriverRegistrarImage:
repository: k8s.gcr.io/sig-storage/csi-node-driver-registrar
tag: "v2.5.0"

kubectl

Replace some container images in k8s.yaml (use gnu-sed instead under macOS):

sed --in-place --expression='s@quay.io/k8scsi/livenessprobe:v1.1.0@k8s.gcr.io/sig-storage/livenessprobe:v2.6.0@' k8s.yaml
sed --in-place --expression='s@quay.io/k8scsi/csi-provisioner:v1.6.0@k8s.gcr.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@k8s.gcr.io/sig-storage/csi-node-driver-registrar:v2.5.0@' k8s.yaml