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

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

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.

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.