Run A Sandbox

This page shows how to leverage Kueue’s scheduling and resource management capabilities when running Sandboxes.

This guide is for batch users that have a basic understanding of Kueue. For more information, see Kueue’s overview.

The Sandbox operator provides isolated environments for running AI agent workloads. Kueue manages the Pods created by the Sandbox controller through the Plain Pod integration, where each Sandbox Pod is represented as a single independent Plain Pod.

Before you begin

1. Learn how to install Kueue with a custom manager configuration.

2. Follow the steps in Run Plain Pods to learn how to enable and configure the pod integration.

3. Check Administer cluster quotas for details on the initial Kueue setup.

4. Install the Sandbox operator.

Sandbox definition

a. Queue selection

The target local queue should be specified in the spec.podTemplate.metadata.labels section of the Sandbox configuration.

spec:
  podTemplate:
    metadata:
      labels:
        kueue.x-k8s.io/queue-name: user-queue

b. Configure the resource needs

The resource needs of the workload can be configured in the spec.podTemplate.spec.containers.

spec:
  podTemplate:
    spec:
      containers:
      - resources:
          requests:
            cpu: "100m"
            memory: "200Mi"

Sample Sandbox

Here is a sample Sandbox:

apiVersion: agents.x-k8s.io/v1alpha1
kind: Sandbox
metadata:
  name: hello-world-kueue
spec:
  podTemplate:
    metadata:
      labels:
        kueue.x-k8s.io/queue-name: user-queue
    spec:
      containers:
      - name: hello
        image: busybox
        command: ["sleep"]
        args: ["6000"]
        resources:
          requests:
            cpu: "100m"
            memory: "200Mi"
      restartPolicy: Never

Limitations

• Kueue will only manage pods created by the Sandbox operator.
• Each Sandbox Pod will create a new Workload resource and must wait for admission by Kueue.