bug(helm): reject invalid gateway listener ports during rendering #5475

User Story

When configuring OpenShell gateway listeners through Helm, I need invalid port settings to fail with a clear error during rendering, so configuration mistakes can be corrected before Kubernetes rejects the resources or the gateway fails to start.

Problem Statement

The chart currently renders listener ports without a common check for integer values, TCP port ranges, and collisions. For example, service.port=65536 renders an invalid Kubernetes Service, and service.healthPort=8080 with the default gateway port renders two listeners on 0.0.0.0:8080.

PR #3179 implements early validation and regression tests. This issue records that PR's scope for the contributor acceptance process. It does not include introducing a new metrics enablement setting; that separate change is tracked in #5474.

Impact / Why This Matters

Operators receive errors at Kubernetes admission or gateway startup rather than a field-specific Helm rendering error. Invalid values can reach generated resources and gateway configuration even though they cannot produce the intended deployment.

Acceptance Criteria

• Gateway and health ports accept integer values from 1 through 65535.
• Metrics accepts integer values from 1 through 65535 and retains numeric 0 as the current disable sentinel.
• Boolean, fractional, malformed, negative, and out-of-range inputs fail during rendering with an actionable field-specific error.
• Enabled listener ports must be distinct.
• Default and valid custom configurations render as before.
• Numeric metricsPort 0 still omits the listener, container port, and Service port; metrics TLS still requires an enabled listener.
• Focused chart tests cover rejected inputs, range boundaries, collisions, and valid configurations.
• Document accepted port values and the change from previously tolerated boolean false to numeric 0; update relevant cluster-debugging guidance.

Reproduction Steps

Using the current chart without #3179:

1. Render an out-of-range gateway Service:

   helm template port-review deploy/helm/openshell --set agentSandbox.preflight.enabled=false --set service.port=65536 --show-only templates/service.yaml

   Observe a successful render containing port: 65536.
2. Render colliding gateway and health listener addresses:

   helm template port-review deploy/helm/openshell --set agentSandbox.preflight.enabled=false --set service.healthPort=8080 --show-only templates/gateway-config.yaml

   Observe both bind_address and health_bind_address set to 0.0.0.0:8080.

Scope Decision

Accept the localized validation in #3179 without adding oversized-integer overflow hardening. That edge case is outside this issue's required scope. Keep the separate metrics enable/disable setting in #5474.

Environment

• OpenShell checkout: 626feae7903fc39dabe4079c720e57acf026eecf.
• Reviewed PR fix(helm): validate gateway listener ports #3179 head: 62866fc.
• Helm: 4.2.0, macOS arm64.
• Validation: offline Helm rendering; no Kubernetes deployment required. Agent Sandbox preflight is disabled only for offline rendering.
• The PR diff applied to that checkout passes all 462 chart tests and Helm lint.

Suggested UX

Error: service.port must be between 1 and 65535.
Error: service.metricsPort must be 0 (disabled) or between 1 and 65535.
Error: service.port and service.healthPort must be different.

Context

• Implementation: fix(helm): validate gateway listener ports #3179.
• Separate metrics enablement follow-up: feat(helm): separate metrics enablement from the listener port #5474.