Added Shared Volume Support via Volume Mount Options

[yulmwu]

Previously, container volumes within a sandbox were completely isolated and not shared between containers. While this aligned with the project's original philosophy, there are cases where sharing specific paths between containers is desirable.

To address this, the following functionality has been added in this PR (excerpt from the README).

volumes

A Sandbox may define sandbox-local shared ephemeral volumes through spec.volumes.

- name: runtime-state
  ephemeral_storage: 128Mi

• name: The volume name. It must be unique within the sandbox.
• ephemeral_storage: Required size limit for the shared tmpfs volume. Once this limit is exceeded, writes return ENOSPC.

Volumes are local to a single sandbox. They are created when the sandbox starts and automatically removed when the sandbox is deleted. Sharing volumes across different sandboxes is not supported.

volume_mounts

Each container may mount one or more sandbox-local shared volumes through volume_mounts.

- name: runtime-state
  mount_path: /var/www/html
  read_only: false

• name: References one of the entries declared in spec.volumes.
• mount_path: Absolute path inside the container where the shared volume will be mounted.
• read_only: Optional flag that mounts the volume as read-only for that container.

Note

/tmp remains reserved for the container's own ephemeral tmpfs budget and cannot be used as a shared volume mount path.

---

An example manifest is shown below:

apiVersion: sandboxd.o/v1
kind: Sandbox
id: shared-volume-demo
spec:
  egress: false
  ttl_seconds: 3600
  volumes:
    - name: runtime-state
      ephemeral_storage: 128Mi
  containers:
    - name: writer
      image: alpine:3.20
      args:
        - sh
        - -c
        - |
          mkdir -p /srv/runtime
          while true; do
            date -u +"%Y-%m-%dT%H:%M:%SZ" > /srv/runtime/heartbeat.txt
            sleep 5
          done
      volume_mounts:
        - name: runtime-state
          mount_path: /srv/runtime
      resource:
        cpu: 100m
        memory: 128Mi
        ephemeral_storage: 96Mi
    - name: reader
      image: alpine:3.20
      args:
        - sh
        - -c
        - |
          while true; do
            cat /srv/runtime/heartbeat.txt 2>/dev/null || true
            sleep 5
          done
      volume_mounts:
        - name: runtime-state
          mount_path: /srv/runtime
      resource:
        cpu: 100m
        memory: 128Mi
        ephemeral_storage: 96Mi

For more details, please refer to the updated source code and documentation.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[Copilot]

Pull request overview

Adds sandbox-local shared tmpfs volumes that can be mounted by multiple containers within the same sandbox (while still disallowing sharing across sandboxes), spanning orchestrator types/validation, sbxlet runtime mounting/cleanup, and documentation.

Changes:

• Extend sandbox specs/APIs with spec.volumes and containers[].volume_mounts (orch) / volumes and containers[].volumeMounts (sbxlet).
• Validate and forward shared volume definitions/mounts from orchestrator to node agent, and mount tmpfs-backed shared volumes in the runtime.
• Update docs and add examples/tests covering shared volume forwarding and validation.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
sandboxd-orch/types/types.go	Adds Volumes to SandboxSpec and VolumeMounts to container spec types.
sandboxd-orch/service/sandbox_ops.go	Validates shared volumes/mounts and forwards them to sbxlet create requests.
sandboxd-orch/service/sandbox_ops_test.go	Adds tests for forwarding shared volumes and create-time validation failures.
sandboxd-let/sandbox/state.go	Persists incoming Volumes and container VolumeMounts into sandbox state.
sandboxd-let/sandbox/service.go	Ensures sandbox state copies include Volumes and VolumeMounts.
sandboxd-let/sandbox/runtime.go	Implements tmpfs shared volume mounts, container mount wiring, and cleanup on delete.
sandboxd-let/model/validate.go	Adds model-level validation for volume/mount basic constraints.
sandboxd-let/model/validate_test.go	Adds validation tests for shared volumes and mounts.
sandboxd-let/model/types.go	Introduces VolumeSpec/VolumeMount types and wires them into API models.
sandboxd-ctl/cmd/resource_cmds.go	Minor refactor using maps.Copy for log printing bookkeeping.
README.md	Documents volumes / volume_mounts and updates container field list.
examples/shared-volume.yaml	Provides a runnable manifest demonstrating shared volumes between containers.
docs/sandboxd.md	Updates sbxlet API docs with volumes and volumeMounts fields and constraints.
docs/orchestrator.md	Updates orchestrator API docs with spec.volumes and spec.containers[].volume_mounts.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.