mirror of
https://github.com/NVIDIA/OpenShell.git
synced 2026-10-23 06:30:28 +08:00
Taylor Mutch
316c788eac
* fix(helm): derive grpcEndpoint from chart context The chart hardcoded server.grpcEndpoint to https://openshell.openshell.svc.cluster.local:8080, which only matched the in-cluster Service DNS for the standard release name and namespace. A new helper now builds <scheme>://<fullname>.<namespace>.svc.cluster.local:<port> from chart context, picking the scheme from server.disableTls. An explicit server.grpcEndpoint override is passed through verbatim. * chore(scripts): validate k3d cluster name length early helm-k3s-local.sh derives the cluster name from the current branch suffix. Long branch names produced names exceeding k3d's 32-char cap and failed deep inside k3d cluster create with a confusing validation error. cmd_create now bails out before invoking docker/k3d with a copy-pasteable HELM_K3S_CLUSTER_NAME override hint. Status, start, stop, delete, and help remain unaffected so an over-long derived name does not block diagnostics.
130 lines
3.3 KiB
Markdown
130 lines
3.3 KiB
Markdown
# Deploying and Connecting to a Gateway
|
|
|
|
Deploy or register an OpenShell gateway, verify it is reachable, and run your first sandbox. This example covers Helm-managed Kubernetes gateways, existing gateway endpoints, and Cloudflare-fronted deployments.
|
|
|
|
## Prerequisites
|
|
|
|
- OpenShell CLI installed (`openshell`)
|
|
- A reachable gateway endpoint, or access to a Kubernetes cluster where you can install the Helm chart
|
|
|
|
## Helm Deployment
|
|
|
|
Install the gateway into a Kubernetes cluster you manage:
|
|
|
|
```bash
|
|
kubectl create namespace openshell
|
|
helm upgrade --install openshell deploy/helm/openshell \
|
|
--namespace openshell \
|
|
--set server.disableTls=true \
|
|
--set service.type=ClusterIP
|
|
```
|
|
|
|
For local evaluation, forward the service and register the forwarded endpoint:
|
|
|
|
```bash
|
|
kubectl -n openshell port-forward svc/openshell 8080:8080
|
|
openshell gateway add http://127.0.0.1:8080 --local --name local
|
|
```
|
|
|
|
Production deployments should keep TLS enabled or place the gateway behind a trusted TLS-terminating ingress, load balancer, or access proxy.
|
|
|
|
## Existing Gateway Endpoint
|
|
|
|
Register a gateway that is already running:
|
|
|
|
```bash
|
|
openshell gateway add https://gateway.example.com --name production
|
|
```
|
|
|
|
Verify the gateway:
|
|
|
|
```bash
|
|
openshell status
|
|
```
|
|
|
|
Expected output:
|
|
|
|
```text
|
|
Gateway: https://gateway.example.com
|
|
Status: HEALTHY
|
|
Version: <version>
|
|
```
|
|
|
|
## Create a Sandbox
|
|
|
|
```bash
|
|
openshell sandbox create --name hello -- echo "it works"
|
|
openshell sandbox connect hello
|
|
```
|
|
|
|
Clean up the sandbox when finished:
|
|
|
|
```bash
|
|
openshell sandbox delete hello
|
|
```
|
|
|
|
## Edge-Authenticated Gateway
|
|
|
|
For gateways running behind a reverse proxy that handles authentication, such as Cloudflare Access, register the endpoint and authenticate via browser:
|
|
|
|
```bash
|
|
openshell gateway add https://gateway.example.com
|
|
```
|
|
|
|
This opens your browser for the proxy's login flow. After authentication, the CLI stores a bearer token and sets the gateway as active.
|
|
|
|
To re-authenticate after token expiry:
|
|
|
|
```bash
|
|
openshell gateway login
|
|
```
|
|
|
|
### How Edge-Authenticated Connections Differ
|
|
|
|
Reverse proxies that authenticate via browser-style GET requests are incompatible with gRPC's HTTP/2 POST transport. To work around this, the CLI uses a WebSocket tunnel:
|
|
|
|
1. The CLI starts a local proxy that listens on an ephemeral port.
|
|
2. gRPC traffic is sent as plaintext HTTP/2 to this local proxy.
|
|
3. The proxy opens a WebSocket (`wss://`) to the gateway's tunnel endpoint, attaching the bearer token in the upgrade headers.
|
|
4. The edge proxy authenticates the WebSocket upgrade request.
|
|
5. The gateway receives the WebSocket connection and pipes it into the same gRPC service that handles direct mTLS connections.
|
|
|
|
This is transparent to the user. CLI commands work the same regardless of whether the gateway uses mTLS or edge authentication.
|
|
|
|
## Managing Multiple Gateways
|
|
|
|
List all registered gateways:
|
|
|
|
```bash
|
|
openshell gateway select
|
|
```
|
|
|
|
Switch the active gateway:
|
|
|
|
```bash
|
|
openshell gateway select production
|
|
```
|
|
|
|
Override the active gateway for a single command:
|
|
|
|
```bash
|
|
openshell status -g production
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
Check gateway registration details:
|
|
|
|
```bash
|
|
openshell gateway info
|
|
openshell status
|
|
```
|
|
|
|
For Helm deployments, inspect the release and gateway workload:
|
|
|
|
```bash
|
|
helm -n openshell status openshell
|
|
kubectl -n openshell get statefulset,pod,svc,pvc
|
|
kubectl -n openshell logs statefulset/openshell --tail=100
|
|
```
|