OCP Sandbox API — Reference

All Sandbox API Variables — Full Reference

Primary namespace variables (always provided)

Always injected when you have at least one namespace_suffix entry. Correspond to the first (primary) sandbox entry.

Variable	Example value	Description
`sandbox_openshift_namespace`	`mylab-user-abc12`	The primary namespace created by Sandbox API. Format: `<catalog-name>-<suffix>-<guid>`. This is the namespace your main lab resources should be deployed into.
`sandbox_openshift_api_url`	`https://api.cluster-abc12.example.com:6443`	The OpenShift cluster API endpoint. Used by `k8s` Ansible modules and `oc` CLI. Same value for all sandbox entries in a given order (they all land on the same cluster).
`sandbox_openshift_ingress_domain`	`apps.cluster-abc12.example.com`	The wildcard ingress domain for the cluster. Use this to construct Route hostnames and application URLs. E.g., `myapp-{{ sandbox_openshift_namespace }}.{{ sandbox_openshift_ingress_domain }}`.
`sandbox_openshift_console_url`	`https://console-openshift-console.apps.cluster-abc12.example.com`	The full URL to the OpenShift web console. Pass this to Showroom `user_data` for lab attendees to access the console directly from a tab.
`cluster_admin_agnosticd_sa_token`	`eyJhbGciOiJSUzI1NiIs...`	A cluster-admin scoped SA token for AgnosticD. Used internally for all Kubernetes API calls. Never log this variable. Never reference it in your own role variables. Never commit it.
`sandbox_username`	`user-abc12`	The RHSSO user account created by Sandbox API when `keycloak: "yes"` is in `cloud_selector`. Sandbox API supports RHSSO only — not RHBK. Provide to the lab attendee as their SSO login username.
`sandbox_password`	`(generated, from RHDP vault)`	The password for the RHSSO user (`sandbox_username`). Generated by RHDP's secret management system — never hardcode this. Pass it to Showroom for display to the attendee.

Additional namespace variables (per extra sandbox entry)

For each entry after the first, Sandbox API provides a namespace variable prefixed with the entry's name:

sandbox entry name	Variable provided	Example value
`tools`	`sandbox_openshift_tools_namespace`	`mylab-tools-abc12`
`db`	`sandbox_openshift_db_namespace`	`mylab-db-abc12`
`monitoring`	`sandbox_openshift_monitoring_namespace`	`mylab-monitoring-abc12`
`pipeline`	`sandbox_openshift_pipeline_namespace`	`mylab-pipeline-abc12`

Variable naming pattern The pattern is always: sandbox_openshift_<name>_namespace where <name> is the value of the name: key in your sandbox entry. The first entry's namespace uses the short form sandbox_openshift_namespace (no name infix).

The guid variable

Variable	Example	Notes
`guid`	`abc12`	5-character unique identifier for this order. Injected by AgnosticD, not Sandbox API. It appears in all generated names: namespace names, username, etc. Use it when you need to derive unique names not already provided by sandbox vars.

What Sandbox API Handles vs. What You Handle

Sandbox API handles automatically

Namespace creation (one per sandbox entry)
Namespace naming (<catalog>-<suffix>-<guid>)
RHSSO user creation (sandbox_username) — when keycloak: "yes" in cloud_selector
RHSSO user password generation (sandbox_password)
Granting user edit access to the primary namespace
Applying ResourceQuota based on quota vars
Cluster-admin SA token creation and injection
Cluster URL and ingress domain injection
On destroy: namespace deletion (cascade deletes all in-namespace resources)
On destroy: RHSSO user account deletion
On destroy: SA token revocation
On destroy: cluster returned to pool

You handle (via AgnosticD roles)

Deploying your lab application into the provided namespaces
Any cluster-scoped resources your lab needs (use sparingly)
Showroom tab UI configuration and deployment
Any resources that live outside the sandbox-provided namespaces
LiteMaaS virtual keys (if your lab uses AI APIs)
Any external service integrations (webhooks, external registries, etc.)
On destroy: cleaning up any resources you created outside the sandbox namespaces

In-namespace resources are automatically cleaned up When Sandbox API deletes a namespace on destroy, all Kubernetes resources inside it (Deployments, Services, Routes, PVCs, Secrets, ConfigMaps, etc.) are deleted automatically by OpenShift. Your remove_workloads only needs to handle resources that exist outside those namespaces, or resources that require explicit API calls to external systems (like revoking an API key).

Comparison with Scheduler-Only — When to Use Which

Dimension	OCP Sandbox API	Scheduler-Only
Who creates namespaces?	Sandbox API (from `sandboxes:` entries)	Your role (`ocp4_workload_tenant_namespace`)
Who creates the user?	Sandbox API automatically	Your role (Keycloak/RHBK or HTPasswd)
Authentication type	RHSSO user (via `keycloak: yes` in cloud_selector)	RHBK (installed by cluster provisioner)
Namespace naming control	Limited — follows `<catalog>-<suffix>-<guid>` pattern	Full control — `<username>-<suffix>` from your vars
Max namespaces per order	Typically 1–5 (each needs a sandbox entry)	Unlimited (your role creates them all)
Shared services on cluster	Not required	Required (Keycloak, Gitea, ArgoCD pre-installed)
Cluster provisioner needed?	No — sandbox API handles cluster prep	Yes — separate one-time playbook per cluster
LiteMaaS support	Add manually if needed	Built into role list (`ocp4_workload_litellm_virtual_keys`)
ArgoCD / GitOps	Not built-in (add manually if needed)	Built-in (`ocp4_workload_gitops_bootstrap`)
Gitea per-tenant repo	Not built-in	Built-in (`ocp4_workload_tenant_gitea`)
AgV common.yaml complexity	Low — few roles, sandbox vars used directly	High — many roles, complex var dependencies
Destroy complexity	Low — sandbox API cleans up namespaces and user	Medium — each role must be reversed explicitly
Multi-tenant cluster packing	Not the primary use case	Primary use case — many tenants per cluster
Example catalog items	Simple operator labs, single-team workshops, API / pipeline demos	AI/MCP platform labs, Summit multi-tenant workshops

Decision rule of thumb If your lab needs an RHSSO user and one or two namespaces with simple deployment, use OCP Sandbox API. If your lab needs RHBK, per-tenant Gitea repos, ArgoCD GitOps, or multiple custom namespaces, use Scheduler-Only.

Quota and Destroy Notes

Quota configuration

Set these variables in your AgV common.yaml to control cluster capacity per order:

Variable	Default (if unset)	Recommended range for typical labs
`quota_requests_cpu`	2	"2" – "8" depending on workload
`quota_requests_memory`	4Gi	4Gi – 16Gi
`quota_limits_cpu`	4	Should be 2x requests
`quota_limits_memory`	8Gi	Should be 2x requests
`quota_pods`	25	"25" – "100"

Quota applies per namespace, per sandbox entry If you have two sandbox entries (e.g., user and tools), the quota is applied independently to each namespace. An order with two namespace entries will consume up to 2x the declared quota from the cluster's total capacity. Size accordingly.

Destroy behavior

When an order is destroyed, the sequence is:

AgnosticD runs remove_workloads — your roles clean up external resources (e.g., revoke an API key, remove a webhook, delete a Showroom deployment)
Sandbox API deletes all namespaces for this order — all in-namespace Kubernetes resources are cascade-deleted automatically by OpenShift
Sandbox API deletes the RHSSO user account (sandbox_username)
Sandbox API revokes the cluster-admin SA token used by AgnosticD
Sandbox API returns the cluster to the pool (or schedules cluster retirement)

Keep remove_workloads short Because Sandbox API handles namespace and user deletion, your remove_workloads list should only include roles that created resources outside the sandbox namespaces, or roles (like Showroom) that need an explicit API call to clean up. Do not replicate what Sandbox API already handles.

PVC data is permanently lost on destroy PersistentVolumeClaims inside sandbox namespaces are deleted with the namespace. There is no backup. If your lab requires data persistence across sessions or restarts, you must design for it explicitly (e.g., use an external object store, or document that data is ephemeral).

Important notes

Do not create cluster-scoped resources (ClusterRoles, ClusterRoleBindings, CRDs, etc.) unless absolutely necessary — they are not automatically cleaned up when the namespace is deleted and can accumulate across orders
LimitRange: Sandbox API also applies a LimitRange with default container CPU/memory limits. This means containers without explicit resource requests will inherit these defaults. Design your workloads with this in mind.
sandbox_password security: The sandbox password is managed by RHDP's vault system. Never log it, never store it in a ConfigMap or Secret that persists beyond the lab session, and never commit it to Git.
cluster_admin_agnosticd_sa_token security: This token has full cluster-admin access. It is used exclusively by AgnosticD internally. Do not pass it to your role variables or use it in templates.

Red Hat Demo Platform (RHDP) — Internal developer reference — Back to overview — Scheduler-Only pattern — GitHub

← Previous: OCP Sandbox API — common.yaml