Container Storage Interface (CSI) for S3

Container storage interface is an industry standard that enables storage vendors to develop a plugin once and have it work across a number of container orchestration systems.

S3 is a simple and highly scalable distributed file system, to store and serve billions of files fast!

• Deployment
  • Kubernetes (kubectl)
  • Kubernetes (helm)
• Update (Safe rollout)
• Testing
• Static and dynamic provisioning
• DataLocality
• License
• Code of conduct

Deployment

Kubernetes (kubectl)

Prerequisites:

• Already have a working Kubernetes cluster (includes kubectl)
• Already have a working S3 cluster

Install

Helm

1. Add the helm repo;

helm repo add s3-csi https://hanzoai.github.io/s3-csi/helm

2. Check versions by helm repo update s3-csi and helm search repo s3-csi

Source

1. Clone this repository

git clone https://github.com/hanzoai/s3-csi.git

2. Adjust your S3 Filer address via variable S3_FILER in deploy/kubernetes/s3-csi.yaml (2 places)

3. Apply the container storage interface for S3 for your cluster. Use the '-pre-1.17' version for any cluster pre kubernetes version 1.17.

To generate an up to date manifest from the helm chart, do:

$ helm template s3 ./deploy/helm/s3-csi > deploy/kubernetes/s3-csi.yaml

Check the kubelet root directory ,Execute the following command

ps -ef | grep kubelet | grep root-dir

If the result returned from the previous check command is not empty, the root directory (eg:--root-dir=/data/k8s/kubelet/data) representing the kubelet is not the default value (/var/lib/kubelet), so you need to update the kubelet root-dir in the CSI driven deployment file and deploy:

sed 's+/var/lib/kubelet+/data/k8s/kubelet/data+g'  deploy/kubernetes/s3-csi.yaml | kubectl apply -f - 

If the result returned by the previous check command is null, you can directly deploy it without modifying the configuration:

$ kubectl apply -f deploy/kubernetes/s3-csi.yaml

4. Ensure all the containers are ready and running

$ kubectl get po -n kube-system

TLS Support

The provided static manifest deploy/kubernetes/s3-csi.yaml does not include TLS configuration by default. To enable TLS, it is recommended to use Helm with tlsSecret configured. If you must use static manifests, you will need to manually patch the s3-mount and s3-node DaemonSets to include the necessary TLS environment variables and volume mounts.

Uninstall

$ kubectl delete -f deploy/kubernetes/sample-busybox-pod.yaml
$ kubectl delete -f deploy/kubernetes/sample-s3-pvc.yaml
$ kubectl delete -f deploy/kubernetes/s3-csi.yaml

Kubernetes (helm)

Install

1. Clone project

git clone https://github.com/hanzoai/s3-csi.git

2. Edit ./deploy/helm/s3-csi/values.yaml if required and Install

helm install --set s3Filer=<filerHost:port> s3-csi-driver ./deploy/helm/s3-csi

Example with multiple filers :

helm install s3-csi-driver ./deploy/helm/s3-csi/ \
  --namespace s3-csi-driver \
  --set s3Filer="<filerHost:port>\,<filerHost:port>\,<filerHost:port>\,<filerHost:port>\,<filerHost:port>"

Uninstall

helm uninstall s3-csi-driver

Update (Safe rollout)

Updating s3-csi-driver DaemonSet (DS) will break processeses who implement fuse mount: newly created pods will not remount net device.

For safe update set node.updateStrategy.type: OnDelete for manual update. Steps:

1. delete DS pods on the node where there is no s3 PV
2. cordon or taint node
3. evict or delete pods with s3 PV
4. delete DS pod on node
5. uncordon or remove taint on node
6. repeat all steps on [all nodes]

Testing

1. Create a persistent volume claim for 5GiB with name s3-csi-pvc and storage class s3-storage. The requested size is applied as a quota to the S3 collection used by the mount.

$ kubectl apply -f deploy/kubernetes/sample-s3-pvc.yaml

2. Verify if the persistant volume claim exists and wait until its the STATUS is Bound

$ kubectl get pvc

3. After its in Bound state, create a sample workload mounting that volume

$ kubectl apply -f deploy/kubernetes/sample-busybox-pod.yaml

4. Verify the storage mount of the busybox pod

$ kubectl exec my-csi-app -- df -h

Capacity limits

For dynamically provisioned volumes, resources.requests.storage is enforced by the S3 FUSE mount and reported by df. Once the mount observes that the quota has been reached, further writes fail with ENOSPC. PVC expansion updates the mount quota.

The quota is collection-based and enforced by each CSI-managed mount, rather than stored as an authoritative server-side limit. By default, every dynamic volume gets its own collection, so its quota is isolated. If multiple volumes are configured to use the same collection, their usage is shared and they do not have independent per-directory quotas. Writes through another S3 client that does not use the quota-configured mount are not restricted by this CSI quota.

Because enforcement is mount-side, concurrent writers on different mounts can briefly exceed the configured capacity before collection usage is refreshed.

For statically provisioned Kubernetes volumes, the driver reads spec.capacity.storage from the PersistentVolume matching spec.csi.volumeHandle. Other orchestrators receive volumeCapacity from dynamic CreateVolume calls; static integrations can provide the same value in bytes through the volume context.

Static and dynamic provisioning

By default, driver will create separate folder (/buckets/<volume-id>) and will use separate collection (volume-id) for each request. Sometimes we need to use exact collection name or change replication options. It can be done via creating separate storage class with options:

kind: StorageClass
apiVersion: storage.k8s.io/v1
metadata:
  name: s3-special
provisioner: s3-csi-driver
parameters:
  collection: mycollection
  replication: "011"
  diskType: "ssd"

There is another use case when we need to access one folder from different pods with ro/rw access. In this case we do not need additional StorageClass. We need to create PersistentVolume:

apiVersion: v1
kind: PersistentVolume
metadata:
  name: s3-static
spec:
  accessModes:
  - ReadWriteMany
  capacity:
    storage: 1Gi
  csi:
    driver: s3-csi-driver
    volumeHandle: dfs-test
    volumeAttributes:
      collection: default
      replication: "011"
      path: /path/to/files
      diskType: "ssd"
    readOnly: true
  persistentVolumeReclaimPolicy: Retain
  volumeMode: Filesystem

and bind PersistentVolumeClaim(s) to it:

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: s3-static
spec:
  storageClassName: ""
  volumeName: s3-static
  accessModes:
  - ReadWriteMany
  resources:
    requests:
      storage: 1Gi

DataLocality

DataLocality (inspired by Longhorn) allows instructing the storage-driver which volume-locations will be used or preferred in Pods to read & write.

It auto-sets mount-options based on the location a pod is scheduled in and the locality-option wanted. The option can be set and overridden in Driver, StorageClass and PersistentVolume.

Setup

Change the type of locality

Level	Location
Driver	Helm: values.yaml -> dataLocality Or DaemonSet -> Container csi-s3-plugin -> args --dataLocality=
StorageClass	parameter.dataLocality
PersistentVolume	spec.csi.volumeAttributes.dataLocality

Driver < StorageClass < PersistentVolume

Available options

Option	Effect
none (default)	Changes nothing
write_preferLocalDc	Sets the DataCenter-mount-option to the current Node-DataCenter, making writes local and allowing reads to occur wherever read data is stored. More Details

Requirements

Volume-Servers and the CSI-Driver-Node need to have the locality-option DataCenter correctly set (currently only this option is required).

This can be done manually (although quite tedious) or injected by the Container-Orchestration.

Automatic injection

Kubernetes

Unfortunately Kubernetes doesnt allow grabbing node-labels, which contain well-known region-labels, and setting them as environment-variables. The DownwardAPI is very limited in that regard. (see #40610)

Therefore a workaround must be used. KubeMod can be used based on this comment. This of course requires KubeMod to be installed.

You can activate it in the Helm-Chart values.yaml -> node.injectTopologyInfoFromNodeLabel.enabled. node.injectTopologyInfoFromNodeLabel.labels decides which labels are grabbed from the node.

It is recommended to use well-known labels to avoid confusion.

License

Apache v2 license

Code of conduct

Participation in this project is governed by Kubernetes/CNCF code of conduct