Skip to content

sandbox-setup.md

Latest commit

 

History

History
84 lines (65 loc) · 4.28 KB

sandbox-setup.md

File metadata and controls

84 lines (65 loc) · 4.28 KB
Raw

Sandbox setup

This reference covers the AKS setup used by the deployment scripts. The live in-cluster model is a single AgentHost warm pool managed by the upstream agent-sandbox controller.

Components

Component Source Purpose
agent-sandbox controller scripts/azure/steps/10-create-cluster.mjs Installs CRDs in API group extensions.agents.x-k8s.io.
SandboxTemplate/agentweaver-agent-host k8s/base/sandbox-template-agenthost.yaml Defines the Kata-isolated AgentHost pod: image, service account, workspace PVC, config, A2A port 8088.
SandboxWarmPool/agentweaver-agent-host k8s/base/sandbox-warmpool-agenthost.yaml Keeps AgentHost pods pre-warmed for fast run startup.
SandboxClaim created per run by the API/worker Binds one warm AgentHost pod for a run, then releases it on completion/suspend.

Install order

The canonical workflow provisions and deploys the sandbox pieces through the root package scripts (npm run shown; pnpm run is equivalent):

npm run azure:provision-infra      # installs the controller + CRDs, builds/pushes images, applies the template/warm pool, and verifies it

For an existing cluster, npm run azure:deploy-from-local builds/pushes images, redeploys, and cycles the warm pool without re-provisioning the cluster. azure:provision-infra/azure:deploy-from-local apply sandbox-template-agenthost.yaml before sandbox-warmpool-agenthost.yaml; the warm pool depends on the template by name. For targeted recovery, the AKS deployment runbook shows how to run individual steps, including gen-a2a-mtls-certs.

AgentHost pod behavior

  1. Warm pods start without run context and wait in standby.
  2. A run creates a SandboxClaim referencing warm pool agentweaver-agent-host.
  3. The controller binds a warm pod and reports it in status.sandbox.name.
  4. The API/worker calls AgentHost /configure with run/user/token context.
  5. Agent turns run over A2A on port 8088.
  6. Releasing the claim deletes the used pod; the warm pool replenishes it.

Per-run context is not injected through SandboxClaim.spec.env; as of controller v0.5.3 the warm-pool-adoption-bypass behavior tied to spec.env/spec.volumeClaimTemplates has not been confirmed fixed upstream (see the blocker analysis on #481) — static config stays in the template and configmap-agenthost.yaml until that is verified.

Required configuration

Setting Value
Namespace agentweaver by default (NAMESPACE)
AgentHost warm pool ref agentweaver-agent-host
RuntimeClass kata-vm-isolation
AgentHost image ${ACR_LOGIN_SERVER}/agentweaver-agent-host:${AGENTHOST_IMAGE_TAG}
Key Vault URI https://${KEYVAULT_NAME}.vault.azure.net/
Workspace PVC agentweaver-workspace, mounted at /workspace

The AgentHost image is built by npm run azure:deploy-from-local (or azure:provision-infra) from apps/Agentweaver.AgentHost/Dockerfile. It must publish with --runtime linux-x64 --self-contained false so the Copilot native runtime is included.

Verify

kubectl api-resources --api-group=extensions.agents.x-k8s.io
kubectl get runtimeclass kata-vm-isolation
kubectl get sandboxtemplate,sandboxwarmpool -n agentweaver
kubectl get pods -n agentweaver -l app.kubernetes.io/component=agent-host
npm run azure:verify

Expected resources:

sandboxtemplate.extensions.agents.x-k8s.io/agentweaver-agent-host
sandboxwarmpool.extensions.agents.x-k8s.io/agentweaver-agent-host

Troubleshooting

Symptom Check
Warm pods do not appear kubectl describe sandboxwarmpool agentweaver-agent-host -n agentweaver
Pods stay Pending kubectl get runtimeclass, kubectl describe node, and katapool capacity
Image pull failure image tag matches AGENTHOST_IMAGE_TAG and ACR is attached to AKS
/configure or A2A fails NetworkPolicies allow API/worker to AgentHost TCP 8088; run npm run azure:verify
Token delivery fails service account agentweaver-agent-host has workload identity federation to the dedicated agentweaver-agenthost-identity; the run owner's GitHub token is brokered by the API in /configure (gitHubAccessToken) — the sandbox identity has no Key Vault access (issue #471)