/ambient

name: ambient
description: >-
  Install and verify Ambient Code Platform on an OpenShift cluster using quay.io images.
  Use when deploying Ambient to any OpenShift namespace — production, ephemeral PR test
  instances, or developer clusters. Covers secrets, kustomize deploy, rollout verification,
  and troubleshooting.

Ambient Installer Skill

You are an expert in deploying the Ambient Code Platform to OpenShift clusters. This skill covers everything needed to go from an empty namespace to a running Ambient installation using images from quay.io.

> **Developer registry override:** If you need to use images from the OpenShift internal registry instead of quay.io (e.g. for local dev builds), see `docs/internal/developer/local-development/openshift.md`.

---

Platform Components

| Deployment | Image | Purpose | |-----------|-------|---------| | `backend-api` | `quay.io/ambient_code/vteam_backend` | Go REST API, manages K8s CRDs | | `frontend` | `quay.io/ambient_code/vteam_frontend` | NextJS web UI | | `agentic-operator` | `quay.io/ambient_code/vteam_operator` | Kubernetes operator | | `ambient-api-server` | `quay.io/ambient_code/vteam_api_server` | Stateless API server | | `ambient-api-server-db` | (postgres sidecar) | API server database | | `public-api` | `quay.io/ambient_code/vteam_public_api` | External API gateway | | `postgresql` | (upstream) | Unleash feature flag DB | | `minio` | (upstream) | S3 object storage | | `unleash` | (upstream) | Feature flag service |

Runner pods (`vteam_claude_runner`, `vteam_state_sync`) are spawned dynamically by the operator — they are not standing deployments.

Credential sidecar containers are injected into session pods when the corresponding credential type is configured:

< /dev/null | Sidecar Container | Image | Port | Provider | |-------------------|-------|------|----------| | `credential-github` | `quay.io/ambient_code/vteam_credential_github` | 8091 | GitHub PAT / App | | `credential-jira` | `quay.io/ambient_code/vteam_credential_jira` | 8092 | Jira / Atlassian | | `credential-k8s` | `quay.io/ambient_code/vteam_credential_k8s` | 8093 | Kubeconfig | | `credential-google` | `quay.io/ambient_code/vteam_credential_google` | 8094 | Google Workspace |

---

Prerequisites

• `oc` CLI installed and logged in to the target cluster
• `kustomize` installed (`curl -s https://raw.githubusercontent.com/kubernetes-sigs/kustomize/master/hack/install_kustomize.sh | bash`)
• Target namespace already exists and is Active
• Quay.io images are accessible from the cluster (public repos or image pull secret in place)

---

Step 1: Apply CRDs and RBAC (cluster-scoped, once per cluster)

oc apply -k components/manifests/base/crds/
oc apply -k components/manifests/base/rbac/

These are idempotent. On a shared cluster where CRDs already exist from another namespace, this is safe to re-run.

---

Step 2: Create Required Secrets

All secrets must exist **before** applying the kustomize overlay. The deployment will fail if any are missing.

NAMESPACE=<target-namespace>

oc create secret generic minio-credentials -n $NAMESPACE \
  --from-literal=root-user=<MINIO_ROOT_USER> \
  --from-literal=root-password=<MINIO_ROOT_PASSWORD>

oc create secret generic postgresql-credentials -n $NAMESPACE \
  --from-literal=db.host=postgresql \
  --from-literal=db.port=5432 \
  --from-literal=db.name=postgres \
  --from-literal=db.user=postgres \
  --from-literal=db.password=<POSTGRES_PASSWORD>

oc create secret generic unleash-credentials -n $NAMESPACE \
  --from-literal=database-url=postgres://postgres:<POSTGRES_PASSWORD>@postgresql:5432/unleash \
  --from-literal=database-ssl=false \
  --from-literal=admin-api-token='*:*.<UNLEASH_ADMIN_TOKEN>' \
  --from-literal=client-api-token=default:development.<UNLEASH_CLIENT_TOKEN> \
  --from-literal=frontend-api-token=default:development.<UNLEASH_FRONTEND_TOKEN> \
  --from-literal=default-admin-password=<UNLEASH_ADMIN_PASSWORD>

oc create secret generic github-app-secret -n $NAMESPACE \
  --from-literal=GITHUB_APP_ID="<GITHUB_APP_ID>" \
  --from-literal=GITHUB_PRIVATE_KEY="<GITHUB_PRIVATE_KEY>" \
  --from-literal=GITHUB_CLIENT_ID="<GITHUB_CLIENT_ID>" \
  --from-literal=GITHUB_CLIENT_SECRET="<GITHUB_CLIENT_SECRET>" \
  --from-literal=GITHUB_STATE_SECRET=<GITHUB_STATE_SECRET>

Use `--dry-run=client -o yaml | oc apply -f -` to make secret creation idempotent on re-runs.

Credential Encryption Key (required for production)

Credential tokens are encrypted at rest with AES-256-GCM. Generate a key and create the secret:

ENCRYPTION_KEY=$(openssl rand -base64 32)
oc create secret generic credential-encryption-key -n $NAMESPACE \
  --from-literal=keyring="{\"1\":\"$ENCRYPTION_KEY\"}" \
  --from-literal=version=1

The hcmais overlay mounts this as `CREDENTIAL_ENCRYPTION_KEYRING` and `CREDENTIAL_ENCRYPTION_KEY_VERSION`. After first deploy, encrypt existing tokens:

oc exec deploy/ambient-api-server -n $NAMESPACE -- ambient-api-server encrypt-credentials

To rotate: add new key to keyring JSON, bump version, restart, re-run `encrypt-credentials`. To skip in dev: set `CREDENTIAL_ENCRYPTION_ALLOW_PLAINTEXT=true`. See `specs/security/credential-encryption.spec.md`.

Anthropic API Key (required for runner pods)

oc create secret generic ambient-runner-secrets -n $NAMESPACE \
  --from-literal=ANTHROPIC_API_KEY=<key>

Vertex AI (optional, instead of direct Anthropic)

oc create secret generic ambient-vertex -n $NAMESPACE \
  --from-file=ambient-code-key.json=/path/to/service-account-key.json

If using Vertex, set `USE_VERTEX=1` in the operator ConfigMap (see Step 4).

---

Step 3: Deploy with Kustomize

Scripted (preferred for ephemeral/PR namespaces)

`components/pr-test/install.sh` encapsulates Steps 2–6 into a single script. It copies secrets from the source namespace, deploys via a temp-dir kustomize overlay (no git working tree mutations), p