docs(openshift): expand OpenShift guide into multi-page section with TLS, OIDC, and ingress

[akram]

Summary

Replace the single-page plaintext-only OpenShift guide with a multi-page section covering TLS-enabled installation, external gateway access (reencrypt Route and Gateway API with Istio), Keycloak OIDC authentication with the required protocol mappers, and OpenShift identity federation. All Keycloak commands are provided in both kcadm.sh and REST API tabs.

Related Issue

Addresses #2091

Changes

• openshift.mdx → openshift/index.mdx: landing page with Cards linking to four sub-pages
• openshift/install.mdx: TLS-enabled installation with SCC overrides, preserves all original content (namespace creation, SCC binding, Helm overrides table, deployment rollout tip)
• openshift/gateway-connection.mdx: three connection methods — local port-forward, reencrypt Route (with explanation of why edge and passthrough break gRPC), and Gateway API with Istio (including DestinationRule for TLS origination)
• openshift/oidc-keycloak.mdx: Keycloak realm/client setup, the three required protocol mappers (sub, aud, realm_access.roles), realm roles, Helm OIDC values, and CLI registration with --oidc-issuer
• openshift/identity-federation.mdx: OpenShift OAuth as a Keycloak openshift-v4 identity provider, with the ROSA HCP baseUrl caveat and federated user role assignment

Testing

• Deployed on ROSA HCP 4.21 (OpenShift 4.21.3, Kubernetes 1.34.2)
• Tested all kcadm.sh commands end-to-end from a clean realm (--config /tmp/kcadm.config required for non-root Keycloak containers)
• Tested both reencrypt Route and Gateway API (Istio) paths for external access
• Verified OIDC login with Keycloak and OpenShift identity federation (browser flow with "Login with OpenShift" button)
• mise run pre-commit — passes (helm:lint fails on main too: missing postgresql dependency, pre-existing)
• Unit tests added/updated — N/A, documentation only
• E2E tests added/updated — N/A, documentation only

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)
• Architecture docs updated (if applicable) — N/A

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[akram]

@TaylorMutch can you PTAL ?

[akram]

@TaylorMutch I took into account the review comments and made changes. Let me know if squash+rebase is needed.

[TaylorMutch]

/ok to test 2090fb7

[TaylorMutch]

I've thought about this PR a bit more, and here's what I am thinking:

Platform deployers of OpenShell on Kubernetes or OpenShift will want a single page describing the ingress, identity, OIDC and TLS specifics needed for deploying OpenShell. I think splitting these out into OpenShift specific docs and then the other Kubernetes docs makes docs navigation more complicated.

If you are up for it, I would be open to incorporating OpenShift specifics into the overall Kubernetes docs pages, so that those pages are focused on the specific features of Ingress, Identity, OIDC, etc., rather than a specific platform like OpenShift. Then any OpenShift-specifics can be highlighted within the context of that feature.

What do you think @akram ? I am very much in favor of expanding OpenShift specific documentation, but I think this PR in it's current state dilutes and possibly duplicates information across our docs.

[akram]

What do you think @akram ? I am very much in favor of expanding OpenShift specific documentation, but I think this PR in it's current state dilutes and possibly duplicates information across our docs.

Agree @TaylorMutch ; I was hesitating as well to have this specific section, or to have specific paragraphs for each case. I will rework it entirely then.

[akram]

Hey @TaylorMutch, apologies for the delay — I was on PTO.

I've reworked the PR per your feedback — OpenShift specifics are now integrated into the existing K8s docs pages (access-control, ingress, openshift) instead of separate pages.

I also validated the full install path end-to-end on a fresh ROSA HCP 4.22.8 cluster:

• Agent Sandbox CRDs v0.5.4 installed successfully (note: the Helm chart README references manifest.yaml but the actual release asset is sandbox.yaml — might be worth a separate fix)
• OpenShell Helm chart v0.0.98 deployed with the documented OpenShift overrides (fsGroup=null, runAsUser=null, SCC binding)
• Gateway: healthy, Kubernetes compute driver connected, sandbox reconciliation active
• Sandbox lifecycle: create, exec, file upload/download, delete — all working
• Policy enforcement: network policies are correctly enforced per-binary
• Cold start: ~37s including 3.2 GB base image pull

Ready for another look when you get a chance.

[johntmyers]

hey @akram Taylor is OOO, but I can try and help. can you rebase?

[johntmyers]

gator-agent

Blocked

Head SHA: 1626004b1f43c7500d4d3e80b3cc78833f296f9a
Gator payload: 4

Gator is blocked because PR #2094 currently has merge conflicts with main.

Taylor Mutch's main documentation request appears substantially addressed in this head: the OpenShift-specific guidance is integrated into the existing Kubernetes feature pages (access-control.mdx and ingress.mdx), while openshift.mdx remains the platform install page instead of becoming a separate multi-page hierarchy. I also checked Taylor's earlier question about data-science-gateway-class: that name still appears in the current ingress diff even though the author later said the reference was removed, so the rebased update should either remove it or retain the accompanying explanation.

Thanks @johntmyers for identifying the immediate next step. Next action: @akram, please rebase this branch onto current main, resolve the conflicts, and preserve the consolidated documentation structure. Gator will review the new head and dispatch the authorized E2E run after the branch is mergeable.