aws-samples / aws-samples/sample-openclaw-multi-tenant-platform

Adopt agent-sandbox CRD for per-tenant kernel-isolated workspaces

Open
#5 3 comments 0 reactions 0 assignees View on GitHub
area/runtime upstream-dependency
Dominant language
Shell
Stars
41
Forks
8
PR merge metrics
No merged PRs in 30d

Description

## Summary
Adopt the [kubernetes-sigs/agent-sandbox](https://agent-sandbox.sigs.k8s.io/) model (as packaged in [awslabs/ai-on-eks](https://awslabs.github.io/ai-on-eks/docs/infra/agents/agent-sandbox)) to give each tenant a declarative, lifecycle-managed, kernel-isolatable workspace. Today tenants are plain `Deployment`s isolated only at the namespace + `NetworkPolicy` level. This migrates the per-tenant workload to the `Sandbox` CRD model and adds a gVisor runtime tier as a follow-up.

## Why
- The `Sandbox` CRD is purpose-built for "a long-running, stateful, singleton container with a stable identity" — exactly the per-tenant persistent workspace model used here.
- Its target architecture includes hibernation + resume-on-incoming-connection (native scale-to-zero for the agent tier). This is **not yet available on the pinned v0.4.5** and lands incrementally — tracked upstream in kubernetes-sigs/agent-sandbox#968 (see Scope below).
- gVisor is delivered as a `SandboxTemplate` `runtimeClassName` field, not a standalone layer — so adopting the Sandbox control plane first is the architecturally correct order.
- Built on AWS-native + OSS SIG primitives.

## Scope (phased)
- [x] **PR #1 — Sandbox control plane + tenant migration (runc):** deploy the agent-sandbox controller + CRDs as an ArgoCD-managed addon; add a per-tenant `runc` `SandboxTemplate`; migrate the per-tenant workload from `Deployment` to `SandboxClaim`; route the Gateway `HTTPRoute` to the controller-owned Service. Runtime stays `runc`. The pinned controller (v0.4.5 / `v1alpha1`) has no connection-triggered resume, so this PR runs **always-on**; scale-to-zero is deferred (see PR #1.5). Design doc `docs/agent-sandbox.md` (included in this PR).
- [ ] **PR #1.5 — scale-to-zero (hibernation + data-path router):** add the `sandbox-router` and idle hibernation once the upstream resume mechanism is available. Gated on upstream Auto Suspend/Resume (kubernetes-sigs/agent-sandbox#968).
- [x] **PR #2 — gVisor runtime tier:** (merged in #9) add a `gvisor` `RuntimeClass`, a gVisor-capable ARM64 Karpenter NodePool (AL2023 + `runsc` shim via user-data), a `gvisor` `SandboxTemplate`, and flip the tenant claim to the gVisor template (a single field).

## Verified design notes
- gVisor supports ARM64, so the all-Graviton (Graviton/`arm64`) cluster needs no x86 migration.
- On v0.4.5 `v1alpha1`, `SandboxClaim.spec.sandboxTemplateRef` links directly to the `SandboxTemplate`; the controller deletes the pod at `Replicas==0` (no native wake), which is why scale-to-zero is split into PR #1.5 and tracked against the upstream auto suspend/resume work.

Contributor guide

Open the contributing guide

Research direction

Start with docs/agent-sandbox.md and the pinned v0.4.5 v1alpha1 SandboxClaim and SandboxTemplate references. Check the completed PR #1 and merged PR #9, then review PR #1.5 and upstream issue #968 before taking work. Done would require the remaining hibernation and resume path to be implemented and verified against the upstream capability.

Written by the indexing model from the issue text.

Assessment

Tech stack
aws, kubernetes, linux
Domain
cloud, devops, infrastructure
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.