How-To Setup Crusoe CSI on Self-Managed Kubernetes Cluster

Last Updated: Oct 28, 2025

Introduction

Crusoe provides a growing suite of add-ons and plugins designed to extend the functionality of self-managed Kubernetes clusters hosted on Crusoe Cloud. One such add-on is the Container Storage Interface (CSI) driver, which allows workloads in your cluster to provision and manage Crusoe-supported disk types as PersistentVolumes. Currently, this includes both Persistent Disks and Shared Disks.

This page provides a step-by-step guide and outlines the steps to install the Crusoe CSI Driver within your self-managed Kubernetes cluster. Please note, these same instructions can be followed to install the driver on a Crusoe Managed Kubernetes (CMK) cluster after it has been provisioned.

Prerequisites

• Access to the Crusoe CLI or Crusoe Console
• Valid Crusoe authentication credentials
• An existing self-managed Kubernetes cluster hosted on Crusoe Cloud (e.g. RKE2)
• Successful Helm installation

Step-by-Step Instructions

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.

Step 1: Setup Crusoe Credentials in CMK cluster

Generate Security Token

As the CSI Driver will communicate with the Crusoe Cloud API to orchestrate storage operations, you will have to set up credentials in your Kubernetes cluster which the driver can then use to communicate with the API. Here is a template .yaml file which can be modified with your credentials and applied to your cluster.

You can generate the API token in the Security → Tokens tab. 

Once the token is generated, it will display the Crusoe access key and secret key. Make sure to securely note down the secret credentials, as it will not be shown again.

Create Namespace

Create a Kubernetes namespace to install all CSI-related components. If you're manually installing the driver on a CMK cluster after provisioning, you can skip this step and use the existing crusoe-system namespace.

kubectl create namespace crusoe-csi-driver   

Create Secret 

Create a Kubernetes Secret using one of the methods below to store the token generated in the previous steps: 

apiVersion: v1
data:
  CRUSOE_ACCESS_KEY: <base-64 encoded Crusoe Access Key>
  CRUSOE_SECRET_KEY: <base-64 encoded Crusoe Secret Key>
kind: Secret
metadata:
  name: crusoe-api-keys
  namespace: crusoe-csi-driver

kubectl create secret generic crusoe-api-keys -n crusoe-csi-driver -o yaml \
--from-literal=CRUSOE_ACCESS_KEY=$YOUR_CRUSOE_ACCESS_KEY \
--from-literal=CRUSOE_SECRET_KEY=$YOUR_CRUSOE_SECRET_KEY

If you haven’t already added the Helm repository, you can do so with the following command:

helm repo add <repo alias> https://crusoecloud.github.io/crusoe-csi-driver-helm-charts/charts

helm repo update

To view the available charts in the Crusoe repository, use:

helm search repo crusoe

Step 3: Install Helm Chart

helm install <release-name> <repo alias>/crusoe-csi-driver -n crusoe-csi-driver

$ helm install csi csi-driver/crusoe-csi-driver -n crusoe-system

NAME: csi
LAST DEPLOYED: Fri Jun 27 15:23:15 2025
NAMESPACE: crusoe-system
STATUS: deployed
REVISION: 1
TEST SUITE: None    

helm delete <release-name>

$ 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