Provisioner Management

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

Adding a provisioner

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.

Listing provisioners

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

Getting provisioner details

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

Editing a provisioner

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

Removing a provisioner

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.

Removing a provisioner with existing 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

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

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

Recovering volumes after removal

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.

Scanning for volumes

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.

Dry-run scan

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)

Import and prune scan

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.

Listing available driver types

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.

Creating a provisioner from an existing one

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

Common workflows

Adding your first provisioner

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
   

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
   

Post-migration from V3

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.