Skip to content

feat: add network storage volume mount support for actors#282

Open
chenggui53 (chenggui53) wants to merge 1 commit into
agent-substrate:mainfrom
chenggui53:feat/network-storage-mount
Open

feat: add network storage volume mount support for actors#282
chenggui53 (chenggui53) wants to merge 1 commit into
agent-substrate:mainfrom
chenggui53:feat/network-storage-mount

Conversation

@chenggui53

Copy link
Copy Markdown

Summary

Add the ability to mount network storage (NFS, PVC, HostPath) into actor sandboxes when starting actors. This enables actors to access shared persistent storage for workspace, model cache, and other use cases.

Closes #232
Related: #220, #172

Changes

CRD Types

  • WorkerPool: Add StorageVolume type and storageVolumes field to declare available storage infrastructure (NFS, PVC, HostPath sources)
  • ActorTemplate: Add ActorVolume type and volumes field to declare mount requirements (name, mountPath, subPath, readOnly)

Proto

  • atelet.proto: Add VolumeMount message and volume_mounts field to WorkloadSpec

Controller

  • WorkerPool controller injects storageVolumes as K8s volumes into worker pods and mounts them at /var/lib/ateom-storage/<name>

API Server

  • workloadSpecFromActorTemplate converts ActorTemplate volumes to proto VolumeMounts
  • CallAteletRestoreStep validates volume refs against WorkerPool storageVolumes

Atelet (OCI)

  • resolveVolumeMounts converts proto mounts to host-path configs
  • buildActorOCISpec creates OCI bind mounts for storage volumes
  • Supports ${ACTOR_ID} placeholder in SubPath for per-actor isolation

Validation

  • ValidateVolumeMountPath ensures mount paths are absolute and safe

Usage

# WorkerPool (infrastructure)
apiVersion: ate.dev/v1alpha1
kind: WorkerPool
metadata:
  name: gpu-pool
spec:
  replicas: 5
  ateomImage: gcr.io/project/ateom:latest
  storageVolumes:
  - name: shared-data
    nfs:
      server: nfs.example.com
      path: /exports/actor-data

# ActorTemplate (workload)
apiVersion: ate.dev/v1alpha1
kind: ActorTemplate
metadata:
  name: code-agent
spec:
  pauseImage: registry.k8s.io/pause:3.10@sha256:...
  containers:
  - name: agent
    image: gcr.io/project/agent@sha256:...
  volumes:
  - name: shared-data
    mountPath: /workspace
    subPath: ${ACTOR_ID}/workspace

Testing

  • ✅ Unit tests for OCI spec generation with volume mounts (7 new tests)
  • ✅ CRD validation verified on kind cluster
  • ✅ WorkerPod volume injection verified
  • ✅ Full test suite passes (go test ./...)

@google-cla

google-cla Bot commented Jun 22, 2026

Copy link
Copy Markdown

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

Add the ability to mount network storage (NFS, PVC, HostPath) into actor
sandboxes when starting actors. This enables actors to access shared
persistent storage.

## Changes

### CRD Types
- WorkerPool: Add StorageVolume type and storageVolumes field to declare
  available storage infrastructure (NFS, PVC, HostPath sources)
- ActorTemplate: Add ActorVolume type and volumes field to declare mount
  requirements (name, mountPath, subPath, readOnly)

### Proto
- atelet.proto: Add VolumeMount message and volume_mounts field to WorkloadSpec

### Controller
- WorkerPool controller injects storageVolumes as K8s volumes into worker pods
  and mounts them at /var/lib/ateom-storage/<name>

### API Server
- workloadSpecFromActorTemplate converts ActorTemplate volumes to proto
- CallAteletRestoreStep validates volume refs against WorkerPool

### Atelet (OCI)
- resolveVolumeMounts converts proto mounts to host-path configs
- buildActorOCISpec creates OCI bind mounts for storage volumes
- createMountPoint creates mount point directories in rootfs
- Supports ${ACTOR_ID} placeholder in SubPath for per-actor isolation

### Validation
- ValidateVolumeMountPath ensures mount paths are absolute and safe

## Usage

WorkerPool (infrastructure):
  storageVolumes:
  - name: shared-data
    nfs: {server: nfs.example.com, path: /exports/data}

ActorTemplate (workload):
  volumes:
  - name: shared-data
    mountPath: /workspace
    subPath: '${ACTOR_ID}/workspace'
@msau42

Copy link
Copy Markdown
Collaborator

/assign

@msau42 Michelle Au (msau42) self-assigned this Jun 22, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Feature] External volume mounts

2 participants