JuiceFS CSI Driver

The JuiceFS Container Storage Interface (CSI) Driver implements the CSI specification for container orchestrators to manage the lifecycle of JuiceFS filesystems.

Installation

Deploy the driver:

kubectl apply -f https://raw.githubusercontent.com/juicedata/juicefs-csi-driver/master/deploy/k8s.yaml

Additional steps could be required on some provider, e.g. Aliyun Container Service Kubernetes. See Troubleshooting#AttachVolume.Attach failed for details.

Upgrade

We have two components to upgrade:

CSI Driver
JuiceFS client in CSI Driver

Upgrade CSI Driver

Stop all pods using this driver.
Upgrade driver:
- If you're using latest tag, simple run kubectl rollout restart -f k8s.yaml and make sure juicefs-csi-controller and juicefs-csi-node pods are restarted.
- If you have pinned to a specific version, modify your k8s.yaml to a newer version, then run kubectl apply -f k8s.yaml.

Visit here for more versions.

Upgrade JuiceFS client

Refer to the notes in Examples section below.

Examples

Before the example, you need to:

Get yourself familiar with how to setup Kubernetes and how to create JuiceFS filesystem.
When creating JuiceFS filesystem, make sure it is accessible from Kuberenetes cluster. It is recommended to create the filesystem inside the same region as Kubernetes cluster.
Install JuiceFS CSI driver following the Installation steps.

Example links

Basic
Static provisioning
Dynamic provisioning

Notes:

Since JuiceFS is an elastic filesystem it doesn't really enforce any filesystem capacity. The actual storage capacity value in persistence volume and persistence volume claim is not used when creating the filesystem. However, since the storage capacity is a required field by Kubernetes, you must specify the value and you can use any valid value e.g. 10Pi for the capacity.
Automatically upgrade of JuiceFS Client in JuiceFS CSI Driver image is now supported, and can be disabled. JuiceFS Client will upgrade automatically everytime before mounting a PersistentVolume if enabled. We also offer different ways to control this function:
- If you are using JuiceFS CSI Driver image with latest tag, then auto-upgrade is enabled by default. JuiceFS Client will try to upgrade itself everytime before mounting, a very short check time will be taken if no upgrade.
- If you have pinned JuiceFS CSI Driver to a specific version, then auto-upgrade is disabled by default. You can still enable this through environment variables:
  - JFS_AUTO_UPGRADE: enable auto-upgrade if set to none empty value, otherwise disable
  - JFS_AUTO_UPGRADE_TIMEOUT: the timeout for auto-upgrade in seconds(default 10)
  configure the above environment variables when deploy JuiceFS CSI Driver. Notice JuiceFS CSI Driver need to be re-deployed to ensure the environment variables are applied to controller and node driver.

CSI Specification Compatibility

JuiceFS CSI Driver \ CSI Version	v0.3	v1.0
master branch (csi-v1)	no	yes
csi-v0 branch	yes	no

Interfaces

Currently only static provisioning is supported. This means an JuiceFS filesystem needs to be created manually on juicefs web console first. After that it can be mounted inside a container as a volume using the driver.

The following CSI interfaces are implemented:

Node Service: NodePublishVolume, NodeUnpublishVolume, NodeGetCapabilities, NodeGetInfo, NodeGetId
Identity Service: GetPluginInfo, GetPluginCapabilities, Probe