Agent Sandbox

Using Kueue with Agent Sandbox

Overview

This example shows how to use Kueue to control the admission of Agent Sandbox workloads and defines a default ResourceFlavor required by the ClusterQueue.

Kueue is designed for batch workloads that run to completion, while Agent Sandbox workloads are long-running. Instead of managing execution, Kueue acts as an admission controller to decide when sandbox workloads can start.

Use Cases

• Compute quota management: Limit number of active sandbox workloads
• Admission control: Queue workloads until resources are available
• Warm pool access: Control access to limited resources (e.g., GPUs)

Step 1: Create Kueue Queues

apiVersion: kueue.x-k8s.io/v1beta2
kind: ResourceFlavor
metadata:
  name: default
spec: {}
---
apiVersion: kueue.x-k8s.io/v1beta2
kind: ClusterQueue
metadata:
  name: cluster-queue
spec:
  namespaceSelector: {}
  resourceGroups:
  - coveredResources: ["cpu", "memory"]
    flavors:
    - name: default
      resources:
      - name: cpu
        nominalQuota: 1
      - name: memory
        nominalQuota: 1Gi
---
apiVersion: kueue.x-k8s.io/v1beta2
kind: LocalQueue
metadata:
  name: user-queue
  namespace: default
spec:
  clusterQueue: cluster-queue

Step 2: Apply Kueue Resources

Create a file using the above yaml and apply Kueue Resources.

kubectl apply -f kueue-resources.yaml

Step 3: Deploy Agent Sandbox with Kueue

apiVersion: agents.x-k8s.io/v1beta1
kind: Sandbox
metadata:
  name: kueue-sandbox-example
  namespace: default
spec:
  podTemplate:
    metadata:
      labels:
        kueue.x-k8s.io/queue-name: user-queue
    spec:
      restartPolicy: Never
      containers:
      - name: hello
        image: busybox
        command: ["sh", "-c", "echo 'Hello from Kueue sandbox' && sleep 3600"]
        resources:
          requests:
            cpu: "100m"
            memory: "200Mi"

Step 4: Apply Sandbox Kueue

Create a file using the above yaml and apply Sandbox Kueue.

kubectl apply -f sandbox-kueue.yaml

Key Integration

Kueue uses this label to associate sandbox pods with a queue for admission control:

kueue.x-k8s.io/queue-name: user-queue

How it works

1. Sandbox is created
2. Pod is generated by the controller
3. Kueue detects the pod and queues it
4. Pod waits until resources are available
5. Once admitted, the pod starts running

Important Note

Kueue controls when the sandbox starts, not how long it runs.