Fuzzball Documentation
Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Back to homepage

Creation

Fuzzball creates ephemeral volumes on demand, when the workflow that declares them starts. From V4 onward, persistent volumes work differently: you must create one explicitly through the CLI, web UI, or API before any workflow can use it.

Your cluster administrator configures storage provisioners that determine the storage backend and access policies for your organization. Your workflow declares one or more storage volumes. A storage volume is a directory on the backend that its provisioner manages, and Fuzzball mounts it into your job containers.

Volume Naming Rules

A volume name must follow these rules:

  • Length: Between 1 and 255 characters
  • No path separators: Cannot contain / or \
  • No path traversal: Cannot be . and cannot contain ..
  • No null bytes: Cannot contain a null byte (\0)

Any other characters — letters in any case, digits, spaces, dots, underscores, hyphens, and other punctuation — are allowed.

Valid examples:

my-dataset
Research_Data-2024
project 1
results.v2

Invalid examples:

my/dataset          # Contains a path separator
data\set            # Contains a path separator
..                  # Path traversal
my..dataset         # Contains path traversal (..)
These rules prevent volume names from escaping the storage boundary. The same rules are enforced by the CLI, web UI, and API.

A volume name that breaks any of these rules is rejected at creation time, whichever interface you use.

Two other errors can reject a workflow at submission. If you reference a persistent volume that does not exist, create it first – fuzzball volume list shows the volumes you can reach, and fuzzball volume create PROVISIONER_NAME VOLUME_NAME creates a new one. If you request an ephemeral volume on a provisioner your group cannot use, ask your cluster administrator to add your group or user to that provisioner’s access list, or choose a different provisioner.

Volume Permissions

A volume’s root directory has Unix-style permissions — a file mode — that control who can read, write, and traverse (enter) it. You choose the mode when you create the volume, and the mode cannot be changed afterward.

In the web UI, the New Volume dialog has a Permissions field listing modes in both octal and symbolic notation, for example 0750 (rwxr-x---). Every interface defaults to 0750: the volume owner has full access, group members can read and traverse, and other users have no access.

ModeSymbolicAccess
0500r-x------Owner can read and traverse; group and others have no access
0550r-xr-x---Owner and group can read and traverse; others have no access
0555r-xr-xr-xOwner, group, and others can read and traverse
0700rwx------Owner has full access; group and others have no access
0750rwxr-x---Owner has full access; group can read and traverse; others have no access (default)
0755rwxr-xr-xOwner has full access; group and others can read and traverse
0770rwxrwx---Owner and group have full access; others have no access
0775rwxrwxr-xOwner and group have full access; others can read and traverse

The web UI offers the eight modes listed above. The CLI accepts any POSIX mode up to 7777, including the setuid, setgid, and sticky bits.

The API field is a plain unsigned integer, not octal text, and the service does not enforce the CLI’s upper bound. Convert the mode before sending it: 0750 is 488, and sending 750 instead records mode 01356 – a sticky, world-writable volume.

The equivalent on the CLI is the --permissions flag, which also accepts symbolic notation:

$ fuzzball volume create nfs my-dataset --size 10GB --permissions 0750
$ fuzzball volume create nfs my-dataset --size 10GB --permissions u=rwx,g=rx

To see the mode on a volume created with an explicit mode, select it in the web UI volume list and read the Permissions row in the detail panel. Volumes created before Fuzzball recorded volume modes have no stored mode, so the detail panel omits the row for them entirely; the storage driver applies its own default when such a volume is mounted. The CLI reports the mode as a decimal number rather than octal, so fuzzball volume info PROVISIONER_NAME VOLUME_NAME prints permissions: 488 for a volume created with 0750.

Group ownership of the volume directory is derived from your account rather than chosen at creation time. Administrators can see Volume permissions for how the storage driver applies ownership and mode.

Volume Holding Node

A persistent volume on a node-local provisioner lives on exactly one node’s disk — its holding node. You can pin the holding node at creation time with the CLI’s --node flag, or let Fuzzball choose one automatically:

$ fuzzball volume create node-local-store dataset --node 10.0.0.3/7331

To see a volume’s recorded holding node, select it in the web UI volume list and read the Holding Node row in the detail panel. The row is omitted for volumes that are not on a node-local provisioner, and for node-local volumes created before Fuzzball recorded holding nodes. fuzzball volume info PROVISIONER_NAME VOLUME_NAME --output json reports the same value as holdingNode; the command’s default curated YAML output omits it, as does the table fuzzball volume list prints by default.