containers.api.v1.VolumeService
VolumeService manages platform-provisioned volumes: sparse ext4 disk images on node disk, attached by the platform's own CSI driver and mounted into a primitive via WorkspaceMount.volume (common.proto). How this differs from WorkspaceService, which is the question everyone asks: WorkspaceService is a CONTENT store. It knows files, dedupes blobs across every workspace, forks a snapshot for free because a fork is a metadata copy, and works identically whether or not anything is running. What it is bad at is being a filesystem: it has to be copied into the pod, one RPC per file, so start cost scales with file count and the big directories have to be excluded to keep it bearable. VolumeService is STORAGE. It knows bytes, not files. Nothing is copied at start, nothing is synced back, there is no ignore set, and size is a hard cap the filesystem enforces. What it is bad at is being content: a volume cannot be forked or diffed, it is opaque to anything that has not mounted it, and reaching it needs the node holding it to be up. They are complementary rather than competing. Content arrives via seed_snapshot_id and leaves via Archive; in between it is a filesystem. File operations are below. They route to the node holding the volume, which is the only thing that can open the image, and work whether or not a workload is running on it.
postArchive Volume
Copies a persistent volume's current contents into the workspace store as a snapshot and returns its id. Only persistent volumes can be archived. `label` defaults to "archive of <volume_id>". Returns Unimplemented when no workspace store is configured. Returns FailedPrecondition if the volume has never been mounted (its node is not known yet) or its node is unreachable, and Unimplemented when the volume file API is not configured. **Access:** any role in the volume's namespace, or a platform admin.
postCreate Volume
Creates a volume record in PENDING state; the image and its node are chosen when the first workload mounting it is scheduled. `tier` is required. `size_mb` must be 64 MiB-512 GiB. A cache volume requires a `cache_key` (AlreadyExists if the key is taken in the namespace) and cannot be seeded; a scratch volume takes neither a cache key nor a seed; `seed_snapshot_id` is for persistent volumes. Workload-scoped agent keys are refused. **Access:** operator or admin role in the namespace (via Xeonr team role or a namespace API key), or a platform admin.
postDelete Volume
Releases the volume's claim and deletes its record. A mounted volume is refused with FailedPrecondition unless `force` is set. Workload-scoped agent keys are refused. **Access:** operator or admin role in the volume's namespace, or a platform admin.
postGet Volume
Returns a volume by `volume_id`, or by `namespace` + `cache_key` for a cache volume; InvalidArgument if neither is given. Access is checked against the volume's own namespace. **Access:** any role in the volume's namespace, or a platform admin.
postList Volume Files
Lists a directory on the volume. Returns FailedPrecondition if the volume has never been mounted (its node is not known yet) or its node is unreachable, and Unimplemented when the volume file API is not configured. **Access:** any role in the volume's namespace, or a platform admin.
postList Volumes
Lists a namespace's volumes, optionally filtered by `tier`. Workload-scoped agent keys are refused. **Access:** any role in the namespace (viewer, operator or admin — via Xeonr team membership or a namespace API key), or a platform admin.
postMake Volume Directory
Creates a directory, and its missing parents when `parents` is set. Returns FailedPrecondition if the volume has never been mounted (its node is not known yet) or its node is unreachable, and Unimplemented when the volume file API is not configured. **Access:** operator or admin role in the volume's namespace, or a platform admin.
postMove Volume File
Moves or renames a path within the volume. Returns FailedPrecondition if the volume has never been mounted (its node is not known yet) or its node is unreachable, and Unimplemented when the volume file API is not configured. **Access:** operator or admin role in the volume's namespace, or a platform admin.
postRead Volume File
Streams a file's bytes in 64 KiB frames from `offset`; `length` 0 reads to the end. The last frame has `eof` set. Returns FailedPrecondition if the volume has never been mounted (its node is not known yet) or its node is unreachable, and Unimplemented when the volume file API is not configured. **Access:** any role in the volume's namespace, or a platform admin.
postRemove Volume File
Removes a file or empty directory, or a whole tree when `recursive` is set. Returns FailedPrecondition if the volume has never been mounted (its node is not known yet) or its node is unreachable, and Unimplemented when the volume file API is not configured. **Access:** operator or admin role in the volume's namespace, or a platform admin.
postResize Volume
Grows a volume. `size_mb` must be larger than the current size (volumes cannot shrink) and at most 512 GiB. Workload-scoped agent keys are refused. **Access:** operator or admin role in the volume's namespace, or a platform admin.
postRestore Volume
Replaces a volume's contents from a snapshot in the same namespace, defaulting to the volume's most recent archive. Refused (FailedPrecondition) while the volume is mounted or when it has never been archived and no `snapshot_id` is given. Returns FailedPrecondition if the volume has never been mounted (its node is not known yet) or its node is unreachable, and Unimplemented when the volume file API is not configured. **Access:** operator or admin role in the volume's namespace, or a platform admin.
postSet Volume File Attributes
Sets a path's mode and/or mtime; a zero value leaves that attribute unchanged. Returns FailedPrecondition if the volume has never been mounted (its node is not known yet) or its node is unreachable, and Unimplemented when the volume file API is not configured. **Access:** operator or admin role in the volume's namespace, or a platform admin.
postStat Volume File
Returns metadata for one path on the volume. `sha256` is never populated. Returns FailedPrecondition if the volume has never been mounted (its node is not known yet) or its node is unreachable, and Unimplemented when the volume file API is not configured. **Access:** any role in the volume's namespace, or a platform admin.
postWrite Volume File
Writes a file atomically. The first stream message must be the header (volume, path, mode — 0 means 0644); the rest are data frames. The body is capped at 64 MiB (InvalidArgument beyond it). A full volume returns ResourceExhausted. Returns FailedPrecondition if the volume has never been mounted (its node is not known yet) or its node is unreachable, and Unimplemented when the volume file API is not configured. **Access:** operator or admin role in the volume's namespace, or a platform admin.
Set Team Default Cluster POST
Sets, or with an empty `cluster_id` clears, the cluster a namespace created for this team is placed on when the request names none. The team must be able to place on the cluster (it owns it, holds a grant, or the cluster is GLOBAL); otherwise PermissionDenied. With it cleared, the platform's default cluster applies. **Access:** an admin of the team, or a platform admin.
Archive Volume POST
Copies a persistent volume's current contents into the workspace store as a snapshot and returns its id. Only persistent volumes can be archived. `label` defaults to "archive of <volume_id>". Returns Unimplemented when no workspace store is configured. Returns FailedPrecondition if the volume has never been mounted (its node is not known yet) or its node is unreachable, and Unimplemented when the volume file API is not configured. **Access:** any role in the volume's namespace, or a platform admin.