Reference on KlustreFS

Settings ConfigMap

Mon, 01 Jan 0001 00:00:00 +0000

ConfigMap/klustre-csi-settings provides runtime configuration to the node daemonset. Each key maps to either an environment variable or a command-line argument.

Key	Description	Default
`csiEndpoint`	UNIX socket path used by the node plugin. Must align with kubelet’s plugin directory.	`unix:///var/lib/kubelet/plugins/lustre.csi.klustrefs.io/csi.sock`
`driverRegistrationArg`	Argument passed to the node-driver-registrar sidecar.	`--kubelet-registration-path=/var/lib/kubelet/plugins/lustre.csi.klustrefs.io/csi.sock`
`logLevel`	Verbosity for the Klustre CSI binary (`info`, `debug`, etc.).	`info`
`nodeImage`	Container image for the Klustre CSI node plugin.	`ghcr.io/klustrefs/klustre-csi-plugin:0.0.1`
`pluginDir`	HostPath where CSI sockets live.	`/var/lib/kubelet/plugins/lustre.csi.klustrefs.io`
`priorityClassName`	Priority class applied to the daemonset pods.	`system-node-critical`
`registrarImage`	Container image for the node-driver-registrar sidecar.	`registry.k8s.io/sig-storage/csi-node-driver-registrar:v2.10.1`
`registrationDir`	HostPath where kubelet expects CSI driver registration files.	`/var/lib/kubelet/plugins_registry`

To update any field:

Storage class parameters

Mon, 01 Jan 0001 00:00:00 +0000

The manifests bundle a StorageClass named klustre-csi-static. It targets pre-provisioned Lustre exports and enforces node placement.

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
 name: klustre-csi-static
allowedTopologies:
- matchLabelExpressions:
 - key: lustre.csi.klustrefs.io/lustre-client
 values:
 - "true"
mountOptions:
- flock
- user_xattr
provisioner: lustre.csi.klustrefs.io
reclaimPolicy: Retain
volumeBindingMode: WaitForFirstConsumer

Field summary

provisioner – Must stay lustre.csi.klustrefs.io so PVCs bind to the Klustre driver.
allowedTopologies – Uses the lustre.csi.klustrefs.io/lustre-client=true label to ensure only Lustre-capable nodes run workloads. Update the label key/value if you customize node labels.
mountOptions – Defaults to flock and user_xattr. Add or remove Lustre options as needed (e.g., nolock, noatime).
reclaimPolicy – Retain keeps the PV around when a PVC is deleted, which is typical for statically provisioned Lustre shares.
volumeBindingMode – WaitForFirstConsumer defers binding until a pod is scheduled, ensuring topology constraints match the consuming workload.

Customization tips

Create additional storage classes for different mount flag sets or topology labels. Ensure each class references the same provisioner.
If you disable topology constraints, remove allowedTopologies, but be aware that pods might schedule onto nodes without Lustre access.
For multi-cluster environments, consider namespacing storage class names (e.g., klustre-csi-static-prod).

Helm values

Mon, 01 Jan 0001 00:00:00 +0000

The chart is published as oci://ghcr.io/klustrefs/charts/klustre-csi-plugin. Run helm show values oci://ghcr.io/klustrefs/charts/klustre-csi-plugin --version 0.1.1 for the full schema. This page summarizes frequently tuned fields.

Path	Default	Purpose
`image.repository`	`ghcr.io/klustrefs/klustre-csi-plugin`	Node plugin image repository.
`image.tag`	`0.1.1`	Node plugin tag.
`imagePullSecrets`	`[]`	Global image pull secrets applied to all pods.
`nodePlugin.pluginDir`	`/var/lib/kubelet/plugins/lustre.csi.klustrefs.io`	Host path for CSI sockets.
`nodePlugin.kubeletRegistrationPath`	`/var/lib/kubelet/plugins/lustre.csi.klustrefs.io/csi.sock`	Path passed to kubelet registrar.
`nodePlugin.logLevel`	`info`	Verbosity for the node binary.
`nodePlugin.resources`	`requests: 50m/50Mi`, `limits: 200m/200Mi`	Container resource settings.
`nodePlugin.registrar.image.repository`	`registry.k8s.io/sig-storage/csi-node-driver-registrar`	Sidecar repository.
`nodePlugin.registrar.image.tag`	`v2.10.1`	Sidecar tag.
`nodePlugin.extraVolumes` / `extraVolumeMounts`	`[]`	Inject custom host paths (e.g., additional libraries).
`storageClass.create`	`true`	Toggle creation of `klustre-csi-static`.
`storageClass.allowedTopologies[0].matchLabelExpressions[0].key`	`lustre.csi.klustrefs.io/lustre-client`	Node label key for placement.
`storageClass.mountOptions`	`["flock","user_xattr"]`	Default Lustre mount flags.
`settingsConfigMap.create`	`true`	Controls whether the chart provisions `klustre-csi-settings`.
`serviceAccount.create`	`true`	Create the node service account automatically.
`rbac.create`	`true`	Provision RBAC resources (ClusterRole/Binding).

Example override file

image:
 tag: 0.1.2
nodePlugin:
 logLevel: debug
 extraVolumeMounts:
 - name: host-etc
 mountPath: /host/etc
 extraVolumes:
 - name: host-etc
 hostPath:
 path: /etc
storageClass:
 mountOptions:
 - flock
 - user_xattr
 - noatime

Install with:

Parameter reference

Mon, 01 Jan 0001 00:00:00 +0000

The node daemonset containers accept a small set of flags and environment variables. Most values are sourced from ConfigMap/klustre-csi-settings. Use this table as a quick lookup when you need to override behavior.

Component / flag	Env var	Purpose	Default source
`klustre-csi --node-id`	`KUBE_NODE_NAME`	Unique identifier sent to the CSI sidecars and kubelet. Normally the Kubernetes node name.	Downward API (`spec.nodeName`).
`klustre-csi --endpoint`	`CSI_ENDPOINT`	Path to the CSI UNIX socket served by the node plugin. Must match kubelet registration path.	`csiEndpoint` in the settings ConfigMap.
`klustre-csi --log-level`	`LOG_LEVEL`	Driver verbosity (`error`, `warn`, `info`, `debug`, `trace`).	`logLevel` in the settings ConfigMap.
`PATH`	`PATH`	Ensures `mount.lustre`, `umount.lustre`, and related tools are found inside the container.	`/host/usr/sbin:/host/sbin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin`.
`LD_LIBRARY_PATH`	`LD_LIBRARY_PATH`	Points to host library directories required by the Lustre client binaries.	`/host/lib:/host/lib64:/host/usr/lib:/host/usr/lib64`.
`node-driver-registrar --csi-address`	n/a	Location of the CSI socket inside the pod.	`/csi/csi.sock`.
`node-driver-registrar --kubelet-registration-path`	n/a (derived from ConfigMap)	Host path where kubelet looks for CSI drivers.	`driverRegistrationArg` from the settings ConfigMap.

How to override

Edit the settings ConfigMap: