Provisioner Management

Storage provisioners are managed with the fuzzball volume provisioner command. Organization owners can manage provisioners for their organization.

Create a provisioner from a YAML definition file:

$ fuzzball volume provisioner add my-provisioner -f provisioner.yaml

If you omit -f, your $EDITOR opens with a template that you can fill in and save:

$ fuzzball volume provisioner add my-provisioner

You can override the editor for a single invocation:

$ EDITOR=nvim fuzzball volume provisioner add my-provisioner

You can also scan the storage backend after creation to import existing volumes. This is a two-step process — first add the provisioner, then scan:

$ fuzzball volume provisioner add my-provisioner -f provisioner.yaml

$ fuzzball volume provisioner scan my-provisioner

The --scan flag on provisioner add combines both steps into one command:

$ fuzzball volume provisioner add my-provisioner -f provisioner.yaml --scan

See Provisioner Definitions for the YAML format reference.

List all provisioners in the current organization:

$ fuzzball volume provisioner list

ID                                   | NAME              | STATUS | CREATED TIME          | LAST UPDATED          | CLUSTER
80e204ec-ee2f-3485-9282-33f77a9a3318 | my-nfs            | Ready  | 2026-05-20 10:15:00AM | 2026-05-20 10:15:00AM | my-cluster
a1b2c3d4-e5f6-7890-abcd-ef1234567890 | local-scratch     | Ready  | 2026-05-20 10:16:00AM | 2026-05-20 10:16:00AM | my-cluster

Add -o json or -o yaml for machine-readable output:

$ fuzzball volume provisioner list -o json

View the full definition, status, and driver information of a provisioner:

$ fuzzball volume provisioner info my-nfs

The default output is YAML. Use -o json for JSON output:

$ fuzzball volume provisioner info my-nfs -o json

Modify an existing provisioner’s definition. This opens the current definition in your $EDITOR:

$ fuzzball volume provisioner edit my-nfs

You can also apply changes from a file:

$ fuzzball volume provisioner edit my-nfs -f updated-definition.yaml

Changing a provisioner’s driver type or target may make existing volumes inaccessible. Verify volume compatibility before modifying driver settings on a provisioner with active volumes.

Delete a provisioner from the organization:

$ fuzzball volume provisioner remove my-old-provisioner

By default, the provisioner must have no associated volumes. If volumes still exist, the command returns an error with a hint to use --ignore-volumes.

Use --ignore-volumes to remove a provisioner that still has associated volumes. All volume records are soft-deleted, but physical data on the backing store is not touched:

$ fuzzball volume provisioner remove my-old-provisioner --ignore-volumes

--ignore-volumes requires organization owner privileges. It will be rejected if any volumes are currently in use by running workflows.

To skip the confirmation prompt (for example, in scripts), combine with -y:

$ fuzzball volume provisioner remove my-old-provisioner --ignore-volumes -y

Removing a provisioner — with or without --ignore-volumes — does not delete data on the storage backend. To re-associate the data with Fuzzball:

1. Create a new provisioner pointing to the same backend location:

   $ fuzzball volume provisioner add replacement-provisioner -f provisioner.yaml

2. Scan the backend to re-discover and import the volumes:

   $ fuzzball volume provisioner scan replacement-provisioner

Re-imported volumes appear as externally managed volumes. Subsequent deletes of these volumes will remove the Fuzzball record but will not send delete operations to the storage backend.

The scan command performs a two-way reconciliation between the storage backend and the Fuzzball database. It:

1. Discovers volumes that exist on the storage backend but are not yet tracked in Fuzzball.
2. Identifies stale volumes — volumes tracked in Fuzzball whose backing data was not found during the backend scan.

This is useful after migration from V3, manual volume creation on the backend, or after removing and re-creating a provisioner.

Preview what changes the scan would make without applying them:

$ fuzzball volume provisioner scan my-nfs --dry-run

Example output:

Discovered 3 volume(s):
  - project-data
  - shared-models
  - team-archive

Would remove 1 stale volume(s):
  old-dataset          (id: 80e204ec-ee2f-3485-9282-33f77a9a3318)

Always run --dry-run first. The scan identifies stale volumes by comparing the backend directory listing against the database. Symlinked directories are followed, but if a volume’s backing data is not visible to the scan (for example, behind a misconfigured provisioner path), it will appear as stale.

Discover, import, and prune in a single operation:

$ fuzzball volume provisioner scan my-nfs

This applies both sides of the reconciliation:

• New volumes on the backend are imported and become available for use in workflows immediately. Volumes already tracked by Fuzzball are skipped.
• Stale volumes — those tracked in Fuzzball but not found on the backend — have their Fuzzball records removed. Fuzzball does not delete any data on the storage backend; the record is removed because the backing data was not found during the scan.

Example output:

Discovered 3 volume(s):
  - project-data
  - shared-models
  - team-archive

Imported 2 new volume(s):
  project-data         imported (id: a1b2c3d4-e5f6-7890-abcd-ef1234567890)
  shared-models        imported (id: b2c3d4e5-f6a7-8901-bcde-f12345678901)

Removed 1 stale volume(s) (backing data was already gone):
  old-dataset          (id: 80e204ec-ee2f-3485-9282-33f77a9a3318)

In this example, team-archive was already tracked by Fuzzball and is silently skipped — it appears in the discovered list but not in the imported or removed output.

The scan operation connects to the storage backend (NFS mount, local filesystem, AWS API) to list volumes. Scan failures usually indicate network or connectivity issues, not Fuzzball problems.

View the driver types that Fuzzball supports and their configuration fields:

$ fuzzball volume provisioner list-drivers

This returns a description of each driver type along with its required and optional configuration fields. Use -o json or -o yaml for structured output.

You can export an existing provisioner’s definition and use it as a starting point for a new one. This is useful for creating a copy of the default provisioner and adjusting its access policies:

$ fuzzball volume provisioner info default -o yaml > new-provisioner.yaml

Edit the file to change the name and policies:

$ vi new-provisioner.yaml

Then create the new provisioner from the modified definition:

$ fuzzball volume provisioner add team-storage -f new-provisioner.yaml

After a fresh Fuzzball installation:

1. Verify your context is active:

   $ fuzzball context list

2. Check if a default provisioner was created automatically:

   $ fuzzball volume provisioner list

   On fresh installations, Fuzzball may automatically create a default provisioner based on your deployment configuration. Check fuzzball volume provisioner list before creating one manually.

3. If no provisioner exists, create one from a definition file:

   $ fuzzball volume provisioner add my-storage -f provisioner.yaml

4. Verify the provisioner is ready:

   $ fuzzball volume provisioner list

5. If you have existing data on the backend, scan and import:

   $ fuzzball volume provisioner scan my-storage

For guidance on migrating from V3 storage classes to V4 provisioners, see the V3 to V4 Storage Migration Guide and the V4 Breaking Changes page.