docs(openshift): expand OpenShift guide with TLS, OIDC, ingress, and federated identity

[akram]

Problem Statement

The current OpenShift documentation (docs/kubernetes/openshift.mdx) covers only a minimal plaintext HTTP + oc port-forward setup with TLS and PKI disabled. Users who follow the guide end up with no external access, no authentication, and no path forward beyond "refer to Ingress."

The generic ingress docs (docs/kubernetes/ingress.mdx) only cover Envoy Gateway, which cannot be installed on OpenShift because the Ingress Operator manages Gateway API CRDs and rejects the installation. There is no documented path for exposing the gateway on OpenShift.

The existing OpenShift page has:

• ✅ Namespace creation and SCC binding
• ✅ Basic Helm install command
• ❌ TLS (explicitly disabled)
• ❌ External access (only oc port-forward)
• ❌ Authentication (none)
• ❌ OIDC / Keycloak
• ❌ OpenShift Routes
• ❌ Gateway API / Istio
• ❌ Identity federation

Proposed Design

Expand docs/kubernetes/openshift.mdx into a multi-page section (docs/kubernetes/openshift/) with four sub-pages, following the same pattern as get-started/tutorials/:

1. Install (openshift/install.mdx)

TLS-enabled installation with SCC overrides. Replace the current plaintext-only path with pkiInitJob.enabled=true (the default). Document the SCC overrides (fsGroup=null, runAsUser=null) alongside TLS.

2. Gateway Connection (openshift/gateway-connection.mdx)

Three connection methods with trade-offs:

• Local access: oc port-forward for evaluation
• Routes: Why edge and passthrough break gRPC, reencrypt route with backend-protocol=h2 annotation as the working solution
• Gateway API: Using the OpenShift-managed Istio GatewayClass with GRPCRoute + DestinationRule for TLS origination. Note that Envoy Gateway cannot be installed on OpenShift.

3. OIDC with Keycloak (openshift/oidc-keycloak.mdx)

• Creating a Keycloak realm, public client, and the required protocol mappers (sub, aud, realm_access.roles) — Keycloak does not include these in access tokens for public clients by default
• Helm values for OIDC with role-based access
• The --oidc-issuer flag on gateway add — without it, the CLI defaults to the Cloudflare edge-auth flow which hangs indefinitely (bug: gateway add defaults to Cloudflare edge-auth for HTTPS endpoints — no fallback or guidance for non-CF deployments #2057)

4. Identity Federation (openshift/identity-federation.mdx)

• Creating an OAuthClient in OpenShift
• Configuring the openshift-v4 IdP in Keycloak
• ROSA HCP caveat: baseUrl must be the API server URL, not the OAuth route
• Assigning realm roles to federated users after first login

All Keycloak commands provided in both kcadm.sh and REST API tabs.

Alternatives Considered

1. Update the existing single page: Adding all four topics to one page would make it too long (~600 lines) and hard to navigate. The multi-page section with a Cards index follows the established pattern (get-started/tutorials/).

2. Add OpenShift notes to existing generic pages (ingress.mdx, access-control.mdx): Spreading OpenShift-specific content across multiple generic pages makes the OpenShift story hard to follow end-to-end. A dedicated section is easier to discover and maintain.

3. Keep plaintext-only and link to generic docs: The current approach. Doesn't work because the generic ingress docs require Envoy Gateway (blocked on OpenShift) and the generic OIDC docs don't cover the Keycloak mappers required for public clients.

Agent Investigation

• Deployed and validated all four topics end-to-end on ROSA HCP 4.21 (OpenShift 4.21.3, Kubernetes 1.34.2)
• Tested both reencrypt Route and Gateway API (Istio) paths for external access
• Tested all kcadm.sh commands in the Keycloak pod (--config /tmp/kcadm.config required for non-root containers)
• Tested OIDC login with Keycloak and OpenShift identity federation (browser flow with "Login with OpenShift" button)
• Implementation PR: docs(openshift): expand OpenShift guide into multi-page section with TLS, OIDC, and ingress #2094

Related

• bug: gateway add defaults to Cloudflare edge-auth for HTTPS endpoints — no fallback or guidance for non-CF deployments #2057 — CLI edge-auth defaults to Cloudflare
• bug: PKI certgen hardcodes namespace "openshell" in server certificate SANs — breaks deployments in other namespaces #2060 / fix(helm): generate namespace-aware SANs in certgen and cert-manager templates #2062 — certgen hardcodes namespace in SANs
• Support TLS termination for the Envoy Gateway ingress #2017 — TLS termination for Envoy Gateway ingress (Envoy-specific)
• feat: Support restricted SecurityContextConstraints for managed Kubernetes platforms #899 — restricted SCC support / Platform mode
• docs(openshift): expand OpenShift guide into multi-page section with TLS, OIDC, and ingress #2094 — implementation PR

---

• I've reviewed existing issues and the architecture docs
• This is a design proposal, not a "please build this" request

[TaylorMutch]

Any improvement on the OpenShift front is very welcome! PRs for docs or improvements to support OpenShift would be great!

[akram]

Any improvement on the OpenShift front is very welcome! PRs for docs or improvements to support OpenShift would be great!

Hey @TaylorMutch here it is: please see #2094