Alauda Build of Agent Sandbox Docs

Architecture and Resource Model

Alauda Build of Agent Sandbox separates workload lifecycle orchestration from runtime isolation. The controller reconciles Kubernetes resources, while the selected container runtime provides the process or virtual-machine isolation boundary.

TOC

Control PlaneCore Sandbox ResourceOptional Extension ResourcesWorkload and Runtime BoundaryRequest Flow

Control Plane

ACP installs Agent Sandbox as a Cluster Plugin. The installation creates the agent-sandbox-system namespace and runs agent-sandbox-controller in the target workload cluster.

The controller watches Agent Sandbox custom resources and manages their secondary resources. Platform-level settings such as controller replicas, controller Pod resources, and controller scheduling are configured through the Cluster Plugin. Workload-specific resources and scheduling remain in each Sandbox or SandboxTemplate.

Core Sandbox Resource

The core API is:

apiVersion: agents.x-k8s.io/v1beta1
kind: Sandbox

A Sandbox describes one stateful, singleton workload. Its podTemplate defines the container image, commands, storage, security context, networking metadata, scheduling constraints, and optional runtimeClassName.

The controller maintains a Pod with the same stable identity as the Sandbox and reports lifecycle state through status conditions. Applications must inspect each condition's boolean status; condition presence alone is not a state transition.

Optional Extension Resources

The optional extension API group is extensions.agents.x-k8s.io/v1beta1 and contains:

ResourcePurpose
SandboxTemplateDefines a reusable Sandbox workload template.
SandboxWarmPoolMaintains prepared workloads to reduce claim latency.
SandboxClaimRequests a Sandbox from the extension workflow.

The extension CRDs can exist even when their reconcilers are disabled. Before creating these resources, verify that the controller arguments include --extensions=true. The Cluster Plugin setting controller.extensions defaults to false.

Workload and Runtime Boundary

Agent Sandbox is responsible for:

  • Declaring and reconciling the Sandbox lifecycle.
  • Maintaining a stable workload identity.
  • Reporting Ready, Suspended, and error conditions.
  • Managing optional templates, claims, and warm pools.
  • Applying the Pod template selected by the user.

The container runtime is responsible for the low-level isolation boundary. Set spec.podTemplate.spec.runtimeClassName to a RuntimeClass already installed and configured by the cluster administrator. Agent Sandbox does not install Kata Containers, gVisor, or another runtime.

Request Flow

A typical request follows this sequence:

  1. A platform administrator installs and configures the Cluster Plugin.
  2. A user or agent service creates a Sandbox in a business namespace.
  3. The controller validates the requested lifecycle state and creates or updates the managed Pod.
  4. Kubernetes schedules the Pod and selects the configured RuntimeClass.
  5. The controller publishes status conditions on the Sandbox.
  6. The client waits for Ready=True before connecting to or executing commands in the workload.
  7. The client suspends, resumes, deletes, or allows the scheduled shutdown policy to process the Sandbox.

For extension workflows, a SandboxClaim selects a prepared workload from a SandboxWarmPool based on a SandboxTemplate. The resulting workload still uses the same core Sandbox and Pod/runtime boundaries.