V4 Storage Breaking Changes

This page summarizes the storage-related breaking changes between Fuzzball V3 and V4. For step-by-step upgrade instructions, see the V3 to V4 Storage Migration Guide.

Architecture change

V3 used a three-tier model. V4 collapses this to two tiers:

V3 Entity	V4 Equivalent	Notes
Storage Driver	Removed	Driver config is embedded in provisioner
Storage Class	Storage Provisioner	Provisioner includes driver config, access policies, annotations
Storage Volume	Storage Volume	Now linked to a provisioner instead of a storage class


V3:  StorageDriver → StorageClass → StorageVolume  (3 entities)
V4:  StorageProvisioner → StorageVolume            (2 entities)

V4 storage drivers are built into the platform. There is no need to install, update, or manage external container-based drivers.

CLI command changes

Removed commands

V3 Command	V4 Replacement
`fuzzball admin storage driver install`	Not needed — drivers are built-in
`fuzzball admin storage driver uninstall`	Not needed
`fuzzball admin storage driver list`	Not needed
`fuzzball admin storage driver update`	Not needed
`fuzzball admin storage class create`	`fuzzball volume provisioner add`
`fuzzball admin storage class delete`	`fuzzball volume provisioner remove`
`fuzzball admin storage class list`	`fuzzball volume provisioner list`
`fuzzball admin storage class update`	`fuzzball volume provisioner edit`
`fuzzball storage` (user-level)	`fuzzball volume provisioner list`

New commands

Command	Purpose
`fuzzball volume provisioner add`	Create a provisioner from YAML definition
`fuzzball volume provisioner list`	List provisioners
`fuzzball volume provisioner info`	Get provisioner details
`fuzzball volume provisioner edit`	Modify a provisioner
`fuzzball volume provisioner remove`	Delete a provisioner
`fuzzball volume provisioner scan`	Discover volumes on the storage backend
`fuzzball volume provisioner list-drivers`	List available driver types
`fuzzball workflow upgrade`	Convert a V1 workflow to V4 format
`fuzzball workflow validate`	Validate a workflow definition

Volume info output changes

The fuzzball volume info command no longer includes the reference field in its output (JSON or YAML). This legacy V3 field has been removed as of V4.1.

What changed

The reference field is no longer returned in volume info responses
This affects both fuzzball volume info and fuzzball volume list output
The field is omitted from both JSON and YAML output

Migration

If your scripts or tooling previously parsed the reference field, use one of these alternatives:

Use case	Replacement
Volume identification	Use the immutable `id` field (JSON output, or YAML output with `--metadata`)
Volume specification in workflows	Use the three-part `scope/provisioner/name` pattern or just `provisioner/name` for user-scoped volumes
CLI volume operations	Use `provisioner name` arguments (e.g., `fuzzball volume info shared-nfs my-volume`)

Example of the new output format:


# fuzzball volume info shared-nfs project-data
project-data:
  use: shared-nfs
  name: project-data
  size: 50 GiB

Workflow DSL changes

Volume syntax

V3 workflows used the reference: field to specify volumes:


# V3 syntax (deprecated, still accepted via auto-upgrade)
version: v1
volumes:
  data:
    reference: volume://user/persistent
  scratch:
    reference: volume://user/ephemeral

V4 workflows use use:, name:, size:, and annotations::


# V4 syntax (recommended)
version: v4
volumes:
  data:
    use: shared-nfs
    name: my-dataset
  scratch:
    use: shared-nfs
    size: 10GB

Note

V1 workflows are auto-upgraded to V4 at execution time. Fuzzball converts reference: fields to the equivalent use:/name: syntax automatically. You can also convert workflows manually with fuzzball workflow upgrade.

Version field

New workflows should use version: v4. The version: v1 format is still accepted and auto-upgraded at execution time.

Web UI default

The Web UI Workflow Editor defaults to version: v4 when creating new workflows or hydrating workflow templates from the Workflow Catalog without an explicit version specified. This means:

New workflows created via "Create New" in the Workflow Editor start with version: v4
Template workflows hydrated from the Workflow Catalog without a version field default to version: v4

Users who are familiar with v3 syntax and wish to create v1 workflows through the Web UI should explicitly set version: v1 in the YAML editor (press e to open it) before saving or running the workflow.

This change does not affect the CLI or existing workflows — v1 workflows continue to be supported and are auto-upgraded at execution time.

Mount syntax

V4 uses path-keyed mounts (the mount point is the key) instead of volume-keyed mounts:


# V3 mount syntax (auto-upgraded)
jobs:
  myjob:
    mounts:
      data:
        location: /data

# V4 mount syntax
jobs:
  myjob:
    mounts:
      /data:
        volume: data

Permission model changes

V3 used organization-level access for storage — all members of an organization could use all storage classes. V4 introduces group-based access policies on each provisioner:

Policy	Purpose
`access`	Controls which groups can mount existing persistent volumes
`create`	Controls which groups can create new persistent volumes
`ephemeral`	Controls which groups can use ephemeral volumes

See Access Policies for details.

Built-in driver types

V4 includes three built-in storage drivers:

Driver	V3 Equivalent	Backend
NFS	NFS CSI driver container	NFS export with volume subdirectories
Hostpath	HostPath CSI driver container	Local filesystem directories
EFS	EFS CSI driver container	AWS EFS access points

See Driver Types for configuration details.

Automatic migration

When upgrading from V3 to V4, the storage-migrate process runs automatically during the upgrade and:

Creates a V4 provisioner for each V3 storage class (one per org per class)
Links existing volumes to their new provisioner
Backfills volume ownership (UID/GID)

The migration handles database records only. Depending on your V3 storage layout, filesystem paths may need manual adjustment. See the V3 to V4 Storage Migration Guide for complete post-upgrade steps.

Default provisioner bootstrap

On fresh V4 installations, Fuzzball automatically creates a default provisioner:

Deployment Type	Default Driver	Default Path
Single-binary (compose)	Hostpath	`/mnt/fuzzball-sharedfs`
AWS Kubernetes	EFS	Configured EFS filesystem

The default provisioner grants access: all and ephemeral: all to all groups.

Overview