docs(osep): refine volume binding proposal #146
Conversation
Clarify access modes, backend constraints, permissions, and security/config expectations to make the volume proposal more actionable.
Pangjiping
added
documentation
Clarify access modes, backend constraints, permissions, and security/config expectations to make the volume proposal more actionable.
hittyt
force-pushed
the
docs/support-volume
branch
from
c6a4481 to
788d974
Compare
| from opensandbox import SandboxClient | ||
| from opensandbox.models import ImageSpec, ResourceLimits | ||
|
|
||
| client = SandboxClient(api_key="YOUR_API_KEY") |
There was a problem hiding this comment.
There is no SandboxClient class in Python SDK。
Pangjiping
requested review from
Generalwin,
Spground,
fengcone and
kevinlynx
| ## Proposal | ||
|
|
||
| Add two new optional fields to the Lifecycle API: | ||
| - `volumes[]`: defines reusable, runtime-neutral storage resources. |
There was a problem hiding this comment.
Why does the sandbox, even though it only has a single container, still need to define volumes + volumeMounts—a more complex semantics that’s designed for multi-container setups?
There was a problem hiding this comment.
simplified the core model to a single volume concept
|
|
||
| - Full-featured storage orchestration (auto-provisioning, snapshots, backups). | ||
| - Object storage mounting (S3/OSS) in the initial MVP. | ||
| - Cross-sandbox sharing semantics beyond explicit volume bindings. |
There was a problem hiding this comment.
Why doesn’t the volume design support data sharing within the sandbox? If the data source is centralized, then the need for sharing is inherent. Would supporting data sharing in volumes impact the implementation and future iterations?
There was a problem hiding this comment.
Optimized the docs description
| ### Non-Goals | ||
|
|
||
| - Full-featured storage orchestration (auto-provisioning, snapshots, backups). | ||
| - Object storage mounting (S3/OSS) in the initial MVP. |
There was a problem hiding this comment.
In my opinion, we should consider support s3/oss/gitfs firstly, which are popular backend in production.
There was a problem hiding this comment.
Removed this Non-Goal and plan to implement local/oss in the initial MVP
| ```yaml | ||
| volumes: | ||
| - name: workdir | ||
| backendType: local |
There was a problem hiding this comment.
suggestion backendType -> type for simplification
| - name: workdir | ||
| backendType: local | ||
| backendRef: "/data/opensandbox/user-a" | ||
| parameters: |
There was a problem hiding this comment.
- These parameters maybe not enough for lifecycle management of
volume, e.g credential to manage user's cloud resources(oss,s3,etc). - These parameters vary by different backend
type.
There was a problem hiding this comment.
- We are not responsible for volume lifecycle management.
- Yep, parameters vary by different backend type, and this is by design
Clarify access modes, backend constraints, permissions, and security/config expectations to make the volume proposal more actionable.
| ### API enum specifications | ||
| Enumerations are fixed and validated by the API: | ||
| - `accessMode`: use short forms `RW` (read/write) and `RO` (read-only). Examples in this document follow that convention. | ||
| - `backendType`: `local`, `pvc`, `nfs`. `local` refers to host path bind mounts in Docker and hostPath-equivalent mounts in Kubernetes, and must be documented explicitly to avoid ambiguity. |
There was a problem hiding this comment.
PVC is an implementation detail and should be transparent to users.
There was a problem hiding this comment.
I think we should keep PVC as an explicit option—many K8s users already manage PVCs and need to reference them directly.
| volumes: | ||
| - name: workdir | ||
| backendType: local | ||
| backendRef: "/data/opensandbox/user-a" |
There was a problem hiding this comment.
Why we need the backendRef param?
There was a problem hiding this comment.
backendRef is the minimal, explicit pointer to the actual storage resource behind a volume. Without it, the runtime can’t deterministically locate what to mount.
- For type=local, backendRef is the absolute host path to bind mount.
- For type=pvc, it’s the PVC claimName.
- For type=nfs, it’s server:/export/path.
We intentionally keep it required so behavior is predictable and validation is possible; auto‑provisioned or implicit backends would need a separate type or field.
|
|
||
| OpenSandbox users running long-lived agents need artifacts (web pages, images, reports) to persist after a sandbox is terminated or restarted. Today, the API only supports transient filesystem operations via upload/download and provides no mount semantics; as a result, users must move large outputs out-of-band. This proposal adds first-class storage semantics while maintaining runtime portability and security boundaries. | ||
|
|
||
| ### Goals |
There was a problem hiding this comment.
Maybe we should highlight the fact that we want to solve file persist problem. In another words, volume is NOT general storage solution( no block storage, no object storage, etc), so volume should be narrowed in file storage area.
Clarify the MVP scope (Docker local + OSS), align enums/examples/tests, and refine OSS mount behavior and validation details.
4 participants
Summary
Introduce OSEP-0003 to define a runtime-neutral volume and volume binding model, clarifying access modes, backend constraints, permissions/ownership expectations, concurrency notes, and security/configuration details to make the proposal actionable.
Testing
Breaking Changes
Checklist