Sandbox API — Developer Reference
AgnosticD / AgnosticV integration guide for Red Hat Demo Platform (RHDP)
What is Sandbox API?
Sandbox API allocates OpenShift clusters to lab orders and hands control to AgnosticD (via AgnosticV) to deploy lab content. For every order it:
- Picks an available OpenShift cluster from the resource pool
- Creates a service account with cluster-admin privileges for AgnosticD
- Injects well-known variables into your AgnosticD run (API URL, ingress domain, console URL, SA token)
- Optionally creates namespaces and OCP user accounts (OCP Sandbox API pattern only)
- Reclaims the cluster when the order is destroyed or expired
common.yaml configures what runs, in what order, and with what variables. Everything else — Ansible roles, GitOps, or both — is up to your workloads.
How Cluster Selection Works — cloud_selector
The cloud_selector in your __meta__.sandboxes entry filters the cluster pool. Every cluster has annotation tags; Sandbox API picks a cluster whose annotations contain every tag you specify, weighted by availability.
Example cloud_selector
__meta__:
sandboxes:
- kind: OcpSandbox
namespace_suffix: user
cloud_selector:
cloud: cnv-dedicated-shared # cluster type — must match
demo: mcp-with-openshift # lab-specific tag — key and value set by admin at cluster registration
# key name varies: could be "demo", "lab", or anything — ask admin
purpose: prod # prod vs dev pool
keycloak: "yes" # optional — only clusters with RHSSO installed
The cluster must have ALL four tags to qualify. A cluster missing keycloak: yes will NOT be selected even if it has the other three.
Variables injected after cluster selection
Once a cluster is selected, Sandbox API injects these variables automatically. You do not declare them — you just use them:
| Variable | What it contains | Example value |
|---|---|---|
sandbox_openshift_api_url |
Cluster API server URL — use this to connect to the cluster | https://api.cluster-xyz.example.com:6443 |
sandbox_openshift_ingress_domain |
Wildcard apps domain — use this to build Route hostnames and all service URLs | apps.cluster-xyz.example.com |
sandbox_openshift_console_url |
Web console URL — pass to Showroom for the console tab | https://console-openshift-console.apps.cluster-xyz... |
cluster_admin_agnosticd_sa_token |
Cluster-admin SA token — used by all roles to authenticate to the cluster. Never log or commit this value. | eyJ... (JWT) |
sandbox_openshift_namespace |
Primary namespace created by Sandbox API (from namespace_suffix). Format: sandbox-{guid}-{suffix} |
sandbox-abc12-user |
sandbox_username / sandbox_password |
RHSSO user credentials — only provided when keycloak: "yes" is in cloud_selector |
sandbox-abc12 / generated |
sandbox_openshift_ingress_domain is the most used variable
Almost every service URL in your lab is built from this: https://myapp-{namespace}.{{ sandbox_openshift_ingress_domain }}. This variable is always available — you never need to look it up manually.
Why Sandbox API — Shared Clusters
The primary driver is Zero Touch OpenShift — instant, isolated OpenShift for workshops without waiting for cluster provisioning.
- Speed. A dedicated CNV cluster takes 45–60 minutes to provision. A shared cluster order takes 2–3 minutes — the cluster is already running, we only provision per-tenant resources. For booth demos and Lightning Labs, waiting an hour is not an option.
- Lightning Labs at Summit 2026. Short, self-paced sessions attendees can walk up and start on their own. The environment must be ready in minutes. A shared cluster + Sandbox API makes them viable at scale, concurrently, across the event floor.
-
Reusable pattern. The tenant roles (
ocp4_workload_tenant_keycloak_user,ocp4_workload_tenant_namespace,ocp4_workload_tenant_gitea) are generic — not tied to MCP. Any lab on a shared OpenShift cluster can use the same building blocks. - Authentication. On a shared cluster, HTPasswd with sequential usernames breaks down. RHBK is already on the cluster; each order adds one user to the existing realm and removes it on destroy.
See the full GitOps architecture guide →
Which Pattern Should I Use?
Choose based on who should own namespace and user lifecycle.
Scheduler-Only Summit 2026
Use when
- Multiple tenants share one cluster
- A cluster provisioner pre-installs shared services (Keycloak, Gitea, ArgoCD) once
- Your Ansible roles create namespaces and users per-order
- You need GitOps (ArgoCD) managing tenant workloads
- You need LiteMaaS AI API keys per tenant
- Complex multi-namespace topologies per tenant
Sandbox API does: Schedule cluster, provide token + domain
Your roles do: Create users, namespaces, repos, ArgoCD apps, everything else
OCP Sandbox API
Use when
- Each order gets its own isolated namespace(s)
- You want Sandbox API to own namespace + OCP user lifecycle
- Simpler labs that deploy directly into sandbox namespaces
- No shared cluster services needed
- Single-team or single-namespace workloads
- Less Ansible role complexity is acceptable
Sandbox API does: Schedule cluster, create namespaces, create OCP user, apply quota
Your roles do: Deploy lab content into the ready namespaces
Decision Guide
| Question | Scheduler-Only | OCP Sandbox API |
|---|---|---|
| Multiple tenants on one cluster? | Yes — designed for this | Usually no (one order = one namespace) |
| Need Keycloak / RHBK SSO per user? | Yes — ocp4_workload_tenant_keycloak_user |
No — sandbox provides an OCP local user |
| Need Gitea org + mirrored repos per user? | Yes — ocp4_workload_tenant_gitea |
Not built-in |
| Need ArgoCD (GitOps) per tenant? | Yes — ocp4_workload_gitops_bootstrap |
Not built-in |
| Need LiteMaaS AI API key per tenant? | Yes — ocp4_workload_litellm_virtual_keys |
Add manually if needed |
| Who creates OCP namespaces? | Your role (ocp4_workload_tenant_namespace) |
Sandbox API (from sandboxes: entries) |
| Who creates OCP user account? | Your role (via Keycloak or HTPasswd) | Sandbox API automatically |
| Cluster provisioner required? | Yes — separate playbook run once per cluster | No — sandbox API handles cluster prep |
sandboxes: entries in AgV |
One OcpSandbox entry under __meta__ with alias, cloud_selector, quota |
One entry per namespace, each with namespace_suffix |
| Complexity | Higher — more roles, more vars | Lower — fewer roles, sandbox handles lifecycle |
Summit 2026 — Scheduler-Only Pattern
Sandbox API schedules a cluster and injects credentials. All per-tenant resources are created by your workloads — RHBK user, namespaces, Gitea instance, ArgoCD Applications. A separate cluster provisioner installs shared services once per cluster.
Key AgV fields: single OcpSandbox entry under __meta__.sandboxes with alias, cloud_selector, and quota. No keycloak: yes — you manage users yourself.
Full guide with complete annotated common.yaml →
OCP Sandbox API Pattern
Sandbox API creates the namespaces and an RHSSO user for each order. Your workloads deploy lab content into the ready-made namespaces. Simpler setup — no cluster provisioner, no Keycloak role, no Gitea role. Less flexibility.
Key AgV fields: one OcpSandbox entry per namespace with namespace_suffix. Add keycloak: "yes" to create an RHSSO user. Use cluster_condition: same('alias') to pin multiple namespaces to the same cluster.
Full guide with complete annotated common.yaml →
Red Hat Demo Platform (RHDP) — Internal developer reference — GitHub