Add ReadWriteMany (RWX) volume support via NFS

[sjmiller609]

Summary

Adds support for ReadWriteMany (RWX) volume mounts backed by NFS, allowing multiple VMs to mount the same volume simultaneously for both reading and writing.

Volume Access Modes

Introduces a three-tier access mode system:

Mode	Multi-attach	Backing	Use case
ReadWriteOnce (default)	Single rw, multiple ro	Local block device	Existing behavior, backwards compatible
ReadOnlyMany	Multiple ro only	Local block device	Shared read-only data
ReadWriteMany	Multiple rw/ro	NFS	Shared writable storage across VMs

NFS Volume Flow

1. Create: POST /volumes with access_mode: "ReadWriteMany" and nfs: {server, export_path, ...} — no local disk image created, just metadata
2. Attach: Multiple instances can attach rw — no block device limits consumed
3. Guest config: Mount mode "nfs" with server details passed to guest init, which mounts via NFS client
4. Networking: NFS volumes require network.enabled=true on the instance

Key Design Decisions

• NFS volumes don't consume local disk — excluded from storage quota tracking
• NFS volumes don't consume block device slots (/dev/vdX) — only metadata + guest config
• Overlay mode is not supported for NFS volumes (NFS is already writable)
• Existing volume behavior is fully backwards compatible (empty access_mode defaults to ReadWriteOnce)

Files Changed

• lib/volumes/types.go — AccessMode enum, NFSConfig struct
• lib/volumes/manager.go — RWX-aware creation, attachment rules, NFS skip in storage tracking
• lib/volumes/storage.go — Persisted NFS metadata fields
• lib/volumes/errors.go — ErrInvalidRequest
• lib/instances/types.go — VolumeNFSConfig, updated VolumeAttachment
• lib/instances/configdisk.go — NFS mount config generation
• lib/instances/create.go — NFS config resolution, validation, device count skip
• lib/instances/admission.go — Skip NFS in overlay reservation
• lib/vmconfig/config.go — NFS fields on VolumeMount
• openapi.yaml — NFSConfig schema, access_mode/nfs on volume endpoints
• lib/oapi/oapi.go — Regenerated
• cmd/api/api/volumes.go — API handler NFS/access_mode support

Example: Create an RWX Volume

POST /volumes
{
  "name": "shared-workspace",
  "size_gb": 100,
  "access_mode": "ReadWriteMany",
  "nfs": {
    "server": "nfs.internal.example.com",
    "export_path": "/exports/workspace",
    "version": "4.1"
  }
}

TODO

• Guest init binary needs NFS mount handler for mode: "nfs" / mode: "nfs_ro"
• Integration test with actual NFS server
• CLI support for creating RWX volumes (if CLI exists)

[github-actions]

✱ Stainless preview builds

This PR will update the hypeman SDKs with the following commit message.

feat: Add ReadWriteMany (RWX) volume support via NFS

Edit this comment to update it. It will appear in the SDK's changelogs.

✅ hypeman-typescript studio · code · diff

Your SDK build had at least one new note diagnostic, which is a regression from the base state.
generate ✅ → build ✅ → lint ✅ → test ✅

npm install https://pkg.stainless.com/s/hypeman-typescript/3e9a538a2c94bdb7c298880503fa16639c65e226/dist.tar.gz

New diagnostics (1 note)

💡 Model/Recommended: `#/components/schemas/NFSConfig` could potentially be defined as a [model](https://www.stainless.com/docs/guides/configure#models) within `#/resources/volumes`.

✅ hypeman-openapi studio · code · diff

Your SDK build had at least one new note diagnostic, which is a regression from the base state.
generate ✅

New diagnostics (1 note)

💡 Model/Recommended: `#/components/schemas/NFSConfig` could potentially be defined as a [model](https://www.stainless.com/docs/guides/configure#models) within `#/resources/volumes`.

✅ hypeman-go studio · code · diff

Your SDK build had at least one new note diagnostic, which is a regression from the base state.
generate ✅ → build ✅ → lint ✅ → test ✅

go get github.com/stainless-sdks/hypeman-go@95c24f4a67553fbc9c2287df71ef6a284d31fd45

New diagnostics (1 note)

💡 Model/Recommended: `#/components/schemas/NFSConfig` could potentially be defined as a [model](https://www.stainless.com/docs/guides/configure#models) within `#/resources/volumes`.

---

This comment is auto-generated by GitHub Actions and is automatically kept up to date as you push.
If you push custom code to the preview branch, re-run this workflow to update the comment.
Last updated: 2026-04-09 17:01:21 UTC