feat: mount an existing volume per actor at a sub-path

[teemow]

Problem

Actors that work in one shared workspace need part of a volume that exists outside Substrate and outlives them: their own directory read-write, and another directory of the same volume read-only. On this line an external volume is created per actor, attached single-node-writer and deleted with the actor; a VolumeMount has no sub-path and no read-only flag; an Actor carries no volume of its own.

Proposed solution

The shape proposed upstream in agent-substrate#1637 (agent-substrate#1637 (comment)), on top of the access modes of agent-substrate#1988:

• Template: Volume.existing_volume (an empty marker) declares a volume each actor supplies. Mounts of it may set the new VolumeMount.sub_path and read_only. Templates still refuse a mount of an undeclared volume, and sub_path/read_only on any other kind of volume.

• Actor: CreateActor takes Actor.existing_volumes (immutable). Each ExistingVolume has a name, a CSI driver, a volume handle, an access mode (READ_WRITE_MANY or READ_ONLY_MANY, the shape of volume: support configurable access modes agent-substrate/substrate#1988's VolumeAccessMode), and a sub_path: the directory this actor sees as the volume's root. Template mount sub-paths are relative to it, so one template serves every actor, each in a directory of its own (sessions/<id> read-write, mirrors read-only, both from one handle).

• Refused at create, with the reason:

  • a reference to a volume the template does not declare as existing;
  • a driver without a CSIDriverConfig;
  • a handle that no PersistentVolume of the driver holds;
  • an access mode the PersistentVolume does not permit.

  ate-api-server reads PersistentVolumes (a new ClusterRole rule). The PersistentVolume's volumeAttributes reach the driver at resume.

• Unsupplied volumes: an existing volume the actor does not supply contributes neither the volume nor its mounts. The create request of such an actor is unchanged.

• Lifecycle: Substrate never creates, deletes or detaches an existing volume (other actors on the node may be using it). Pause, resume (on another node too) and delete only unmount and mount it.

• CSI: a multi-node volume is published with MULTI_NODE_MULTI_WRITER or MULTI_NODE_READER_ONLY. It is staged once per target, so one actor's unmount never unstages it under another actor on the node.

• Sub-paths on the node: ateom (which sees the volume the CSI node plugin published and may mount; atelet may do neither) binds each sub-path, on both runtimes (internal/volumebind), before the sandbox starts and releases it when the sandbox stops. It binds from a descriptor opened beneath the volume's root with openat2 (RESOLVE_BENEATH | RESOLVE_NO_SYMLINKS | RESOLVE_NO_XDEV), then remounts it read-only where asked. A symbolic link another actor wrote on the volume therefore fails the mount instead of redirecting it, and so does a missing directory: nothing is auto-created. The OCI spec binds the per-mount directory, read-only when asked. On the microvm runtime the bind is made before the volumes directory is shared into the guest, so the guest sees it too.

• Snapshots and tags: an actor with existing volumes boots from its image instead of restoring the template's golden snapshot, which was captured without their mounts. It cannot be created from a tag, since a tag does not record the mounts its guest state was captured with.

• Gate: upstream puts this behind the Preview gate of Add a "preview gate" concept, use it for external volumes agent-substrate/substrate#1994, which this line does not carry, so it is ungated here.

• Commits: FORK.md row with the upstream issue and the exit. The repeated-message equality fix is carried as its own commit with its own row. resources.DeepEqual compared repeated message fields with reflect.DeepEqual, so an immutable repeated field (here existing_volumes) failed every CreateActor with "field is immutable".

Design notes:

• A missing volume fails at create, not at resume. Some drivers confirm any volume ID in ValidateVolumeCapabilities (the NFS CSI driver does), so the check is the cluster's own record: a PersistentVolume of the driver with that handle, permitting the access mode.
• A shared volume is never unstaged or unpublished under a neighbour. A multi-node volume is staged once per target, so one actor's NodeUnstageVolume touches only its own staging. Existing volumes are never ControllerUnpublishVolumed. Neither needs a per-node count of the actors using the volume.
• The sub-path resolves in ateom, which sees the published volume and may mount; atelet may do neither.
• volume: support configurable access modes agent-substrate/substrate#1988 is not carried: only the shape of its VolumeAccessMode enum is mirrored. Its own prerequisites (CSI volume support: follow-up improvements agent-substrate/substrate#1729, csi: add publishContext to actor volumes agent-substrate/substrate#1578) are therefore not needed here.

Replaces #231 (the snapshot-seeded per-actor volume, superseded by this design).

Acceptance criteria

• e2e on kind with an NFS CSI driver: an actor created with a volume reference mounts sub-path sessions/a read-write and mirrors read-only at the declared paths (TestExistingVolumes/MountsSubPathsAtDeclaredPaths)
• Two actors on the same volume each write only their own sub-path; a write to the read-only mount fails (ActorsWriteOnlyTheirOwnSubPath)
• Pausing, resuming and deleting an actor leaves the volume and the other actor's files intact, no PV deleted (PauseResumeDeleteLeaveTheVolume)
• An actor of the same template created without a reference has no such mounts, and its create request is unchanged: unit TestWorkloadSpecExistingVolumes/without_a_reference_the_request_is_unchanged; e2e NoReferenceNoMounts
• A reference to an unknown driver or a missing volume is refused at create with that reason: unit TestValidateExistingVolumes; e2e RefusesBadReferencesAtCreate
• FORK.md row naming the upstream issue it follows; released as a line release candidate

Closes #227.

---

This pull request was written by an agent.

[teemow]

Written by an agent: a parallel implementation of this contract (unpushed, for reference) is the local worktree ~/projects/giantswarm/substrate-wt-227-refs, branch feat/actor-volume-refs at 046ec015.

[teemow]

Replaced by #234: the same tree, with the feature as one commit for this rebase-merged line. Written by an agent.