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

Self-provisioned cloud provisioners create their backing infrastructure asynchronously. When a cloud driver definition (AWS EFS, Oracle Cloud FSS, Oracle Cloud Managed Lustre) omits its backing-resource IDs, provisioner add returns immediately with the provisioner in Provisioning status while the filesystem is created in the background. The provisioner is not usable until it transitions to Ready — check progress with fuzzball volume provisioner info <name>. Creation time varies by backend (OCI Managed Lustre takes ~10–15 minutes; EFS and FSS are faster). A failed creation transitions the provisioner to Error. Bring-your-own definitions (all resource IDs supplied) are validated synchronously and come up Ready within the add call.

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. You are prompted for confirmation unless you pass -y/--yes:

$ 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 is rejected if any of the provisioner’s volumes are currently in use by running workflows. Stop those workflows before removing the provisioner.

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, and imports them.
2. Identifies stale volumes — volumes tracked in Fuzzball whose backing data was not found during the scan — and removes their Fuzzball records.

This is useful after:

• Migration from V3
• Manual volume creation on the backend
• Removing and re-creating a provisioner
• Out-of-band deletion of storage (e.g., manual removal of NFS directories)

Scan is not supported for local provisioners. Local provisioners use node-local storage that cannot be discovered from the control plane, so scanning one returns an error.

By default, scan applies changes: it imports newly discovered volumes and removes stale volumes from the Fuzzball database.

$ fuzzball volume provisioner scan my-nfs
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, so it appears in the discovered list but not in the imported output. Imported volumes become available for use in workflows immediately. Stale volumes are soft-deleted from the Fuzzball database; their backing data is already gone, so no storage is touched.

Pass --dry-run to preview what scan would do without applying any changes. No volumes are imported and no stale records are removed:

$ fuzzball volume provisioner scan my-nfs --dry-run
Discovered 3 volume(s):
  - project-data
  - shared-models
  - team-archive

Would remove 2 stale volume(s):
  old-dataset          (id: a1b2c3d4-e5f6-7890-abcd-ef1234567890)
  temp-scratch         (id: f1e2d3c4-b5a6-0987-fedc-ba9876543210)

Without --dry-run, scan removes stale volume records immediately. Because a stale volume’s backing data is already gone, no storage is deleted — but the Fuzzball record is. Run a dry-run scan first to confirm the expected set of removals, especially if the backend may be only temporarily unreachable.

A volume becomes stale when:

• The backing storage (e.g., an NFS directory) was deleted manually outside of Fuzzball
• The storage backend was reconfigured or reformatted
• A provisioner was pointed to a different storage target
• Cloud resources were deleted via the cloud provider’s console or API

Stale volumes remain in the Fuzzball database but cannot be used in workflows because their data no longer exists. Running scan detects this condition — any volume tracked in Fuzzball but not found on the backend during the scan — and removes the orphaned database record. Fuzzball does not delete any data on the storage backend.

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. If scan cannot reach the backend, stale-volume detection cannot run.

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.