@xemahq/storage-driver-k8s-csi

Kubernetes CSI ReadWriteMany storage driver

Overview

A Kubernetes implementation of the workspace storage-driver contract, for every CSI backend that can issue a ReadWriteMany volume. Each storage pool maps onto one read-write-many persistent volume claim, and per-allocation isolation is a sub-path mount translated by the matched scheduler. The consuming service injects a Kubernetes client so this package stays free of a hard SDK dependency and respects the storage boundary.

One driver instance drives one backend, selected by kind. What differs between backends is a default StorageClass name and a capacity policy, and both are declared per kind rather than implemented per kind:

| kind | Provisioner | Default StorageClass | Capacity | | --- | --- | --- | --- | | longhorn | driver.longhorn.io | longhorn | enforced | | nfs | nfs.csi.k8s.io | nfs-csi | not enforced | | efs | efs.csi.aws.com | efs-sc | not enforced | | filestore | filestore.csi.storage.gke.io | standard-rwx | 1 TiB minimum | | azure_files | file.csi.azure.com | azurefile-csi | enforced |

A capacity that is not enforced is recorded on the claim because the Kubernetes API requires the field, and no quota is applied to it — the backend is elastic, or the volume is a directory on a share that limits nothing. A backend with a minimum refuses a smaller request rather than quietly provisioning something larger than the pool says it is. The policy is stamped on every pool claim as the xema.io/capacity-policy label, and the profile table is exported so callers can read it directly.

When to use it

• Use it for Kubernetes clusters serving shared workspace storage over Longhorn, an NFS CSI export, Amazon EFS, Google Filestore or Azure Files.

Installation

pnpm add @xemahq/storage-driver-k8s-csi

Usage

import { StorageDriverKind } from '@xemahq/kernel-contracts/workspace-storage';
import { createK8sCsiStorageDriver } from '@xemahq/storage-driver-k8s-csi';

const driver = createK8sCsiStorageDriver({
  kind: StorageDriverKind.Longhorn,
  k8s: myK8sClient,
  namespace: 'xema-storage',
});
await driver.ensurePool(poolSpec);

Both the driver-wide storageClass option and a pool's driverConfig.storageClassName override the profile default; the pool wins.

License

Apache-2.0 © Xema — xema.dev