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.
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.
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.
| Mode | Symbolic | Access |
|---|---|---|
| 0500 | r-x------ | Owner can read and traverse; group and others have no access |
| 0550 | r-xr-x--- | Owner and group can read and traverse; others have no access |
| 0555 | r-xr-xr-x | Owner, group, and others can read and traverse |
| 0700 | rwx------ | Owner has full access; group and others have no access |
| 0750 | rwxr-x--- | Owner has full access; group can read and traverse; others have no access (default) |
| 0755 | rwxr-xr-x | Owner has full access; group and others can read and traverse |
| 0770 | rwxrwx--- | Owner and group have full access; others have no access |
| 0775 | rwxrwxr-x | Owner 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=rxTo 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.
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/7331To 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.