[cv]

Draft pending maintainer acceptance of #5500 (state:accepted); the PR Issue Acceptance check is expected to fail until then.

Summary

The chart's gateway Service accepts service.type but nothing a cloud load balancer usually needs. This adds Service annotations, loadBalancerClass and loadBalancerSourceRanges, and a Service port separate from the gateway's listening port, so a LoadBalancer can listen on 443 while the gateway keeps listening on 8080. With the new values unset, the chart renders the same manifests as before.

Related Issue

Closes #5500

Changes

• service.annotations (map): rendered on the gateway Service only when non-empty.
• service.loadBalancerClass (string) and service.loadBalancerSourceRanges (list): rendered only when set. Each requires service.type=LoadBalancer; the chart fails rendering otherwise, rather than silently dropping a source restriction.
• service.servicePort (int, default null): the port the gateway Service exposes. Null exposes service.port. The Service keeps targetPort: grpc, the gateway's service.port container port.
  • Follow the Service port: the derived Kubernetes driver grpc_endpoint (sandboxes dial the Service's DNS name) and the GRPCRoute's backend for the gateway Service.
  • Keep service.port: bind_address, the container port, OPENSHELL_PEER_ENDPOINT, and the peer and per-replica Services and their GRPCRoute replica backends, which address pods directly. The OpenShift Route targets the named grpc port and is unaffected. Certificate SANs carry no port.
  • Validation: an integer from 1 to 65535, and different from service.metricsPort while metrics are enabled, since the Service exposes both.
• Docs: a "Publish the Gateway Service as a LoadBalancer" section in docs/kubernetes/ingress.mdx, the regenerated chart README, and a note in the debug-openshell-cluster skill. The section covers:
  • Source ranges don't cover node ports.
  • loadBalancerClass can't change once set.
  • A LoadBalancer also publishes the plaintext metrics port; the example sets metrics.enabled: false.
  • The built-in certificate hook writes its Secrets only at first install, so add the external name then or use cert-manager.
  • Changing servicePort strands existing sandboxes.

Some history behind the port split: NemoClaw first published its managed gateway on a load balancer's port by moving the gateway's listening port to it, then reverted that. The gateway API's service URLs carry its listen port (service_routing::endpoint_url uses bind_address.port()), and a gateway without privileges can't listen on 443. This PR doesn't move the listening port. It adds a Service-only port, so bind_address, the health and metrics listeners, and the API's service URLs stay as they are. The CLI already rewrites printed service URLs to the registered endpoint's port (service_url_for_gateway), and routing ignores the Host port. The docs say the API reports service.port, the CLI rewrites it, and that opening service URLs remotely needs a wildcard SAN for the service domain plus wildcard DNS pointing at the load balancer.

NemoClaw (NVIDIA/NemoClaw#14421) would use these values to publish its managed gateway as a LoadBalancer through the chart instead of declaring a second Service outside it.

Release Notes

The Helm chart's gateway Service accepts service.annotations, service.loadBalancerClass and service.loadBalancerSourceRanges, and service.servicePort publishes the Service on a port other than the gateway's listening port, such as a LoadBalancer on 443.

Testing

• Checks appropriate to the affected code and behavior pass
  • helm lint and helm template with defaults and every ci/values-*.yaml, plus the workspace chart (the helm:lint steps): pass.
  • helm-docs --dry-run matches both READMEs (helm:docs:check): pass.
  • helm unittest for both charts: 489 and 7 tests pass. test-split-ownership.sh, test-gateway-resource-coherence.sh and test-supervisor-pool-scaling.sh: pass.
  • Defaults unchanged: rendered every ci/values-*.yaml file, the defaults, GRPCRoute, replica routing, NodePort with nodePort, LoadBalancer, and service.port=9443 on main and on this branch. All 33 renders are identical apart from the randomly generated key-encryption key.
  • markdownlint-cli2 on the changed docs, the SPDX header check, check_docs_nav.py and fern check: pass. fern check shows the same 3 warnings as main.
• Unit tests added/updated (if applicable): tests/gateway_service_test.yaml covers the unchanged default Service, annotations, the LoadBalancer class and source ranges, the port split for LoadBalancer (Service port, target, container port, bind_address, grpc_endpoint, peer Service, GRPCRoute) and for NodePort with a fixed nodePort, and the validation failures. It also checks that the metrics port stays on the Service, and that with replica routing the per-replica GRPCRoute backends keep 8080 while the main backend uses 443. tests/supervisor_test.yaml checks that the shared supervisor's --gateway-endpoint follows servicePort. Changing the expected values makes these tests fail.
• E2E tests added/updated (if applicable)

Not verified:

• I didn't install this on a cluster. Nothing ran against a cloud or MetalLB load balancer, and no Kubernetes e2e lane ran.
• test-gateway-config-parser.sh didn't run because it builds the gateway with cargo. The gateway.toml it validates renders byte-identical to main for its fixture.
• From reading the code: sandbox pods receive the callback endpoint as OPENSHELL_ENDPOINT when they're created, so after a service.servicePort change on a live release, existing sandboxes can't reach the gateway until they're recreated. The shared supervisor Deployment rolls out, because its --gateway-endpoint argument changes. I haven't verified either on a cluster. The same holds for service.port today. The docs say to set it before creating sandboxes.
• Re-issuing certificates on an existing release by deleting the PKI Secrets, as the docs describe, wasn't run. It follows from the certgen hook's skip/create/partial-state logic.

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)
• Architecture docs updated (if applicable)

[copy-pr-bot]

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.