How-To Use the Crusoe CSI Driver With CMK Clusters

Last Updated: Oct 23, 2025

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 file named as ssdstorage.yamlwith 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

   Deploy the Storage class

   $ kubectl apply -f ssdstorage.yaml
   storageclass.storage.k8s.io/crusoe-csi-driver-ssd-sc created

2. Create a PersistentVolumeClaim (PVC) file named as pvc.yamlwith 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

   Deploy the PVC file

   $ kubectl apply -f pvc.yaml
   persistentvolumeclaim/ssd-block created

3. Create a deployment file named as deployment.yaml 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

   
   Deploy the deployment file

   $ kubectl apply -f deployment.yaml
   deployment.apps/example-block-ssd created

4. To check the newly created persistent disk go to Crusoe Cloud GUI > Storage 
   

Using Crusoe Shared Disks:

Note:  Shared Filesystems are supported on the largest instance type in a family for GPU enabled instance types. For most GPU instance types, the largest instance type is the *.8x type.

Forl40s-48gb instances, the largest instance type is the  l40s-48gb.10x. Shared Filesystems are not supported onl40s-48gb.8x types or smaller.

1. Create a storage class file 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

   
   Deploy the Storage class
   

   $ kubectl apply -f fsstorage.yaml
   storageclass.storage.k8s.io/crusoe-csi-driver-fs-sc created

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

   
   Deploy the PVC file

   $ kubectl apply -f pvc.yaml
   persistentvolumeclaim/sharedfs-mount created

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

   Deploy the deployment file

   $ kubectl apply -f deployment.yaml
   deployment.apps/example-mount-fs created

4. To check the newly created Shared disk go to Crusoe Cloud GUI > Storage 
   

Additional Resources

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