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.

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

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.

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.

• 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

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

Example of the new output format:

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

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.

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

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.

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

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:

See Access Policies for details.

Newly created volumes default to 0750 (rwxr-x---) when no explicit permissions are specified. This applies to both persistent volumes and workflow-created ephemeral volumes. Previously, the default was 0755 (rwxr-xr-x), which allowed any user on the host to read and traverse the volume directory. Existing volumes are unaffected — only volumes created after the upgrade receive the new default.

V4 includes three built-in storage drivers:

See Driver Types for configuration details.

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.

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

The default provisioner grants access: all and ephemeral: all to all groups. Its create policy is narrower: it names the cluster owner’s group and user, because create implies delete on that provisioner and all would let any group remove another’s volumes. The policy is seeded from the owner email configured at deploy time, so a provisioner created without one has no create policy at all and denies everyone — see Storage Configuration.