Storage Configuration

Fuzzball V4 uses storage provisioners to manage storage. A provisioner combines a built-in storage driver with access policies in a single configuration — there is no need to install separate storage drivers or create storage classes as in V3.

On cloud deployments, Fuzzball creates a default provisioner for the initial organization using the storage backend appropriate to the deployment (EFS on AWS, Azure Files on Azure, Filestore on GCP). Check fuzzball volume provisioner list before creating one manually. See The default provisioner for details.

For detailed reference on provisioner configuration, see the Volume Configuration and Management section. This page covers the basic setup needed to get storage working on a new cluster.

select

Select your deployment type to see storage configuration instructions.

On-Prem

For on-prem deployments, you will likely want to create an NFS provisioner that manages volumes as subdirectories on an NFS export. In addition, you may also want to create hostpath provisioners for shared storage systems mounted on compute nodes.

NFS Storage Configuration

Prerequisite: Create NFS Shares

First, create directories that will be served as NFS shares. On the server node (or the node serving your NFS shares):

# PRIVATE_SUBNET="" # populate this with the proper value for your environment (e.g. 10.0.0.0/20)

# mkdir -pv /srv/fuzzball/storage

# echo "/srv/fuzzball/storage ${PRIVATE_SUBNET}(rw,sync,no_subtree_check,no_root_squash)" \
  >>/etc/exports

# exportfs -a

# exportfs

It is not necessary to mount the NFS share on compute nodes. Fuzzball’s built-in NFS driver handles mounting automatically when volumes are used in workflows.

Create the NFS Provisioner

Create a provisioner definition file:

$ NFS_SERVER_IP="" # fill in the value of your NFS server IP address (e.g. 10.0.0.4)

$ cat >nfs-provisioner.yaml<< EOF
default:
  description: "Default NFS storage"
  driver:
    type: nfs
    target: "${NFS_SERVER_IP}:/srv/fuzzball/storage"
    version: 4
  access: all
  create: all
  ephemeral: all
EOF

Apply the provisioner:

$ fuzzball volume provisioner add default -f nfs-provisioner.yaml

$ fuzzball volume provisioner list
ID                                   | NAME    | STATUS | DETAIL | CLUSTER
80e204ec-ee2f-3485-9282-33f77a9a3318 | default | Ready  |        | local-dev

Many of the CIQ templates in the Workflow Catalog expect a provisioner named default. Keep this name unless you have a specific reason to change it.
A compose deployment is the exception: its default provisioner is scoped to the docker segment and named default-docker accordingly, so templates naming default do not resolve there. Either edit the template to name default-docker, or add a provisioner called default that the deployment’s nodes can serve.

AWS

AWS EFS Storage Configuration

For AWS deployments, Fuzzball’s built-in EFS driver creates and manages volumes as EFS access points. On a fresh AWS deployment, Fuzzball typically bootstraps a default EFS provisioner automatically.

Check for Automatic Provisioner

After deployment, check if a default provisioner was created:

$ fuzzball volume provisioner list

If a default provisioner exists and is in Ready status, storage is configured and you can skip to Next Steps.

A Ready provisioner is not necessarily a usable one. Check that it also carries a create policy:
$ fuzzball volume provisioner info default -o json
If the output has no createPolicy, volume creation is denied for every group, including the cluster owner — policies are default-deny.
Every default provisioner created by the operator is in this state, on all 4.x releases up to and including 4.2.1. Volume creation has been gated on a create policy since 4.0.0. Nothing populated one for the default provisioner until 4.1.3-pre1, and from that release onward the operator still did not pass the cluster’s owner email to the orchestrator, so the seeding had no value to work from.
Upgrading does not repair an existing provisioner: the bootstrap only ever creates one, never updates one, which is also why it cannot overwrite an administrator’s edit. Grant create access once with fuzzball volume provisioner edit, and see Owner email is required.

Manual EFS Provisioner Setup

If no default provisioner exists, create one manually. You can use either BYO mode (provide an existing EFS filesystem ID) or self-provisioned mode (provide subnet IDs and let Fuzzball create the filesystem):

BYO mode — use an existing EFS filesystem:

$ cat >efs-provisioner.yaml<< 'EOF'
default:
  description: "Default EFS storage"
  driver:
    type: efs
    filesystemId: fs-XXXXXXXX
    region: us-east-1
  access: all
  create: all
  ephemeral: all
EOF

Self-provisioned mode — Fuzzball creates the EFS filesystem:

$ cat >efs-provisioner.yaml<< 'EOF'
default:
  description: "Default EFS storage"
  driver:
    type: efs
    region: us-east-1
    subnetIds:
      - subnet-XXXXXXXX
      - subnet-YYYYYYYY
  access: all
  create: all
  ephemeral: all
EOF

Replace placeholder values (fs-XXXXXXXX, us-east-1, subnet IDs) with actual values from your AWS deployment. Provide filesystemId or subnetIds, not both.

Apply the provisioner:

$ fuzzball volume provisioner add default -f efs-provisioner.yaml

$ fuzzball volume provisioner list

GCP

GCP Filestore Storage Configuration

For GCP deployments, Fuzzball uses the Filestore driver to connect to a Cloud Filestore instance. The NFS driver also works against Filestore or any other NFS-compatible storage, but the Filestore driver understands the instance’s endpoint format directly and is the better default.

Check for Automatic Provisioner

After deployment, check if a default provisioner was created:

$ fuzzball volume provisioner list

If a default provisioner exists and is in Ready status, storage is configured.

Manual Filestore Provisioner Setup

If no default provisioner exists, create one pointing to your Filestore endpoint. The target is the instance’s NFS endpoint, given as either host or host:/shareName; omitting the share name uses workflowio:

$ cat >filestore-provisioner.yaml<< 'EOF'
default:
  description: "Default Filestore storage"
  driver:
    type: filestore
    target: "10.171.0.2:/workflowio"
  access: all
  create: all
  ephemeral: all
EOF

Apply the provisioner:

$ fuzzball volume provisioner add default -f filestore-provisioner.yaml

$ fuzzball volume provisioner list

To point at NFS-compatible storage that is not Filestore, use the NFS driver instead and give target in host:/path form.

CoreWeave

Support for CoreWeave within Fuzzball is in preview status and is currently subject to more rapid change than other features. Contact CIQ as part of your deployment planning.

CoreWeave Storage Configuration

For Fuzzball on CoreWeave, use a hostpath provisioner backed by the shared-vast PVC mounted on substrate nodes at /mnt/shared-storage.

$ cat >cw-provisioner.yaml<< 'EOF'
default:
  description: "CoreWeave shared-vast storage"
  driver:
    type: hostpath
    path: /mnt/shared-storage/volumes
  access: all
  create: all
  ephemeral: all
EOF

Apply the provisioner:

$ fuzzball volume provisioner add default -f cw-provisioner.yaml

$ fuzzball volume provisioner list

CoreWeave’s shared-vast storage requires Native Protocol Limit view policy. Ensure this is configured before deployment. For additional CoreWeave storage options, see the CoreWeave Configuration Guide.

OCI

OCI FSS Storage Configuration

For Oracle Cloud Infrastructure (OCI) deployments, Fuzzball’s built-in OCI File Storage Service (FSS) driver creates and manages volumes as exports on OCI FSS. On a fresh OCI deployment, Fuzzball typically bootstraps a default OCI FSS provisioner automatically.

Check for Automatic Provisioner

After deployment, check if a default provisioner was created:

$ fuzzball volume provisioner list

If a default provisioner exists and is in Ready status, storage is configured and you can skip to Next Steps.

Manual FSS Provisioner Setup

If no default provisioner exists, create one manually. You can use either BYO mode (provide an existing FSS file system and mount target) or self-provisioned mode (provide subnet IDs and let Fuzzball create the file system and mount target):

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

$ cat >fss-provisioner.yaml<< 'EOF'
default:
  description: "Default 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
  create: all
  ephemeral: all
EOF

Self-provisioned mode — Fuzzball creates the FSS file system and mount target:

$ cat >fss-provisioner.yaml<< 'EOF'
default:
  description: "Default 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
  create: all
  ephemeral: all
EOF

Replace placeholder values (OCIDs, region, and availability domain) with actual values from your OCI deployment. For BYO mode provide both filesystemId and mountTargetId; for self-provisioned mode omit them and provide subnetIds.

Apply the provisioner:

$ fuzzball volume provisioner add default -f fss-provisioner.yaml

$ fuzzball volume provisioner list

For the full set of OCI FSS fields and the BYO-vs-self-provisioned distinction, see Driver Types.

Verify Storage

After creating a provisioner, verify it is working by scanning for any pre-existing volumes. The scan operation works consistently across all driver types (NFS, hostpath, EFS, OCI FSS):

# fuzzball volume provisioner scan default --dry-run

This shows any existing volumes on the backend without making changes. If volumes are discovered, run the scan without --dry-run to import them:

# fuzzball volume provisioner scan default

For EFS and OCI FSS provisioners, the scan queries the cloud provider API to discover volumes. Ensure that the credentials and permissions configured for the provisioner allow listing EFS access points and OCI FSS exports, respectively.

Default Provisioners per Organization

On a Kubernetes deployment the automatic provisioner described above is created once by default, for the single organization named in the cluster’s configuration. That suits a deployment with one organization, which is the common case. The single-binary deployment and SaaS deployments instead give every organization its own, since both expect organizations to be created after startup.

Where organizations are created on demand — a multi-tenant deployment with self-serve signup, or a federated cluster syncing organizations down — only the first organization would get storage, and every later one would fail its first workflow with “no provisioner matches”. Setting perOrganization gives each organization its own default provisioner as it is created:

defaultStorage:
  provisioners: true
  perOrganization: true
  driverType: filestore
  target: "10.171.0.2:/workflowio"

Each organization’s provisioner is scoped to that organization alone:

On AWS, where the EFS driver can create storage itself, each organization gets its own filesystem. Leave filesystemId unset so the driver self-provisions.
On GCP and for hostpath, where the backing store is shared, each organization gets its own subdirectory via subPath.

Storage failures never block organization creation. If a provisioner cannot be created, the organization is still created and the failure is logged; add a provisioner manually afterwards with fuzzball volume provisioner add.

Mixed-Architecture Considerations

If your cluster includes nodes of different architectures (for example, both amd64 and arm64 compute nodes), be aware that the object cache stores container images with architecture-specific keys. This means:

The same logical container image (e.g., docker://ubuntu:22.04) will occupy separate storage for each architecture present in your cluster.
Cache warming operations should be performed on representative nodes of each architecture to fully pre-populate the cache.
Storage capacity planning should account for the possibility of duplicate image storage across architectures.

For single-architecture clusters, this behavior has no impact. For details on architecture-specific caching, see the Object Cache documentation.

Next Steps

At this point, you have successfully configured storage for your Fuzzball cluster. You can move on to configuring some initial entities.