feat(helm): separate metrics enablement from the listener port #5474

User Story

When configuring OpenShell gateway metrics through Helm, I need enabling or disabling the metrics listener to be independent of choosing its TCP port, so the configuration expresses those two decisions separately.

Problem Statement

The chart currently uses service.metricsPort both as a port number and as an enable/disable switch. Its default is 9090. Numeric 0 disables metrics, and boolean false also disables metrics because the templates test the value's truthiness.

PR #3179 validates listener port values and rejects boolean input while retaining numeric 0 as the disable value. This issue is a separate follow-up to move metrics enablement to an explicit boolean setting; it does not require adding that behavior to #3179.

Impact / Why This Matters

Operators currently change the port value to disable the endpoint, losing the configured port and mixing enablement with port validation. Re-enabling metrics requires restoring a port rather than toggling an explicit setting. The truthiness-based behavior also accepts a boolean in a field documented as an integer.

Proposed Design

Add an explicit Helm setting, proposed as metrics.enabled, defaulting to true to preserve the current default deployment. Keep service.metricsPort numeric, defaulting to 9090, with its role limited to selecting the listener port.

When metrics are disabled, omit the dedicated metrics listener and its container and Service ports while retaining the configured port value for future re-enablement. When enabled, use that port consistently. This setting controls the gateway's dedicated Prometheus endpoint, not OpenTelemetry export or unrelated instrumentation.

Preserve a clear validation rule for metrics TLS: requesting metrics TLS while the endpoint is disabled must produce an actionable configuration error.

Define and document migration from legacy service.metricsPort: 0 and any previously supported false input. Specify precedence or an explicit validation error for conflicting legacy and new settings. Do not silently enable metrics for a deployment that previously disabled it.

Suggested UX

Enabled by default:

metrics:
  enabled: true

service:
  metricsPort: 9090

Disable the endpoint while retaining the chosen port:

metrics:
  enabled: false

service:
  metricsPort: 9090

Acceptance Criteria

• Metrics remain enabled on port 9090 with default chart values.
• An explicit boolean setting controls metrics enablement independently of the numeric port setting.
• Disabling metrics omits the runtime metrics listener, container port, and Service port; gateway and health listeners remain operational.
• Re-enabling metrics uses the retained configured port.
• Enabled metrics enforce a valid TCP port and reject listener collisions.
• Metrics TLS with disabled metrics fails with a clear error.
• Legacy disable values and conflicting settings have an explicit, documented migration and validation policy that avoids silently enabling previously disabled endpoints.
• Focused chart tests cover defaults, enable/disable behavior, custom ports, TLS conflicts, and migration cases.
• Update chart values documentation, the chart README, docs/how-it-works/gateways/configuration.mdx, and relevant cluster-debugging/contributor skill guidance.

Alternatives Considered

• Keep 0 as the permanent disable sentinel: preserves the current interface but continues coupling enablement and port selection.
• Accept false in the port field: preserves accidental truthiness-based behavior but retains mixed types in a numeric field.
• Middleware, interceptors, and credential providers do not control the chart's gateway listener and Service exposure.

Context

• Follow-up to fix(helm): validate gateway listener ports #3179.
• The chart currently gates listener rendering in deploy/helm/openshell/templates/_toml.tpl, container port rendering in _gateway-workload.tpl, and Service port rendering in service.yaml on service.metricsPort.
• Existing metrics TLS validation already rejects a disabled metrics endpoint.