Repository navigation
feat(services): publish authoritative application origins - #4956
TaylorMutch wants to merge 7 commits into
Conversation
|
Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually. Contributors can view more details about this message here. |
|
🌿 Preview your docs: https://nvidia-preview-pr-4956.docs.buildwithfern.com/openshell |
a6d0833 to
e6e1927
Compare
932643d to
6c83b66
Compare
e6e1927 to
2574b9a
Compare
6c83b66 to
755e4d1
Compare
70e365e to
30cf9ce
Compare
0944ea2 to
8504067
Compare
30cf9ce to
6b2fe9c
Compare
8504067 to
feac6b4
Compare
dae4a9d to
66220a7
Compare
0939a70 to
cf5448a
Compare
66220a7 to
3dc01d7
Compare
13b6cb8 to
5baafd6
Compare
Compatibility review (advisory)New or updated breaking changes; see the full report for all findings. 4. typescript-sdk — No explicit risk acceptance foundPreviously valid literals now lack required applicationServiceUrls/gatewayServiceUrls on SandboxRef and raw SandboxResponse, applicationUrl/gatewayUrl on raw ServiceEndpointResponse, or applicationHostname on raw SandboxServiceRoute.
Review details
Advisory review; publication gates are unchanged. |
15f0afb to
6903eaa
Compare
316dd66 to
fd8af36
Compare
6903eaa to
433b9b9
Compare
Compatibility review (advisory)New or updated breaking changes; see the full report for all findings. 3. api-behavior — No explicit risk acceptance foundExposeService.url and CreateSandbox.service_urls replays now recompute current origins instead of returning their recorded URL values.
Review details
Advisory review; publication gates are unchanged. |
433b9b9 to
35e2d05
Compare
fd8af36 to
29c0d05
Compare
Signed-off-by: Taylor Mutch <taylormutch@gmail.com>
Signed-off-by: Taylor Mutch <taylormutch@gmail.com>
Signed-off-by: Taylor Mutch <taylormutch@gmail.com>
35e2d05 to
c503a94
Compare
Signed-off-by: Taylor Mutch <taylormutch@gmail.com>
Compatibility review (advisory)New or updated breaking changes; see the full report for all findings. 3. typescript-sdk — No explicit risk acceptance foundGenerated raw SandboxResponse, ServiceEndpointResponse, and SandboxServiceRoute types acquire required URL-map, URL, and applicationHostname properties absent from previously valid complete objects.
Review details
Advisory review; publication gates are unchanged. |
Signed-off-by: Taylor Mutch <taylormutch@gmail.com>
Signed-off-by: Taylor Mutch <taylormutch@gmail.com>
Signed-off-by: Taylor Mutch <taylormutch@gmail.com>
Summary
Publish authoritative application URLs from the configured supervisor application origin, independently of the gateway API origin. Return explicit application and gateway URLs so clients can choose an access path. Allow installations to disable gateway-mediated application routing independently.
Based on main at
bf9f55cdf.Related Issue
Closes #4953. Part of RFC 0017.
Changes
[openshell.gateway].service_routing_enabled(defaulttrue). Setting it tofalseomits gateway URLs and returns404for gateway application HTTP/WebSocket traffic, while keeping control-plane APIs, app listeners, and discovery available.urlandservice_urlsvalues on idempotent retries; refresh only explicit application/gateway fields. Keep the new curated TypeScript URL maps optional.Configuration
Gateway routing is enabled by default. Disable it independently of the app listener using any of these equivalent settings:
[openshell.gateway]→service_routing_enabled = false--service-routing-enabled=falseOPENSHELL_SERVICE_ROUTING_ENABLED=falsegatewayConfig."openshell.gateway".service_routing_enabled: falsePrecedence is CLI > environment > TOML > default. Explicit
trueandfalseoverrides are supported.Example: publish only application-ingress URLs, with hashed hostnames:
namesupplies the stable installation identity for hashed names.service_hostname_formatdefaults to"readable"and applies to both ingress paths. The applicationpublic_urlis an HTTPS origin matchingdomain; its public port can differ from the listener port. DNS, certificates, and ingress are provisioned separately.For the routing opt-out alone in Helm:
Integrator perspective
The service API tells clients which public URL to use; discovery tells routers where to send requests.
public_urlfor your public ingress. Responses exposeapplication_url,gateway_urlwhen gateway routing is enabled, and a preferredurlthat selects the application URL when configured.Publishing a URL does not create DNS or ingress resources, or establish reachability. Both ingress paths use
[openshell.gateway].service_hostname_format; the app listener has no separate naming mode. Keeping the installation name and public HTTPS domain/port unchanged preserves the service URL when switching ingress.Public URL selection
This PR publishes the configured application origin alongside the gateway-mediated URL when enabled. The example uses gateway installation
gateway-a, workspacedefault, sandboxmy-sandbox, and serviceweb.flowchart TD I["Service identity<br/>gateway-a / default / my-sandbox / web"] M["One gateway setting: service_hostname_format<br/>readable or hashed"] I --> L["Shared service label generator<br/>Hashed example: enh47uqyj7bpyttz"] M --> L E["service_routing_enabled<br/>Default: true"] --> G L --> G["gateway_url<br/>https://enh47uqyj7bpyttz.gateway.example.com/"] L --> A["application_url<br/>https://enh47uqyj7bpyttz.apps.example.com/"] O["Configured application public origin<br/>https://apps.example.com"] --> A A -->|"Preferred when configured"| U["url returned to clients"] G -->|"Fallback when application_url is absent"| USet
service_routing_enabled = falseto use application ingress without advertising or serving gateway-mediated application URLs. The CLI/env equivalents are--service-routing-enabled=falseandOPENSHELL_SERVICE_ROUTING_ENABLED=false; Helm usesgatewayConfig."openshell.gateway".service_routing_enabled: false.urlgateway_urlDisabling routing also makes
gateway_service_urlsempty. Recorded preferred URLs stay unchanged on idempotent retries; explicit URL fields reflect current configuration.Hashed mode is shown above. Readable mode uses
<workspace>--<sandbox>[--<service>]for both paths. The two access paths are alternatives; when their public origins match, their complete URLs match. Integrators consume discovery hostnames as returned.Connecting the published URL to a sandbox
The proxy and example controller below are alternative discovery consumers, shown for context. This PR publishes URLs; it does not deploy either integration. Dashed arrows configure routing; solid arrows carry application traffic.
flowchart TD API["Service API<br/>Returns public application URL"] -.->|"URL used by client"| Client["Application client"] D["Discovery API<br/>Exact hostname → current supervisor Pod IP:port<br/>Installation identity and expiry"] D -.->|"Snapshots / watches"| P["Sandbox proxy<br/>TLS passthrough"] D -.->|"Snapshots / watches"| C["Example Kubernetes HTTPRoute controller<br/>Separate POC"] C -.->|"Reconciles HTTPRoutes, backend resources<br/>and backend TLS configuration"| K["Kubernetes Gateway<br/>Edge TLS termination"] Client -->|"Option A: HTTPS to published hostname"| P Client -->|"Option B: HTTPS to published hostname"| K P -->|"Application TLS forwarded unchanged"| S["Owning supervisor<br/>Application TLS listener"] K -->|"HTTPS to discovered endpoint<br/>Preserve application Host and backend SNI"| S S --> W["Declared service inside sandbox"]Both paths keep application traffic out of the OpenShell gateway. The integrator provides DNS, certificates, and ingress configuration; discovery supplies backend changes and withdrawal/expiry information.
Release Notes
Compatibility context
Supervisor route declarations are explicitly an internal, version-locked deployment protocol. Discovery and canonical hostname publication are being introduced in this stack; no released discovery hostname API needs a migration. The existing readable listener aliases remain supported.
Protobuf additions remain additive on the wire. Curated SDK callers retain their existing construction paths; new TypeScript URL maps are optional. Hand-written exhaustive generated Rust/TypeScript message literals must include new fields or use generated/default initialization; preserving those literal shapes is outside this change's migration scope.
Python SDK changes are deferred to the external SDK repository; this PR leaves the frozen core SDK files unchanged.
Testing
Startup logging: all eight app-listener/gateway-routing/service-auth combinations verified against the real gateway binary, with strict server Clippy and formatting checks. Full chart checks passed after correcting canonical routing/auth Helm examples and tests.
Standalone URL stage: 2,736 server tests and 36 core configuration tests passed, with strict server Clippy and full Helm tests. Added URL-selection/replay matrices, readable/hashed discovery independence, HTTP/WebSocket rejection, and real-listener control-plane availability checks.
Gateway routing opt-out validation: 2,767 combined-stack server tests passed (43 PostgreSQL-dependent tests skipped), all nine proxy tests passed, and strict all-target server/proxy Clippy passed. Full Helm tests, Markdown lint, Rust formatting, and whitespace checks passed.
Previous validation on main
e8ba30fde: standalone discovery passed 2,725 server tests (42 PostgreSQL-dependent tests skipped locally).Combined stack passed 2,761 server tests (43 PostgreSQL-dependent tests skipped), nine proxy tests, and 19 supervisor listener regressions. Strict all-target server/supervisor/proxy Clippy passed.
TypeScript SDK validation passed: protobuf generation/lint, lint, type checking, 207 tests, coverage, and build.
Helm lint and all three chart unit suites passed, including gateway TOML parsing, resource coherence, ownership, and supervisor scaling checks. Markdown lint and Rust formatting passed.
Compatibility regressions cover recorded replay URLs across origin/port changes and disabled ingress, existing TypeScript object shapes, auth-disabled loopback schemes, application-cookie preservation, and real-TLS discovery-certificate opt-in behavior.
Earlier local k3d validation covered dedicated/shared owner changes, HTTP/WebSockets, network-policy isolation, discovery withdrawal, and two proxy replicas. This revision has no new live-cluster or production-load qualification. New-head CI is pending.
Qualification limits
Live HA validation exercised supervisor process/Pod loss on a local k3d cluster. Whole-node failure, real network partitions, metric-driven HPA, sustained production load, and published release artifacts remain unqualified. Grant-file projection contributes to revocation propagation time. Both ingress paths now share the gateway hostname format and label generator. The same installation identity and public HTTPS domain/port preserve service URLs when switching ingress. Installation-status presentation (#4670) remains separate work. Live Kubernetes runs above preceded hostname integration; the naming and shutdown-fence integration is validated by focused Rust regressions.
The example Kubernetes HTTPRoute controller is a deferred compatibility POC outside this stack.
Checklist
PR dependency order: #4956 → #4963 → #4964 → #4957.