Introduction

Crusoe offers a growing collection of add-ons and plugins that enhance the capabilities of Crusoe Managed Kubernetes (CMK) clusters. Among these is the Container Storage Interface (CSI) driver add-on, which enables workloads within your cluster to create and manage supported Crusoe disk types  as PersistentVolumes. Currently, this includes both Persistent Disks and Shared Disks. 

This page provides a step-by-step guide and outlines the various ways to use the Crusoe CSI Driver within your CMK cluster.

Prerequisites

• Access to the Crusoe CLI or Crusoe Console
• Valid Crusoe authentication credentials
• An existing Crusoe Managed Kubernetes (CMK) cluster
• Helm installed (required if installing the add-on after cluster creation)

Step-by-Step Instructions

There are two ways to use the Crusoe CSI Driver with your CMK clusters:

1. Enable the add-on during cluster creation.
2. Manually install the add-on using Helm after the cluster has been created.

Enable CSI Add-On at Creation 

Once the cluster is provisioned with the CSI add-on selected, the CSI drivers for SSD and SharedFS will get installed by default on the CMK cluster.

$ kubectl get csidrivers -A
NAME                ATTACHREQUIRED   PODINFOONMOUNT   STORAGECAPACITY   TOKENREQUESTS   REQUIRESREPUBLISH   MODES        AGE
fs.csi.crusoe.ai    true             false            false             <unset>         false               Persistent   6d23h
ssd.csi.crusoe.ai   true             false            false             <unset>         false               Persistent   6d23h

Post Cluster Creation Setup via Helm 

While we recommend enabling the CSI driver add-on during cluster creation for a clean setup, it can also be manually installed after the CMK cluster has been provisioned. For guidance on installing it post-cluster creation—either on CMK or a self-managed cluster—please refer to this article.

Note: The Crusoe CSI Driver is officially supported only on Crusoe Managed Kubernetes (CMK) clusters. Other non-CMK environments may work but are supported on a best-effort basis. If you're deploying the driver on a self-managed Kubernetes cluster, it is strongly recommended to update the crusoe.projectID value to match the Crusoe project ID associated with your node VMs.

Examples of Configuring Kubernetes Storage with Crusoe CSI

Using Crusoe Persistent Disks:

1. Create a storage class with ssd.csi.crusoe.ai provisioner as shown:
   Note: Default StorageClass reclaim policy is Delete. 

   apiVersion: storage.k8s.io/v1
   kind: StorageClass
   metadata:
     name: crusoe-csi-driver-ssd-sc
   provisioner: ssd.csi.crusoe.ai
   volumeBindingMode: WaitForFirstConsumer
   allowVolumeExpansion: true

2. Create a PersistentVolumeClaim (PVC) with the desired volumeMode (e.g., Block, ReadOnly, or Filesystem). The example below demonstrates a PVC configured for block storage.

   apiVersion: v1
   kind: PersistentVolumeClaim
   metadata:
     name: ssd-block
   spec:
     accessModes:
       - ReadWriteOnce
     storageClassName: crusoe-csi-driver-ssd-sc
     resources:
       requests:
         storage: 2Gi
     volumeMode: Block

3. Create a deployment that uses the PVC. This will automatically provision a Persistent Volume (PV)—a persistent disk that will appear in your Crusoe Console.

   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: example-block-ssd
   spec:
     replicas: 1
     selector:
       matchLabels:
         app: example-block-ssd
     template:
       metadata:
         labels:
           app: example-block-ssd
       spec:
         terminationGracePeriodSeconds: 0
         containers:
           - name: example-block-ssd
             image: ubuntu:24.04
             command: ["sleep", "infinity"]
             volumeDevices:
               - devicePath: "/dev/xvda"
                 name: myblockdevice
         volumes:
           - name: myblockdevice
             persistentVolumeClaim:
               claimName: ssd-block
               readOnly: false

Using Crusoe Shared Disks:

1. Create a storage class with fs.csi.crusoe.ai provisioner as shown:
   Note: Default StorageClass reclaim policy is Delete. 

   apiVersion: storage.k8s.io/v1
   kind: StorageClass
   metadata:
     name: crusoe-csi-driver-fs-sc
   provisioner: fs.csi.crusoe.ai
   volumeBindingMode: WaitForFirstConsumer
   allowVolumeExpansion: true

2. Create a PersistentVolumeClaim (PVC) with the FileSystem volumeMode.

   apiVersion: v1
   kind: PersistentVolumeClaim
   metadata:
     name: sharedfs-mount
   spec:
     accessModes:
       - ReadWriteMany
     storageClassName: crusoe-csi-driver-fs-sc
     resources:
       requests:
         storage: 15Ti
     volumeMode: Filesystem

3. Create a deployment that uses the PVC. This will automatically provision a Persistent Volume (PV)—a persistent disk that will appear in your Crusoe Console.

   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: example-mount-fs
   spec:
     replicas: 2
     selector:
       matchLabels:
         app: example-mount-fs
     template:
       metadata:
         labels:
           app: example-mount-fs
       spec:
         topologySpreadConstraints:
           - maxSkew: 1
             topologyKey: kubernetes.io/hostname
             labelSelector:
               matchLabels:
                 app: example-mount-fs
             whenUnsatisfiable: DoNotSchedule
         terminationGracePeriodSeconds: 0
         containers:
           - name: example-mount-fs
             image: ubuntu:24.04
             command: ["sleep", "infinity"]
             volumeMounts:
               - mountPath: "/vol/myvolume"
                 name: myvolume
         volumes:
           - name: myvolume
             persistentVolumeClaim:
               claimName: sharedfs-mount
               readOnly: false

Additional Resources

• StorageClass-K8s
• Persistent Volumes
• CMK Documentation
• Crusoe CSI Driver GitHub
• How-To Setup Crusoe CSI on Self-Managed Kubernetes Cluster