CSI Driver Overview

FlexFS ships a Container Storage Interface (CSI) driver that lets Kubernetes pods mount flexFS volumes as first-class persistent storage. The driver name is csi.flexfs.io.

Architecture

The CSI driver is deployed as two components:

Component	Kubernetes resource	Purpose
Controller	Deployment (default 2 replicas)	Handles dynamic volume provisioning (CreateVolume / DeleteVolume). Runs the CSI driver alongside the csi-provisioner sidecar.
Node	DaemonSet (one pod per node)	Handles mounting and unmounting volumes on individual nodes (NodePublishVolume / NodeUnpublishVolume). Runs the CSI driver alongside the csi-node-driver-registrar sidecar.

Both the controller and node pods run the same csi.flexfs binary. The binary implements all three CSI service interfaces — Identity, Controller, and Node — in a single process.

How it works

1. Identity service — responds to health probes and reports the driver name (csi.flexfs.io) and version.
2. Controller service — advertises CREATE_DELETE_VOLUME capability. For dynamic provisioning, it calls the admin server REST API to create or delete volumes.
3. Node service — the core mounting logic. When a pod needs a volume:
   • The driver creates a base FUSE mount by executing /sbin/mount.flexfs inside the node pod.
   • It then creates a bind mount from the base mount into the pod’s target path.
   • Credentials are written to a temporary file at /var/lib/kubelet/flexfs/<volume-name>/creds.
   • Each node supports up to 10 volumes concurrently.

When a pod is removed, the driver unmounts the bind mount. If no other pods reference the volume on that node, the base FUSE mount is also unmounted and the credential files are cleaned up.

Container image

The CSI driver image is based on Alpine 3.21 and contains two binaries:

• /sbin/csi.flexfs — the CSI gRPC driver
• /sbin/mount.flexfs — the FUSE mount client

Both amd64 and arm64 architectures are supported via a multi-arch build.

Caution

The node DaemonSet pod runs in privileged mode because it needs access to /dev/fuse and must perform bind mounts into the kubelet directory tree. See Troubleshooting if your cluster restricts privileged pods.

CSI driver registration

The CSI driver is registered with Kubernetes through a CSIDriver object:

apiVersion: storage.k8s.io/v1
kind: CSIDriver
metadata:
  name: csi.flexfs.io
spec:
  attachRequired: false
  fsGroupPolicy: None

• attachRequired: false — flexFS does not require a controller-attach step; volumes are mounted directly on the node.
• fsGroupPolicy: None — flexFS manages its own POSIX permissions and ACLs; Kubernetes should not modify ownership.

Provisioning modes

Mode	Editions	Description
Static provisioning	Enterprise and Community	You pre-create the volume and provide a PersistentVolume that references it by name.
Dynamic provisioning	Enterprise only	A StorageClass triggers automatic volume creation via the admin server API when a PersistentVolumeClaim is submitted.

Next steps

• Install with Helm or raw manifests
• Configuration reference for all CSI flags, Secret fields, and StorageClass parameters