Skip to content

Commit 869c923

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 869c923

6 files changed

Lines changed: 638 additions & 95 deletions

File tree

‎docs/kubernetes/openshift.mdx‎

Lines changed: 0 additions & 95 deletions
This file was deleted.
Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
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+
| Method | Use case |
15+
|---|---|
16+
| [Port forward](#local-access) | Local evaluation from your workstation |
17+
| [Route](#remote-access-with-routes) | Shared or production access using OpenShift-native routing |
18+
| [Gateway API](#remote-access-with-gateway-api) | Shared or production access using the standard Kubernetes Gateway API |
19+
20+
## Local access
21+
22+
For quick evaluation, forward the gateway port to your workstation:
23+
24+
```shell
25+
oc -n openshell port-forward svc/openshell 8080:8080
26+
```
27+
28+
Register the gateway with the CLI:
29+
30+
```shell
31+
openshell gateway add http://127.0.0.1:8080 --local --name openshift
32+
openshell status
33+
```
34+
35+
## Remote access
36+
37+
In shared and production environments, the gateway is exposed externally so that team members and CI systems can connect from outside the cluster. On OpenShift, there are two options: native Routes or the Kubernetes Gateway API.
38+
39+
The gateway multiplexes gRPC and HTTP on a single port. Both options must preserve HTTP/2 for gRPC to work.
40+
41+
### Remote access with Routes
42+
43+
OpenShift Routes are the simplest way to expose the gateway externally. However, not all route types support gRPC:
44+
45+
| Route type | gRPC support | Issue |
46+
|---|---|---|
47+
| Edge | Broken | Terminates TLS and forces HTTP/1.1 to the backend, which drops gRPC frames. |
48+
| Passthrough | Broken | Preserves HTTP/2 but exposes the gateway's mTLS client certificate requirement to browsers, causing `ERR_BAD_SSL_CLIENT_AUTH_CERT`. |
49+
| **Reencrypt** | **Works** | Terminates external TLS at the router, re-establishes TLS to the backend, and supports HTTP/2 with the `backend-protocol=h2` annotation. |
50+
51+
Create a reencrypt route using the gateway's CA certificate for the backend TLS connection:
52+
53+
```shell
54+
DEST_CA=$(oc get secret openshell-server-tls -n openshell \
55+
-o jsonpath='{.data.ca\.crt}' | base64 -d)
56+
57+
oc create route reencrypt openshell \
58+
--service=openshell --port=8080 \
59+
--dest-ca-cert=<(echo "$DEST_CA") \
60+
-n openshell
61+
62+
oc annotate route openshell -n openshell \
63+
haproxy.router.openshift.io/backend-protocol=h2 --overwrite
64+
```
65+
66+
Register the gateway with the CLI using the route hostname:
67+
68+
```shell
69+
oc get route openshell -n openshell -o jsonpath='{.spec.host}'
70+
openshell gateway add https://<route-hostname> --gateway-insecure --name openshift
71+
```
72+
73+
### Remote access with Gateway API
74+
75+
The Kubernetes [Gateway API](https://gateway-api.sigs.k8s.io) provides native gRPC routing via `GRPCRoute` resources, without needing HTTP/2 annotations.
76+
77+
On OpenShift, the Ingress Operator manages Gateway API CRDs. The standard [Envoy Gateway](/kubernetes/ingress) cannot be installed because the Ingress Operator rejects third-party CRD installations. Instead, use the Istio-based Gateway controller that OpenShift provides.
78+
79+
<Steps>
80+
81+
## Identify the GatewayClass
82+
83+
```shell
84+
oc get gatewayclass
85+
```
86+
87+
Look for a class with an Istio-based controller (e.g. `istio` or `data-science-gateway-class`). The class must show `ACCEPTED: True`.
88+
89+
## Create the Gateway and GRPCRoute
90+
91+
```shell
92+
kubectl apply -f - <<'EOF'
93+
apiVersion: gateway.networking.k8s.io/v1
94+
kind: Gateway
95+
metadata:
96+
name: openshell-gateway
97+
namespace: openshell
98+
spec:
99+
gatewayClassName: istio
100+
listeners:
101+
- name: grpc
102+
protocol: HTTPS
103+
port: 443
104+
tls:
105+
mode: Terminate
106+
certificateRefs:
107+
- name: openshell-server-tls
108+
kind: Secret
109+
allowedRoutes:
110+
namespaces:
111+
from: Same
112+
---
113+
apiVersion: gateway.networking.k8s.io/v1
114+
kind: GRPCRoute
115+
metadata:
116+
name: openshell
117+
namespace: openshell
118+
spec:
119+
parentRefs:
120+
- name: openshell-gateway
121+
namespace: openshell
122+
rules:
123+
- backendRefs:
124+
- name: openshell
125+
port: 8080
126+
EOF
127+
```
128+
129+
## Configure TLS to the backend
130+
131+
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:
132+
133+
```shell
134+
kubectl apply -f - <<'EOF'
135+
apiVersion: networking.istio.io/v1
136+
kind: DestinationRule
137+
metadata:
138+
name: openshell-tls-origination
139+
namespace: openshell
140+
spec:
141+
host: openshell.openshell.svc.cluster.local
142+
trafficPolicy:
143+
tls:
144+
mode: SIMPLE
145+
insecureSkipVerify: true
146+
EOF
147+
```
148+
149+
## Get the external address
150+
151+
The Gateway controller creates a LoadBalancer service. Wait for the external address:
152+
153+
```shell
154+
oc get gateway openshell-gateway -n openshell \
155+
-o jsonpath='{.status.addresses[0].value}'
156+
```
157+
158+
<Note>
159+
AWS ELB DNS names can take 1-2 minutes to propagate after creation.
160+
</Note>
161+
162+
## Register the gateway
163+
164+
```shell
165+
openshell gateway add https://<external-address> --gateway-insecure --name openshift
166+
```
167+
168+
</Steps>
169+
170+
## Next steps
171+
172+
- [OIDC with Keycloak](/kubernetes/openshift/oidc-keycloak) — add `--oidc-issuer` to the `gateway add` command for authenticated access.

0 commit comments

Comments
 (0)