docs(deploy): document gateway-trusted-ca for OpenShift OIDC

[bsquizz]

Summary

• Documents the required gateway-trusted-ca ConfigMap setup for OpenShift clusters using gateway OIDC (Keycloak)
• Adds troubleshooting entry for the "OIDC key refresh failed" / "JWKS fetch failed" error
• Documents the privileged SCC requirement for sandbox pods on OpenShift
• Updates deployment README index with links to the new sections

Context

gateway-trusted-ca (8c56a6c)

On OpenShift, the gateway container image (scratch/distroless) has no system CA bundle. When OIDC is configured against a Keycloak instance exposed via an OpenShift Route, the gateway cannot complete the TLS handshake to fetch JWKS keys — the ingress CA that signed the Route's certificate is not trusted.

The control plane already supports injecting a trusted CA via the gateway-trusted-ca ConfigMap (SSL_CERT_FILE + volume mount), but this prerequisite was undocumented.

privileged SCC for sandbox pods (facf463)

On OpenShift, the openshell-sandbox service account needs the privileged SCC in each tenant namespace or sandbox pods fail to start. This requirement was undocumented.

Test plan

• Verify the oc get configmap router-ca command works on a ROSA/OCP cluster
• Confirm the ConfigMap name (gateway-trusted-ca) and key (ca-bundle.crt) match the constants in gateway_reconciler.go
• Verify the oc adm policy command for the privileged SCC works on a ROSA/OCP cluster
• Verify links in the deployment README resolve correctly

🤖 Generated with Claude Code

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://openshift-online.github.io/agent-control-plane/pr-preview/pr-459/
Built to branch gh-pages at 2026-08-03 14:21 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[JGiola]

Can we add a configuration where we can set the name of the ConfigMap to load? copying the value from the injected ones to another is prone to having it rot. What if the CA inside it expire? or is rotated for security? we will have downtime, if we point to the one managed automatically by the OpenShift automations we are sure to always have the latest one...

[YiqinZhang]

🤖 Amber Review

Pure documentation addition filling a real operational gap. Adds gateway-trusted-ca ConfigMap setup instructions and troubleshooting steps for OpenShift OIDC with self-signed certs.

Findings:

• Minor: No code link from gateway_reconciler.go constants to the docs — if the ConfigMap name/key ever changes, docs will silently drift. Worth a cross-reference comment.
• Minor: oc get configmap router-ca -n openshift-config-managed may not apply to all OCP variants (e.g., ROSA with STS) — a brief variant note would help.

No code changes, no security surface touched. Content accurately reflects the running implementation.

Confidence: High

---

— Amber, ACP codebase intelligence

[bsquizz]

Can we add a configuration where we can set the name of the ConfigMap to load? copying the value from the injected ones to another is prone to having it rot. What if the CA inside it expire? or is rotated for security? we will have downtime, if we point to the one managed automatically by the OpenShift automations we are sure to always have the latest one...

Let's write a new spec for this if we want to change the behavior. I'll keep this PR to simply be a doc PR