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 and csi-resizer sidecars.
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 and EXPAND_VOLUME. For dynamic provisioning it calls the admin server REST API to create, expand, or delete volumes. The sidecars that drive it (csi-provisioner, csi-resizer) run alongside it in the controller Deployment.
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 <kubeletDir>/flexfs/<volume-name>/creds, where <kubeletDir> is the kubelet root the driver was started with (/var/lib/kubelet unless overridden — see MicroK8s and custom kubelet directories).
   • There is no fixed per-node volume limit: nothing is attached to the node, so the practical ceiling is memory and file descriptors rather than a slot count.

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