fix(helpers): make backendRef port optional in HTTPRoute rules

[alex1989hu]

The HTTPRoute backendRefs template required .port on every backendRef and failed the render if it was missing, but per the Gateway API spec port is optional on a BackendRef in general. It is only required when the referent is a core Kubernetes Service.

What changed

• port is validated and rendered only when it is actually set, and left out of the manifest entirely when omitted (e.g. for kind: ServiceImport backends).
• Per the Gateway API spec, omitting port when the referent is a core Kubernetes Service (group: "" and kind: Service, the default) still fails the render, now with an explicit message: backendRef "<name>": port is required when the referent is a Kubernetes Service.
• A templated port that renders to an empty string (e.g. port: '{{ .Values.optionalPort }}' with the value unset) is treated as unset, so the optionality also works with template expressions.
• The port documentation in values.yaml, README, and values.schema.json now states when the field may be omitted.

Note on the issue repro

The exact reproduction in #602 (no port, kind defaulting to Service) still fails by design, because the Gateway API spec requires port for Service referents and the HTTPRoute CRD would reject the manifest anyway. The difference is that the failure message now explains the actual constraint instead of Invalid port value: 0. Backends of any other kind render without a port as the issue expects.

Tests

Unit tests cover: port omitted for a non-Service kind (rendered without port), port omitted for a Service (explicit failure), empty templated port for both cases, out-of-range and explicit-zero ports, mixed rules where only some backendRefs have a port, and a Service in a non-core group (port optional).

Closes #602

[aslafy-z]

Thank you for your contribution @alex1989hu, please review my comment:

The new test case is not valid according to the Gateway API specification.

It defines:

backendRefs:
  - name: example-service

Because neither group nor kind is specified, Gateway API infers the core API group and defaults kind to Service. This backendRef therefore refers to a Kubernetes Service, for which port is required:

https://gateway-api.sigs.k8s.io/reference/api-spec/main/spec/#:~:text=Port%20is%20required%20when%20the%20referent%20is%20a%20Kubernetes%20Service.

The chart does support explicit non-Service backends through the group and kind fields, but that is not what this test exercises.

As written, the PR allows an invalid Service backendRef to render successfully. I think the test should continue to require a port for the default Service case. Port omission should only be accepted when group or kind explicitly identifies a non-Service backend.

[alex1989hu]

Do I understand correctly that you'd like to enforce the port field if the kind is omitted or set as Service ?

[aslafy-z]

@alex1989hu I feel like it's the more correct thing to do, what do you think?

[alex1989hu]

@alex1989hu I feel like it's the more correct thing to do, what do you think?

I'm okay with that change. I've just pushed a commit 5f9dd47 , could you please take a look?

[aslafy-z]

Thanks, the Service/default-kind case is now handled correctly.

One remaining issue: if .port checks truthiness rather than whether the field was provided. For example, port: 0 is falsey, so it bypasses the range validation. For a non-Service backend it would be silently omitted, while for a Service it would produce the less accurate "port is required" error.

Could we use kindIs "invalid" to distinguish an absent/null value from an explicitly provided falsey value, and reuse the same gate when rendering?

{{- $group := .group | default "" }}
{{- $kind := .kind | default "Service" }}
{{- $hasPort := not (kindIs "invalid" .port) }}
{{- $isKubernetesService := and (eq $group "") (eq $kind "Service") }}
{{- $portVal := 0 }}

{{- if $hasPort }}
  {{- $portVal = .port | int }}
  {{- if or (lt $portVal 1) (gt $portVal 65535) }}
    {{- fail (printf "Invalid port value: %v. Port must be between 1 and 65535" .port) }}
  {{- end }}
{{- else if $isKubernetesService }}
  {{- fail (printf "backendRef %q: port is required when the referent is a Kubernetes Service" .name) }}
{{- end }}

Then use $hasPort instead of if .port when rendering the field.

The group check also avoids treating a custom resource such as group: example.io, kind: Service as a Kubernetes Service.

[alex1989hu]

Thanks, the Service/default-kind case is now handled correctly.

One remaining issue: if .port checks truthiness rather than whether the field was provided. For example, port: 0 is falsey, so it bypasses the range validation. For a non-Service backend it would be silently omitted, while for a Service it would produce the less accurate "port is required" error.

Could we use kindIs "invalid" to distinguish an absent/null value from an explicitly provided falsey value, and reuse the same gate when rendering?

{{- $group := .group | default "" }}
{{- $kind := .kind | default "Service" }}
{{- $hasPort := not (kindIs "invalid" .port) }}
{{- $isKubernetesService := and (eq $group "") (eq $kind "Service") }}
{{- $portVal := 0 }}

{{- if $hasPort }}
  {{- $portVal = .port | int }}
  {{- if or (lt $portVal 1) (gt $portVal 65535) }}
    {{- fail (printf "Invalid port value: %v. Port must be between 1 and 65535" .port) }}
  {{- end }}
{{- else if $isKubernetesService }}
  {{- fail (printf "backendRef %q: port is required when the referent is a Kubernetes Service" .name) }}
{{- end }}

Then use $hasPort instead of if .port when rendering the field.

The group check also avoids treating a custom resource such as group: example.io, kind: Service as a Kubernetes Service.

Good catch, thank you! I copied your proposal and added two tests in 8a06504

[aslafy-z]

Thanks for the fix @alex1989hu!

I pushed a few additions on top of your commits before merging:

• A templated port that renders empty (e.g. port: '{{ .Values.optionalPort }}' with the value unset) is now treated as unset too, so the optionality composes with template expressions like the chart's own defaults use.
• The render guard now reuses the same presence check as the validation, instead of a separate truthiness test.
• Documented the "required for Service referents, optional otherwise" rule in values.yaml (README and schema regenerated).
• Tidied the new tests a bit (dropped a few duplicate cases) and added coverage for a Service in a non-core group.

Also rebased onto main. Merged, thanks again for the contribution!