Skip to content

Commit 405ff97

Browse files
committed
docs(openshift): expand OpenShift guide into multi-page section
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 <[email protected]>
1 parent 474d2d4 commit 405ff97

6 files changed

Lines changed: 631 additions & 95 deletions

File tree

‎docs/kubernetes/openshift.mdx‎

Lines changed: 0 additions & 95 deletions
This file was deleted.
Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
---
2+
# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
3+
# SPDX-License-Identifier: Apache-2.0
4+
title: "Gateway Connection"
5+
sidebar-title: "Gateway Connection"
6+
slug: "kubernetes/openshift/gateway-connection"
7+
description: "Connect the OpenShell CLI to a gateway running on OpenShift using port forwarding, a reencrypt Route, or the Kubernetes Gateway API."
8+
keywords: "Generative AI, Cybersecurity, Kubernetes, OpenShift, Route, Gateway API, Istio, gRPC, Ingress, CLI"
9+
position: 2
10+
---
11+
12+
After the gateway is installed, register it with the CLI so you can create and manage sandboxes. The gateway is only reachable inside the cluster by default. How you connect depends on whether you need local-only access or external access for your team.
13+
14+
The gateway multiplexes gRPC and HTTP on a single port. When exposing it externally, the transport must preserve HTTP/2 for gRPC to work.
15+
16+
| Method | HTTP/2 | Config complexity | Dependencies | Use case |
17+
|---|---|---|---|---|
18+
| [Port forward](#local-development) | N/A (direct) | Minimal | None | Local evaluation |
19+
| [Reencrypt Route](#reencrypt-route) | Via annotation | Low (2 commands) | None | OpenShift-native |
20+
| [Gateway API](#gateway-api-with-istio) | Native | Medium (3 YAML resources) | Istio / Gateway API controller | Standard Kubernetes |
21+
22+
## Local development
23+
24+
For quick evaluation without external access, use `oc port-forward`:
25+
26+
```shell
27+
oc -n openshell port-forward svc/openshell 8080:8080
28+
```
29+
30+
Register the gateway with the CLI:
31+
32+
```shell
33+
openshell gateway add http://127.0.0.1:8080 --local --name openshift
34+
openshell status
35+
```
36+
37+
## Why not edge or passthrough?
38+
39+
| Route type | Problem |
40+
|---|---|
41+
| Edge | Terminates TLS and forces HTTP/1.1 to the backend, breaking gRPC. |
42+
| Passthrough | Preserves HTTP/2 but exposes the gateway's mTLS client certificate requirement to browsers, causing `ERR_BAD_SSL_CLIENT_AUTH_CERT`. |
43+
44+
## Reencrypt Route
45+
46+
A reencrypt route terminates external TLS at the OpenShift router, then re-establishes TLS to the gateway backend. The `backend-protocol=h2` annotation tells HAProxy to use HTTP/2 for the backend connection.
47+
48+
```shell
49+
DEST_CA=$(oc get secret openshell-server-tls -n openshell \
50+
-o jsonpath='{.data.ca\.crt}' | base64 -d)
51+
52+
oc create route reencrypt openshell \
53+
--service=openshell --port=8080 \
54+
--dest-ca-cert=<(echo "$DEST_CA") \
55+
-n openshell
56+
57+
oc annotate route openshell -n openshell \
58+
haproxy.router.openshift.io/backend-protocol=h2 --overwrite
59+
```
60+
61+
Register the gateway with the CLI using the route hostname:
62+
63+
```shell
64+
oc get route openshell -n openshell -o jsonpath='{.spec.host}'
65+
openshell gateway add https://<route-hostname> --gateway-insecure --name openshift
66+
```
67+
68+
## Gateway API with Istio
69+
70+
OpenShift manages the Gateway API CRDs through the Ingress Operator. The standard [Envoy Gateway](/kubernetes/ingress) cannot be installed because the Ingress Operator rejects third-party Gateway API CRD installations. Instead, use the OpenShift-managed Istio-based Gateway controller.
71+
72+
<Steps>
73+
74+
## Identify the GatewayClass
75+
76+
```shell
77+
oc get gatewayclass
78+
```
79+
80+
Look for a class with an Istio-based controller (e.g. `istio` or `data-science-gateway-class`). The class must show `ACCEPTED: True`.
81+
82+
## Create the Gateway and GRPCRoute
83+
84+
```shell
85+
kubectl apply -f - <<'EOF'
86+
apiVersion: gateway.networking.k8s.io/v1
87+
kind: Gateway
88+
metadata:
89+
name: openshell-gateway
90+
namespace: openshell
91+
spec:
92+
gatewayClassName: istio
93+
listeners:
94+
- name: grpc
95+
protocol: HTTPS
96+
port: 443
97+
tls:
98+
mode: Terminate
99+
certificateRefs:
100+
- name: openshell-server-tls
101+
kind: Secret
102+
allowedRoutes:
103+
namespaces:
104+
from: Same
105+
---
106+
apiVersion: gateway.networking.k8s.io/v1
107+
kind: GRPCRoute
108+
metadata:
109+
name: openshell
110+
namespace: openshell
111+
spec:
112+
parentRefs:
113+
- name: openshell-gateway
114+
namespace: openshell
115+
rules:
116+
- backendRefs:
117+
- name: openshell
118+
port: 8080
119+
EOF
120+
```
121+
122+
## Configure TLS to the backend
123+
124+
The Istio envoy proxy terminates external TLS at the Gateway, then connects to the backend in plaintext by default. Since the OpenShell gateway expects TLS, create a `DestinationRule` for TLS origination:
125+
126+
```shell
127+
kubectl apply -f - <<'EOF'
128+
apiVersion: networking.istio.io/v1
129+
kind: DestinationRule
130+
metadata:
131+
name: openshell-tls-origination
132+
namespace: openshell
133+
spec:
134+
host: openshell.openshell.svc.cluster.local
135+
trafficPolicy:
136+
tls:
137+
mode: SIMPLE
138+
insecureSkipVerify: true
139+
EOF
140+
```
141+
142+
## Get the external address
143+
144+
The Gateway controller creates a LoadBalancer service. Wait for the external address:
145+
146+
```shell
147+
oc get gateway openshell-gateway -n openshell \
148+
-o jsonpath='{.status.addresses[0].value}'
149+
```
150+
151+
<Note>
152+
AWS ELB DNS names can take 1-2 minutes to propagate after creation.
153+
</Note>
154+
155+
## Register the gateway
156+
157+
```shell
158+
openshell gateway add https://<external-address> --gateway-insecure --name openshift
159+
```
160+
161+
</Steps>
162+
163+
## Next steps
164+
165+
- [OIDC with Keycloak](/kubernetes/openshift/oidc-keycloak) — add `--oidc-issuer` to the `gateway add` command for authenticated access.
Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
---
2+
# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
3+
# SPDX-License-Identifier: Apache-2.0
4+
title: "OpenShift Identity Federation"
5+
sidebar-title: "Identity Federation"
6+
slug: "kubernetes/openshift/identity-federation"
7+
description: "Configure Keycloak to delegate authentication to the OpenShift OAuth server so cluster users can log in with their existing credentials."
8+
keywords: "Generative AI, Cybersecurity, Kubernetes, OpenShift, Keycloak, Identity Federation, OAuth, SSO"
9+
position: 4
10+
---
11+
12+
Keycloak can delegate authentication to the OpenShift OAuth server so users log in with their cluster credentials instead of separate Keycloak accounts. Users are auto-imported into the Keycloak realm on first login.
13+
14+
## Prerequisites
15+
16+
- [OIDC with Keycloak](/kubernetes/openshift/oidc-keycloak) configured and working
17+
- `cluster-admin` access to create `OAuthClient` resources
18+
19+
## Create an OAuthClient in OpenShift
20+
21+
Generate a client secret and create the `OAuthClient` that Keycloak uses to initiate the OAuth flow:
22+
23+
```shell
24+
OCP_SECRET=$(openssl rand -hex 32)
25+
KC_URL=https://keycloak.example.com
26+
27+
cat <<EOF | oc apply -f -
28+
apiVersion: oauth.openshift.io/v1
29+
kind: OAuthClient
30+
metadata:
31+
name: keycloak-openshell
32+
secret: "${OCP_SECRET}"
33+
grantMethod: auto
34+
redirectURIs:
35+
- "${KC_URL}/realms/openshell/broker/openshift/endpoint"
36+
EOF
37+
```
38+
39+
## Add OpenShift as a Keycloak identity provider
40+
41+
<Tabs>
42+
<Tab title="kcadm.sh">
43+
44+
```shell
45+
KC_POD="oc exec keycloak-0 -n keycloak --"
46+
KC_ADM="/opt/keycloak/bin/kcadm.sh"
47+
48+
$KC_POD $KC_ADM create identity-provider/instances -r openshell \
49+
-s alias=openshift \
50+
-s displayName=OpenShift \
51+
-s providerId=openshift-v4 \
52+
-s enabled=true \
53+
-s trustEmail=true \
54+
-s "firstBrokerLoginFlowAlias=first broker login" \
55+
-s "config.clientId=keycloak-openshell" \
56+
-s "config.clientSecret=${OCP_SECRET}" \
57+
-s "config.baseUrl=$(oc whoami --show-server)" \
58+
-s "config.defaultScope=user:info" \
59+
-s "config.syncMode=IMPORT"
60+
```
61+
62+
</Tab>
63+
<Tab title="REST API">
64+
65+
```shell
66+
TOKEN=$(curl -sk "${KC_URL}/realms/master/protocol/openid-connect/token" \
67+
-d "client_id=admin-cli" \
68+
-d "username=<admin-user>" \
69+
-d "password=<admin-password>" \
70+
-d "grant_type=password" | jq -r .access_token)
71+
72+
curl -sk -X POST "${KC_URL}/admin/realms/openshell/identity-provider/instances" \
73+
-H "Authorization: Bearer $TOKEN" \
74+
-H "Content-Type: application/json" \
75+
-d "{
76+
\"alias\": \"openshift\",
77+
\"displayName\": \"OpenShift\",
78+
\"providerId\": \"openshift-v4\",
79+
\"enabled\": true,
80+
\"trustEmail\": true,
81+
\"firstBrokerLoginFlowAlias\": \"first broker login\",
82+
\"config\": {
83+
\"clientId\": \"keycloak-openshell\",
84+
\"clientSecret\": \"${OCP_SECRET}\",
85+
\"baseUrl\": \"$(oc whoami --show-server)\",
86+
\"defaultScope\": \"user:info\",
87+
\"syncMode\": \"IMPORT\"
88+
}
89+
}"
90+
```
91+
92+
</Tab>
93+
</Tabs>
94+
95+
<Note>
96+
**ROSA HCP**: set `baseUrl` to the API server URL (`https://api.<cluster>:443`), not the OAuth route (`oauth.<cluster>`). On ROSA HCP, the OAuth metadata endpoint (`/.well-known/oauth-authorization-server`) is served by the API server. The OAuth route returns 404.
97+
</Note>
98+
99+
## Assign roles to federated users
100+
101+
Users imported from OpenShift do not receive the `openshell-user` or `openshell-admin` realm roles automatically. After a user's first login through the "OpenShift" button, assign the appropriate role through the Keycloak admin console:
102+
103+
**Keycloak Admin Console → Users → select user → Role Mappings → Assign role → openshell-user**
104+
105+
Or via the CLI/API:
106+
107+
<Tabs>
108+
<Tab title="kcadm.sh">
109+
110+
```shell
111+
$KC_POD $KC_ADM add-roles -r openshell \
112+
--uusername <openshift-username> \
113+
--rolename openshell-user
114+
```
115+
116+
</Tab>
117+
<Tab title="REST API">
118+
119+
```shell
120+
USER_ID=$(curl -sk "${KC_URL}/admin/realms/openshell/users?username=<openshift-username>&exact=true" \
121+
-H "Authorization: Bearer $TOKEN" | jq -r '.[0].id')
122+
123+
ROLE_ID=$(curl -sk "${KC_URL}/admin/realms/openshell/roles/openshell-user" \
124+
-H "Authorization: Bearer $TOKEN" | jq -r '.id')
125+
126+
curl -sk -X POST "${KC_URL}/admin/realms/openshell/users/${USER_ID}/role-mappings/realm" \
127+
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
128+
-d "[{\"id\":\"${ROLE_ID}\",\"name\":\"openshell-user\"}]"
129+
```
130+
131+
</Tab>
132+
</Tabs>
133+
134+
## Result
135+
136+
The Keycloak login page shows a "Login with OpenShift" button below the standard username/password form. Clicking it redirects to the OpenShift login page. After authentication, Keycloak issues an OIDC token with the user's identity and assigned roles, and the CLI stores the token.

0 commit comments

Comments
 (0)