docs(openshift): expand OpenShift guide into multi-page section with TLS, OIDC, and ingress#2094
docs(openshift): expand OpenShift guide into multi-page section with TLS, OIDC, and ingress#2094akram wants to merge 4 commits into
Conversation
Replace the single-page plaintext-only OpenShift guide with a section containing four sub-pages: - install: TLS-enabled installation with SCC overrides - external-access: reencrypt Route and Gateway API (Istio) options - oidc-keycloak: Keycloak OIDC setup with required protocol mappers - identity-federation: OpenShift OAuth as a Keycloak identity provider Addresses NVIDIA#2091 Signed-off-by: Akram <akram.benaissi@gmail.com>
akram
requested review from
a team,
derekwaynecarr,
maxamillion and
mrunalp
as code owners
|
@TaylorMutch can you PTAL ? |
Address review feedback: remove the Note about AWS ELB DNS propagation delay as it is not specific to the OpenShell setup. Signed-off-by: Akram <akram.benaissi@gmail.com>
Address review feedback: identity federation is a specific use case for organisations that want OpenShell users to authenticate with their existing OpenShift credentials. The OIDC Keycloak setup works standalone. Mark the identity federation page and all references as optional. Signed-off-by: Akram <akram.benaissi@gmail.com>
Address review feedback: the Keycloak realm/client/mapper/role setup is not OpenShift-specific. Move the full setup (with kcadm.sh and REST API tabs) to docs/kubernetes/access-control.mdx under a new "Keycloak setup" section. The OpenShift oidc-keycloak page now references the generic guide and only contains OpenShift-specific steps (Helm upgrade, CLI connection with --oidc-issuer). Signed-off-by: Akram <akram.benaissi@gmail.com>
|
@TaylorMutch I took into account the review comments and made changes. Let me know if squash+rebase is needed. |
|
/ok to test 2090fb7 |
TaylorMutch
left a comment
TaylorMutch
left a comment
There was a problem hiding this comment.
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.
| oc get gatewayclass | ||
| ``` | ||
|
|
||
| Look for a class with an Istio-based controller (e.g. `istio` or `data-science-gateway-class`). The class must show `ACCEPTED: True`. |
There was a problem hiding this comment.
What is "data-science-gateway-class"?
|
|
||
| The gateway multiplexes gRPC and HTTP on a single port. Both options must preserve HTTP/2 for gRPC to work. | ||
|
|
||
| ### Remote access with Routes |
There was a problem hiding this comment.
Even though this is OpenShift specific I do feel strongly that these docs are somewhat duplicative with the existing ingress docs we have. I think it would be better to have those docs in one place, rather than have a whole section dedicated to OpenShift specifics.
2 participants
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.shand REST API tabs.Related Issue
Addresses #2091
Changes
openshift.mdx→openshift/index.mdx: landing page with Cards linking to four sub-pagesopenshift/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 (includingDestinationRulefor 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-issueropenshift/identity-federation.mdx: OpenShift OAuth as a Keycloakopenshift-v4identity provider, with the ROSA HCPbaseUrlcaveat and federated user role assignmentTesting
kcadm.shcommands end-to-end from a clean realm (--config /tmp/kcadm.configrequired for non-root Keycloak containers)mise run pre-commit— passes (helm:lint fails on main too: missing postgresql dependency, pre-existing)Checklist