|
| 1 | +<!-- |
| 2 | +SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. |
| 3 | +SPDX-License-Identifier: Apache-2.0 |
| 4 | +--> |
| 5 | + |
| 6 | +# Sandbox application proxy |
| 7 | + |
| 8 | +`openshell-sandbox-proxy` is an optional consumer of the gateway service discovery |
| 9 | +API. It selects the exact discovered hostname from TLS SNI and forwards TLS bytes |
| 10 | +to the owning supervisor's app listener. Application certificates and private |
| 11 | +keys remain at supervisors. HTTP, WebSockets, application authentication, and |
| 12 | +sandbox policy remain enforced by the existing listener and application. |
| 13 | + |
| 14 | +```shell |
| 15 | +openshell-sandbox-proxy \ |
| 16 | + --gateway-endpoint https://gateway.example.com \ |
| 17 | + --workspace default \ |
| 18 | + --gateway-ca /run/discovery/ca.crt \ |
| 19 | + --discovery-token-file /run/discovery/token \ |
| 20 | + --listen-address 0.0.0.0:8443 |
| 21 | +``` |
| 22 | + |
| 23 | +Repeat `--workspace` for a finite set (up to 64 distinct names), or use |
| 24 | +`--all-workspaces` to include every active workspace, including future ones. |
| 25 | +These modes are mutually exclusive. For example: |
| 26 | + |
| 27 | +```shell |
| 28 | +openshell-sandbox-proxy --gateway-endpoint https://gateway.example.com \ |
| 29 | + --workspace team-a --workspace team-b \ |
| 30 | + --discovery-client-cert /run/discovery/tls.crt \ |
| 31 | + --discovery-client-key /run/discovery/tls.key --gateway-ca /run/discovery/ca.crt |
| 32 | +``` |
| 33 | + |
| 34 | +Use a discovery-only `OU=discovery` certificate with an administrator-managed |
| 35 | +fingerprint grant, or an existing identity authorized for the selection. Client mTLS can |
| 36 | +use `--discovery-client-cert` and `--discovery-client-key`. Credentials and CA |
| 37 | +files reload on reconnect. The gateway must authorize every selected workspace; |
| 38 | +a finite grant cannot request platform scope. Unauthorized selections fail as a |
| 39 | +whole. All-workspaces output is bounded by the gateway's 64-workspace scan and |
| 40 | +shared route/byte limits. The proxy does not require operator credentials. Plaintext |
| 41 | +credential-free loopback development requires `--allow-insecure-gateway`. |
| 42 | + |
| 43 | +A snapshot initializes the cache and bounded watches replace it. Reconnects |
| 44 | +relist; transient errors retain routes only until their published expiry. |
| 45 | +Authorization/configuration/data-integrity failures clear the cache. Monotonic |
| 46 | +local deadlines are derived from absolute expiries and capped at fifteen seconds; |
| 47 | +operators must synchronize gateway and proxy clocks. Snapshot revisions are |
| 48 | +opaque and installation versions identify replacement independently of renewal. |
| 49 | + |
| 50 | +Only exact, current routes can dial a backend. A route withdrawal, installation |
| 51 | +replacement, or expiry closes affected TCP streams; renewal preserves them. |
| 52 | +There is no gateway payload fallback, wildcard route fallback, or caller-selected |
| 53 | +backend. Limits are 4,096 cached routes, 1,024 concurrent connections, 64 per |
| 54 | +hostname, a 64 KiB ClientHello, and five-second hello/connect/setup deadlines. |
| 55 | +Each relay uses Tokio's bounded bidirectional copy buffers. ClientHello parsing |
| 56 | +is dependency-owned rustls protocol parsing, not a first-party cryptographic |
| 57 | +operation. Authenticated discovery transport uses the shared SDK/crypto facade. |
| 58 | + |
| 59 | +The health listener defaults to port 9091: `/healthz` is process liveness, |
| 60 | +`/readyz` reflects discovery availability, and `/metrics` exposes connection |
| 61 | +counts. During transient discovery failures readiness fails while existing |
| 62 | +unexpired connections can continue. Expiry still closes streams independently |
| 63 | +of the discovery connection. Multiple replicas keep independent caches and need |
| 64 | +no Kubernetes ownership or leader election. |
| 65 | + |
| 66 | +Build with `mise run docker:build:sandbox-proxy`. The standalone Helm chart at |
| 67 | +`deploy/helm/openshell-sandbox-proxy` mounts only discovery identity/trust Secrets; |
| 68 | +it needs no Kubernetes API permissions. Configure NetworkPolicy to allow the |
| 69 | +proxy to reach the gateway API and discovered supervisor app endpoints, and |
| 70 | +restrict supervisor ingress where edge authentication is required. The proxy |
| 71 | +never authenticates application users using its discovery identity. |
| 72 | + |
| 73 | +For Gateway API TLS passthrough, attach a TLSRoute to a Gateway listener in |
| 74 | +`Passthrough` mode and target the proxy Service on port 443. Application TLS |
| 75 | +terminates at the supervisor. An HTTPRoute requires a separate edge termination |
| 76 | +and backend-TLS contract. A controller can instead consume the same discovery |
| 77 | +API and reconcile exact-host routes directly to supervisor endpoints; it does |
| 78 | +not need this proxy. |
| 79 | + |
| 80 | +## Verification |
| 81 | + |
| 82 | +```shell |
| 83 | +cargo test -p openshell-sandbox-proxy |
| 84 | +cargo clippy -p openshell-sandbox-proxy --all-targets -- -D warnings |
| 85 | +helm lint deploy/helm/openshell-sandbox-proxy \ |
| 86 | + --set gatewayEndpoint=https://gateway.example.com --set workspace=default |
| 87 | +``` |
| 88 | + |
| 89 | +Kubernetes discovery resolves dedicated supervisors and acknowledged shared-pool |
| 90 | +owners. During HA takeover the proxy withdraws the old installation and connects |
| 91 | +to the new owner after it advertises an accepted installation. Existing streams |
| 92 | +may close; clients reconnect without restarting the sandbox. Readable and hashed |
| 93 | +hostnames use the same discovery path. The proxy consumes returned hostnames |
| 94 | +and never reconstructs them or needs the gateway's hashing configuration. |
0 commit comments