Kubernetes Agent Sandbox on AWS EKS (Step-by-Step Guide)

What it claims

The tutorial installs the kubernetes-sigs agent-sandbox controller and its Sandbox Router on an EKS cluster with gVisor, then runs two workloads. The first is a Kubernetes troubleshooting agent (frontend, backend, PostgreSQL) where only the backend runs as a sandbox. The second is untrusted Python run through the k8s-agent-sandbox SDK. All manifests are in techiescamp/kubernetes-ai-projects under agent-sandbox/.

How it works

A SandboxTemplate's podTemplate is a copy of a Deployment's template.spec plus runtimeClassName: gvisor. Without that field, the sandbox runs on the default runc runtime. A SandboxWarmpool keeps pre-started pods. A SandboxClaim takes one from the pool, and the pool then starts a replacement. This is why kubectl get po shows three backend pods: one is claimed and two are warm.

The SDK talks to two different endpoints. It uses the local kubeconfig only to create or claim a sandbox through the Kubernetes API. File execution and commands go through the Sandbox Router, because gVisor does not allow direct connections to the sandboxed pod. The agent backend does not need the router: the frontend reaches it through an ordinary Service.

flowchart LR
  SDK[sandbox.py + SDK] -->|kubeconfig: create/claim| API[Kubernetes API]
  API --> Ctrl[agent-sandbox controller]
  Ctrl --> Pool[Warm pool pod]
  SDK -->|ROUTER_AUTH_TOKEN: exec code| Router[sandbox-router-svc :8080]
  Router --> Pool

The CRDs use two API groups. Sandbox is agents.x-k8s.io/v1beta1. Templates and warm pools are extensions.agents.x-k8s.io.

Evidence

The untrusted-code test reports the following:

• Reading /etc/shadow fails with PermissionError (Errno 13).
• setuid(0) fails with Errno 1.
• The ServiceAccount token path does not exist (FileNotFoundError).
• A probe process sees itself as PID 3 inside the sandbox.

The page credits Pod Security for the first three results and gVisor for process isolation from the node. Scheduled deletion terminated a pod at about 4m55s for a 5-minute shutdownTime. A file written to a PVC-backed /workspace was still present after a suspend and resume cycle that replaced the pod.

How to use it

Prerequisites are a gVisor RuntimeClass (handler runsc), the Pod Identity and EBS CSI add-ons, a default StorageClass, jq, and Python 3. Install the controller and router:

VERSION=$(curl -s https://api.github.com/repos/kubernetes-sigs/agent-sandbox/releases/latest | jq -r '.tag_name')
kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/$VERSION/sandbox.yaml
kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/$VERSION/extensions.yaml
kubectl create secret generic sandbox-router-auth \
  --namespace agent-sandbox-system \
  --from-literal=auth-token="$(openssl rand -hex 32)"
kubectl apply -f sandbox-router.yaml

For the agent, run ./scripts/setup-pod-identity.sh create. This creates the Bedrock role and binds it to the ai-agent service account. Then edit the region, model, token cost and Postgres password in kustomization.yaml, and run kubectl apply -k ..

For the SDK, run pip install k8s-agent-sandbox, port-forward svc/sandbox-router-svc 8080:8080, and export ROUTER_AUTH_TOKEN. A wrong token produces Failed to communicate with the sandbox.

Two Sandbox spec fields control lifecycle:

• shutdownPolicy (Retain or Delete) with shutdownTime schedules expiry.
• operatingMode: Suspended or Running hibernates and resumes a sandbox.

Limits

Suspending a sandbox deletes the pod. Any data not on a PersistentVolume mounted at the agent's data path is lost.

The scheduled-deletion manifest uses BSD/macOS date -v+5M. The command shown just before it uses GNU date -d. On Linux, use the GNU form.

The page calls the SDK RBAC a "role and role binding" in one place and a "cluster role and cluster role binding" in another. Check rbac.yaml before applying it.

Cleanup deletes only the agent-sandbox-system and ai-agent namespaces (with --force) and the pod identity. It does not remove the python-sdk resources or the controller's CRDs.

Model choice, Bedrock cost, and the agent's own permissions in 02-rbac.yaml are not discussed. The agent applies fixes to the cluster only after the user approves them.