Repository navigation
feat(services): publish authoritative application origins - #4956
TaylorMutch wants to merge 8 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
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
35e2d05 to
c503a94
Compare
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>
Signed-off-by: Taylor Mutch <taylormutch@gmail.com>
Signed-off-by: Taylor Mutch <taylormutch@gmail.com>
Signed-off-by: Taylor Mutch <taylormutch@gmail.com>
Signed-off-by: Taylor Mutch <taylormutch@gmail.com>
Signed-off-by: Taylor Mutch <taylormutch@gmail.com>
Compatibility review (advisory)New or updated breaking changes; see the full report for all findings. 1. configuration — No explicit risk acceptance foundApp-listener TOML
2. api-behavior — No explicit risk acceptance found
Review details
Advisory review; publication gates are unchanged. |
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
9f3c9560d.Related Issue
Closes #4953. Part of RFC 0017.
Changes
supervisor.app_listener.base_urlas the single authored application origin and derive its service domain. Enabled listeners require an HTTPS DNS base URL; remove the previousdomain/public_urlfields. The supervisor listener port stays independent of the public URL port.[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:
base_urlsupplies the hostname suffix under which service DNS records are created. The listener derives its domain from that URL.namesupplies the stable installation identity for hashed names.service_hostname_formatdefaults to"readable"and applies to both ingress paths. The applicationbase_urlis an HTTPS origin whose hostname determines the service domain; 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.
base_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
Enabled application listeners now require
base_urlin place ofdomainand optionalpublic_url. Remove those old keys when upgrading and deploy matching gateway/supervisor images. The domain is derived from the HTTPS base URL; its public port remains separate from the supervisor listener port.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
9f3c9560d; standalone URL runtime passed 2,772 server tests (45 PostgreSQL-dependent tests skipped), 652 core tests, 336 Kubernetes-driver tests, and 300 supervisor tests.base_url.Live tests exercised supervisor Pod-IP routing with Host/SNI, rather than public DNS or an external ingress controller. New-head CI is pending.
Qualification limits
Live Kubernetes qualification covers dedicated/shared supervisors, graceful shared-owner replacement, gateway outage, and policy isolation. Hashed URL/public-port behavior is covered by unit tests. Whole-node failure, real network partitions, metric-driven HPA, sustained production load, external ingress/DNS automation, and published release artifacts remain unqualified. Installation-status presentation (#4670) remains separate work. The example Kubernetes HTTPRoute controller remains a separate compatibility POC.
Checklist
PR dependency order: #4956 → #4963 → #4964 → #4957.