Provisioner Definitions

A provisioner definition is a YAML file that describes how a storage provisioner operates: which driver to use, how to connect to the storage backend, and which groups have access. Provisioner definitions are applied with fuzzball volume provisioner add.

Definition format

Provisioner definitions use a name-keyed format where the provisioner name is the top-level key:

my-provisioner:
  description: "Shared NFS storage for development"
  driver:
    type: nfs
    target: "nfs-server:/export/data"
  access: all
  ephemeral: all

The provisioner name (my-provisioner above) is set by the top-level key in the YAML file. It is also passed as the first argument to fuzzball volume provisioner add.

Field reference

Top-level fields

Field	Type	Required	Description
`description`	string	No	Human-readable description of the provisioner
`driver`	object	Yes	Storage driver configuration (see below)
`annotations`	map	No	Key-value pairs for provisioner selection matching
`access`	policy	No	Groups allowed to mount existing persistent volumes
`create`	policy	No	Groups allowed to create persistent volumes
`ephemeral`	policy	No	Groups allowed to create and use ephemeral volumes
`costPerGbHour`	float	No	Billing rate for ephemeral volume usage

Driver configuration

The driver section configures the storage backend. All driver types share the type field; remaining fields depend on the driver type.

Field	Type	Drivers	Description
`type`	string	All	Driver type: `nfs`, `hostpath`, or `efs`
`target`	string	NFS	NFS server and export in `host:/path` format
`version`	integer	NFS	NFS protocol version: `3` or `4` (omit for auto-negotiate)
`options`	string	NFS	Additional mount options (e.g., `hard,intr`)
`path`	string	Hostpath	Absolute path to the base directory on the node
`local`	boolean	Hostpath	Set to `true` for node-local volumes (default: `false`)
`filesystemId`	string	EFS	AWS EFS filesystem ID for BYO mode (e.g., `fs-12345678`)
`region`	string	EFS	AWS region (e.g., `us-west-2`)
`subnetIds`	list	EFS	AWS subnet IDs for self-provisioned mode (mount target placement)

For EFS provisioners, provide either filesystemId (BYO mode — use an existing EFS filesystem) or subnetIds (self-provisioned mode — Fuzzball creates the filesystem and mount targets automatically). Do not provide both at creation time.

Access policy format

Each of the three policy fields (access, create, ephemeral) accepts one of two forms:

Grant to all groups:

access: all

Grant to specific groups:

access:
  - engineering
  - datascience
  - research

Policies that are omitted or empty grant no access (default-deny). See Access Policies for details on the three-tier permission model.

Annotations

Annotations are string key-value pairs used for provisioner selection in workflow volume definitions. When a workflow specifies annotations: on a volume, Fuzzball matches those annotations against provisioner annotations to select the right provisioner.

my-provisioner:
  driver:
    type: nfs
    target: "nfs-server:/export/fast"
  annotations:
    tier: fast
    region: us-west
  access: all

See Annotations and Selection for details on how matching works.

Complete examples

NFS provisioner

An NFS provisioner for a multi-node on-prem cluster with per-group access control:

shared-nfs:
  description: "Shared NFS storage for all teams"
  driver:
    type: nfs
    target: "nfs-server.prod.internal:/vol/shared"
    options: "hard,intr"
  access: all
  create:
    - data-engineers
    - mlops
  ephemeral: all
  annotations:
    tier: shared

Hostpath provisioner

A hostpath provisioner for a single-node deployment or a node with a shared clustered filesystem (Lustre, GPFS):

lustre-storage:
  description: "Lustre shared filesystem"
  driver:
    type: hostpath
    path: /mnt/lustre/fuzzball
  access: all
  create:
    - storage-admins
  ephemeral: all

Node-local hostpath provisioner

A hostpath provisioner for node-local NVMe scratch storage. Volumes created with this provisioner exist only on the node where they were created:

local-nvme:
  description: "Local NVMe scratch storage"
  driver:
    type: hostpath
    path: /mnt/nvme0n1
    local: true
  ephemeral:
    - compute-jobs
    - batch-workers

When local: true is set, volumes are only accessible on the node where they were created. Fuzzball’s scheduler ensures jobs using these volumes are placed on the correct node.

AWS EFS provisioner (BYO mode)

A provisioner for an existing AWS EFS filesystem:

aws-efs:
  description: "AWS EFS shared cloud storage"
  driver:
    type: efs
    filesystemId: fs-12345678
    region: us-west-2
  access: all
  create:
    - engineering
  ephemeral: all

AWS EFS provisioner (self-provisioned mode)

A provisioner where Fuzzball creates the EFS filesystem and mount targets:

aws-efs-auto:
  description: "Auto-provisioned AWS EFS"
  driver:
    type: efs
    region: us-west-2
    subnetIds:
      - subnet-abc123
      - subnet-def456
  access: all
  create:
    - engineering
  ephemeral: all

The EFS driver creates AWS EFS access points for each volume. Volume creation and deletion are control-plane operations that do not require a substrate node.

Editing an existing provisioner

To modify an existing provisioner’s definition, use fuzzball volume provisioner edit:

$ fuzzball volume provisioner edit my-provisioner

This opens the current definition in your $EDITOR. Save and close to apply the changes. You can also export the current definition to a file, modify it, and re-apply:

$ fuzzball volume provisioner info my-provisioner -o yaml > provisioner.yaml

$ vi provisioner.yaml

$ fuzzball volume provisioner edit my-provisioner -f provisioner.yaml