Driver Types

Fuzzball V4 includes five built-in storage drivers. Each driver handles a different type of storage backend. All drivers are built into the Fuzzball platform — no external container-based drivers need to be installed. The on-premises drivers are NFS and Hostpath; the cloud drivers are AWS EFS, Azure Files, and Oracle Cloud File Storage (FSS).

You can list the drivers available on your cluster, along with their required and optional configuration fields, with:

$ fuzzball volume provisioner list-drivers

The NFS driver manages volumes as subdirectories on an NFS export. It is the primary driver for on-premises multi-node clusters where shared storage is provided by an NFS server.

shared-nfs:
  description: "Shared NFS storage"
  driver:
    type: nfs
    target: "nfs-server.internal:/exports/fuzzball"
    version: 4
    options: "hard,intr"
  access: all
  ephemeral: all

When a volume is created, the driver:

1. Mounts the NFS export to a temporary location
2. Validates available capacity on the export
3. Creates a subdirectory named after the volume
4. Sets POSIX ownership (UID/GID) on the directory
5. Unmounts the temporary mount

When a volume is published (mounted into a workflow container), the driver mounts the specific volume subdirectory to the target path:

NFS Export Root (/exports/fuzzball)
├── my-volume/        ← volume directory, mounted to container path
├── project-data/
└── scratch-wf-123/

NFSv3 and NFSv4 have different mount option syntax and behavior. If you specify mount options in the options field, ensure they are compatible with the NFS version you select.

NFS exports configured with root_squash will remap root (UID 0) operations to the nobody user. This affects volume creation and ownership assignment. If your NFS server uses root_squash, configure the export with no_root_squash for the network range where Fuzzball substrate nodes reside, or use the volume’s UID/GID settings to work within the squash rules.

The hostpath driver manages volumes as directories under a base path on the local filesystem. It supports two modes: shared (default) and node-local.

In shared mode (local: false or omitted), the base path is expected to be available on all nodes in the cluster — typically via a shared filesystem like Lustre, GPFS, or a network mount. Volumes can be accessed from any node.

lustre-storage:
  description: "Lustre shared filesystem"
  driver:
    type: hostpath
    path: /mnt/lustre/fuzzball
  access: all
  ephemeral: all

In node-local mode (local: true), volumes exist only on the node where they were created. Fuzzball’s scheduler ensures that jobs using node-local volumes are placed on the correct node.

local-nvme:
  description: "Local NVMe scratch"
  driver:
    type: hostpath
    path: /mnt/nvme0n1
    local: true
  ephemeral:
    - compute-jobs

Node-local volumes are ideal for ephemeral scratch storage on fast local disks (NVMe, SSD). They are not suitable for persistent data that needs to survive node failures or be accessed from multiple nodes. When local: true is set, Fuzzball’s scheduler constrains job placement to the node where the volume was created — this applies to both ephemeral and persistent volumes using this provisioner.

When a volume is created, the driver:

1. Validates available capacity at the base path
2. Creates a subdirectory named after the volume
3. Sets POSIX ownership (UID/GID) on the directory

When a volume is published, the driver creates a bind mount from the volume directory to the target path:

Base Path (/mnt/fuzzball)
├── volume-a/         ← bind-mounted to container path
├── volume-b/
└── scratch-wf-456/

The EFS driver manages volumes as access points on an Amazon Elastic File System. It is designed for AWS cloud deployments where shared, elastic storage is needed.

Provide filesystemId or subnetIds, not both. Use filesystemId to attach an existing EFS filesystem (BYO mode). Use subnetIds to have Fuzzball create the EFS filesystem and mount targets automatically (self-provisioned mode).

BYO mode — use an existing EFS filesystem:

aws-efs:
  description: "AWS EFS for shared storage"
  driver:
    type: efs
    filesystemId: fs-12345678
    region: us-west-2
  access: all
  ephemeral: all

Self-provisioned mode — Fuzzball creates the EFS infrastructure:

aws-efs-auto:
  description: "Auto-provisioned AWS EFS"
  driver:
    type: efs
    region: us-west-2
    subnetIds:
      - subnet-abc123
      - subnet-def456
  access: all
  ephemeral: all

The EFS driver is unique among Fuzzball’s drivers — it is a control-plane driver, meaning volume creation and deletion happen via AWS API calls from the Fuzzball control plane, not from a substrate node. This provides faster operations and eliminates the need for a running substrate node during volume management.

When a volume is created, the driver:

1. Creates an AWS EFS access point on the filesystem
2. Sets the access point’s root directory to /<volume-name>
3. Configures POSIX identity via the access point’s PosixUser and CreationInfo (UID, GID, and directory permissions)

When a volume is published (mounted into a workflow container), the driver:

1. Mounts the access point via NFS 4.1 to the target path
2. Mount uses the access point’s root directory for isolation

EFS Filesystem (fs-12345678)
├── /volume-a/    ← access point root, mounted to container
├── /volume-b/    ← separate access point
└── /scratch-123/ ← ephemeral access point

Before creating an EFS provisioner, ensure:

• The EFS filesystem exists and is in the available state
• Mount targets are available in the subnets where Fuzzball nodes run
• Security groups allow NFS traffic (TCP port 2049) from the node subnet
• IAM permissions allow elasticfilesystem:CreateAccessPoint, elasticfilesystem:DeleteAccessPoint, and elasticfilesystem:DescribeAccessPoints

EFS storage is elastic — there are no per-access-point capacity quotas. The size field in volume definitions is accepted but not enforced at the EFS level.

The Azure Files driver manages volumes as subdirectories of an Azure Files NFS share. Each volume is a subdirectory in the share, mounted on substrate nodes over NFSv3. It is designed for Azure cloud deployments.

The Azure Storage account must have the NFS protocol enabled on the file share. SMB shares are not supported by this driver.

azure-files:
  description: "Azure Files NFS storage"
  driver:
    type: azure_files
    accountName: fuzzballstorage
    shareName: workflowio
  access: all
  ephemeral: all

The OCI FSS driver manages volumes on an Oracle Cloud File Storage Service file system, with parity to the AWS EFS driver. Volumes mount over NFSv3, and per-volume POSIX ownership is enforced server-side by an OCI FSS IdentitySquash policy. It supports both bring-your-own (BYO) mode and self-provisioned mode.

For BYO mode, provide both filesystemId and mountTargetId. For self-provisioned mode, omit them and provide subnetIds; the driver creates the file system and mount target from the compartment, availability domain, and subnets.

BYO mode — use an existing FSS file system and mount target:

oci-fss:
  description: "OCI File Storage"
  driver:
    type: oci_fss
    region: us-ashburn-1
    compartmentId: ocid1.compartment.oc1..aaaaaaaa
    availabilityDomain: "Uocm:US-ASHBURN-AD-1"
    filesystemId: ocid1.filesystem.oc1.iad.aaaaaaaa
    mountTargetId: ocid1.mounttarget.oc1.iad.aaaaaaaa
  access: all
  ephemeral: all

Self-provisioned mode — Fuzzball creates the FSS infrastructure:

oci-fss-auto:
  description: "Auto-provisioned OCI File Storage"
  driver:
    type: oci_fss
    region: us-ashburn-1
    compartmentId: ocid1.compartment.oc1..aaaaaaaa
    availabilityDomain: "Uocm:US-ASHBURN-AD-1"
    subnetIds:
      - ocid1.subnet.oc1.iad.aaaaaaaa
  access: all
  ephemeral: all

The AWS EFS and Azure Files drivers accept an optional nfsSyncMode field that controls whether NFS volumes are mounted with synchronous or asynchronous writes:

For most clusters the auto default is correct. Override it only when you have a specific durability or performance requirement.

Use this guide to select the right driver for your deployment: