feat: Gateway-API as an alternative to the Ingress in five annotation charts

Group 2 of the #114 sweep: the charts whose behaviour hangs off an nginx annotation - calibre-web-automated, outline, paperless-ngx, zipline (proxy-body-size) and freesailarr (rewrite-target). Each gets the form the pilot (cyberchef, PR #115) fixed and group 1 (PR #116) repeated: an httpRoute block off by default, a template rendering ONLY an HTTPRoute with parentRefs - no Gateway, no gatewayClassName, no Certificate, no implementation-specific policy object - render aborts on both modes at once (naming both value paths), on an empty parentRefs and on a missing hostname, empty hostnames meaning [ingress.domain], a schema entry closed against unknown keys with an open parentRef definition, and a NOTES.txt that names the active mode and what the mode costs. Minor, additive, defaults unchanged: `helm template` with each chart's CI values is byte-identical to origin/main for all five. The upload limit is DOCUMENTED, not rebuilt (decision 2 of the issue). The Gateway API knows no body size; a policy object would bind the chart to one implementation. So the Gateway branch of NOTES.txt says, per chart and in the chart's own terms, that the value is NOT ENFORCED and names where to set it: an e-book library (calibre), an upload service (zipline), the web-UI half of the document intake while the consume directory keeps no limit at all (paperless), and the open #12 pair (outline). Four findings that were not in the plan, each argued in the file it changes: freesailarr gated freesailarr.sharedIngressApps on ingress.enabled, and that list is read by the <APP>__SERVER__URLBASE variables as well as by the routing objects. In Gateway mode it would have come out EMPTY while the route served radarr, sonarr and prowlarr under their prefixes: UrlBase unset, assets and API calls linked at the host root, broken UI behind a Ready pod. The helper's two guards (seerr/mediathekarr only at "/", no duplicate paths) would have gone unenforced there too. Fixed with freesailarr.published (ingress.enabled OR httpRoute.enabled) - the same shape as sure.publishedOverTls in group 1, and identical to ingress.enabled while httpRoute.enabled is false. Measured: on origin/main with ingress.enabled: false the render emits ZERO URLBASE variables; with this change in Gateway mode it emits three. paperless-ngx was the last chart in the repository rendering its Ingress UNCONDITIONALLY. Without an ingress.enabled switch there is no second value path for the mutual-exclusion abort to name, and the Ingress plus its unconditional required() on clusterIssuer would have kept rendering in Gateway mode - a value demanded for nothing, which is issue #114's "Folge 1" and README guideline 12. The switch was added, defaulting to true, so the render is unchanged. paperless-ngx PAPERLESS_URL had no required() of its own: it relied on the Ingress template's, which stops firing the moment the Ingress is switchable. With httpRoute.hostnames set and ingress.domain empty it would have rendered "https://" and refused every login POST as a CSRF failure. It now carries its own required(), naming what the value is for. calibre-web-automated claimed, in values.yaml and in its schema, that ingress.domain is read nowhere but in the Ingress template. The HTTPRoute reads it, so the claim now holds only while both modes are off. Corrected rather than left standing - the same correction garage needed in group 1. freesailarr is where the Gateway API is LESS machinery than what it replaces, not a translation of it. rewrite-target applies per Ingress OBJECT, so qBittorrent (no base path, prefix must be stripped) needed a second Ingress on the shared host, which then had to repeat the first object's TLS secret name, omit the cert-manager annotation conditionally so only one Certificate is requested, and match an ImplementationSpecific regex path for the rewrite's capture group. A URLRewrite filter applies per RULE: one route, one rule per app, the filter on qBittorrent's rule, a plain PathPrefix. All four crutches gone. It is also the only chart without httpRoute.hostnames - it has no ingress.domain either, and a chart-global hostname list could not say which of the ten apps it belonged to, so the hostnames stay in ingress.host and <app>.ingress.host. CI: one render overlay per chart under ci/httproute/, so the assertion is not vacuum-green - ci/run-httproute-match-test.sh goes from 20 held assertions over 10 charts to 36 over 15. freesailarr's overlay moves bazarr onto a host of its own, so the shared-host route AND the per-app route are both rendered; without that the per-app branch would be exercised by nothing. The install-test fixtures stay in Ingress mode: the install runs one configuration per chart, cyberchef already pays that price against the real Gateway-API CRDs, and for paperless-ngx that fixture is the only install of the valkey-subchart path anywhere. README also carries a stale figure fixed here: the HTTPRoute test was still documented at the pilot's 4 assertions over 2 charts, although group 1 had taken it to 20 over 10. Not proven, by construction: that traffic flows. No Gateway controller runs in CI. Not run locally either: k3d, Docker, Trivy. The Gateway branch of NOTES.txt is EXECUTED by the render test (a template error in it fails the job, verified) but its text is printed by no pipeline stage - helm template does not emit notes, and the install-test installs in Ingress mode. Part of #114
2026-10-12 18:15:29 +00:00
1 parent 33d7cedbab
commit bd1fdc09a0
@@ -5,7 +5,7 @@ name: calibre-web-automated
 description: A Helm chart to deploy calibere-web-automated
 icon: https://raw.githubusercontent.com/crocodilestick/Calibre-Web-Automated/main/README_images/cwa-logo-round-dark.png

-version: 7.0.1+upv4.0.6
+version: 7.1.0+upv4.0.6
 appVersion: v4.0.6

 maintainers:
@@ -2,11 +2,16 @@
 {{- $startup := fromYaml (include "calibre-web-automated.startupProbe" .Values.cwa.startupProbe) -}}
 {{- $sfs := printf "%s-%s-sfs" .Release.Name .Chart.Name -}}
 {{- $pod := printf "%s-0" $sfs -}}
+{{- $httpRoute := .Values.httpRoute | default dict -}}
+{{- $hostnames := $httpRoute.hostnames | default list -}}
+{{- if not $hostnames -}}
+{{- $hostnames = list .Values.ingress.domain -}}
+{{- end -}}
 Calibre-Web Automated {{ .Chart.AppVersion }} — release {{ .Release.Name }} in namespace {{ .Release.Namespace }}.

 {{- if .Values.ingress.enabled }}

-ACCESS
+ACCESS — INGRESS MODE (ingress.enabled: true, httpRoute.enabled: false)
  https://{{ .Values.ingress.domain }}

  The certificate is requested by cert-manager through the "{{ .Values.ingress.clusterIssuer }}"
@@ -20,12 +25,59 @@ ACCESS
  controller before CWA ever sees it, so nothing about it reaches the app log.
  Both annotations are understood by the nginx-family controllers only, and this
  release uses ingressClassName "{{ .Values.ingress.className }}".
+{{- else if $httpRoute.enabled }}
+
+ACCESS — GATEWAY MODE (httpRoute.enabled: true, ingress.enabled: false)
+{{- range $hostnames }}
+  https://{{ . }}
+{{- end }}
+
+  This release renders an HTTPRoute ({{ .Release.Name }}-{{ .Chart.Name }}-httproute) and NOTHING
+  else of the routing path — no Gateway, no class, no Certificate. Three things
+  therefore belong to the cluster and not to this chart, and if any is missing
+  the address above does not answer:
+
+    1. The Gateway-API CRDs. Without them this install would have failed.
+    2. The Gateway named in httpRoute.parentRefs
+{{- range $httpRoute.parentRefs }}
+         {{ .name }}{{ if .namespace }} in namespace {{ .namespace }}{{ end }}{{ if .sectionName }}, listener {{ .sectionName }}{{ end }}
+{{- end }}
+       must exist AND its listener must allow routes from this namespace
+       ({{ .Release.Namespace }}) in allowedRoutes. A rejected attachment shows
+       up only in the route's status:
+
+         kubectl -n {{ .Release.Namespace }} get httproute {{ .Release.Name }}-{{ .Chart.Name }}-httproute -o yaml
+
+       Read status.parents[].conditions — "Accepted: True" and
+       "ResolvedRefs: True" is a working attachment. An empty status means no
+       controller has looked at the route at all.
+    3. The TLS certificate for the hostname, on the Gateway's listener.
+       ingress.clusterIssuer is NOT used in this mode and is not required: the
+       chart renders no Certificate, so there is no
+       tls-{{ .Release.Name }}-{{ .Chart.Name }}-ingress secret and nothing for cert-manager to do.
+
+  YOUR UPLOAD LIMIT IS NOT cwa.maxUploadFileSize ANY MORE — IT IS THE GATEWAY'S.
+  cwa.maxUploadFileSize ({{ .Values.cwa.maxUploadFileSize }}) is NOT ENFORCED in this mode. The chart
+  renders it into nginx.ingress.kubernetes.io/proxy-body-size, and the Gateway
+  API has NO counterpart — it knows no body size at all, that is
+  implementation-specific policy — so this chart deliberately renders no policy
+  object, which would bind it to one implementation. Whatever limit the Gateway
+  enforces is the limit your uploads get, and this is an e-book library: a book
+  above the Gateway's default is rejected before CWA sees a byte, the user gets
+  the proxy's error instead of a message from the application, and nothing says
+  a chart value was ignored. Set the limit at the Gateway, or through its
+  implementation's own policy object next to the Gateway — not here.
+
+  ingress.annotations is inert in this mode as well, for the same reason: the
+  Gateway API has no annotation channel.
 {{- else }}

-ACCESS — NO INGRESS
-  ingress.enabled is false, so this release has no Ingress and no certificate.
-  Neither ingress.domain nor ingress.clusterIssuer is needed: this chart reads
-  ingress.domain in the Ingress template and nowhere else. The app is reachable
+ACCESS — NEITHER INGRESS NOR HTTPROUTE
+  ingress.enabled and httpRoute.enabled are both false, so this release is not
+  published: no Ingress, no HTTPRoute and no certificate. Neither
+  ingress.domain nor ingress.clusterIssuer is needed — this chart reads
+  ingress.domain in the two routing templates and nowhere else, and with both
+  of them off nothing reads it. The app is reachable
  inside the cluster as {{ .Release.Name }}-{{ .Chart.Name }}-service:80. To open it locally:

    kubectl -n {{ .Release.Namespace }} port-forward svc/{{ .Release.Name }}-{{ .Chart.Name }}-service 8083:80
@@ -39,7 +91,9 @@ SCALED TO ZERO
  {{ if .Values.scaleDown }}scaleDown: true{{ else }}cwa.replicas: 0{{ end }} — the StatefulSet runs with replicas: 0, so nothing
  answers until you set it back and upgrade again. Both PVCs, the Secret and the
  Service{{ if .Values.ingress.enabled }} and Ingress stay in place, so no data is lost and the certificate
-  is not re-issued.{{ else }} stay in place, so no data is lost.{{ end }}
+  is not re-issued.{{ else if $httpRoute.enabled }} and HTTPRoute stay in place, so no data is lost — the route then
+  resolves to a Service with no endpoints and the Gateway answers its own
+  error.{{ else }} stay in place, so no data is lost.{{ end }}
 {{ end }}
 FIRST LOGIN — THE DEFAULT PASSWORD IS PUBLIC
  Username "admin", password "admin123". Those are the upstream defaults, they
@@ -0,0 +1,101 @@
+{{/*
+The Gateway-API alternative to calibre-web-automated.ingress.yaml (Gitea #114).
+Form and reasoning: template-chart/templates/xxx.httproute.yaml and README,
+"Ingress and Gateway API".
+
+Only an HTTPRoute with parentRefs. No Gateway, no gatewayClassName, no
+Certificate, and no implementation-specific policy object - that subset looks
+identical on nginx-gateway-fabric, Cilium, Envoy Gateway and Istio, which is
+the whole reason the cluster's implementation can be swapped without touching
+this chart. Class and certificate therefore belong to the PLATFORM, on the
+Gateway and its listeners.
+
+ingress.clusterIssuer is meaningless here - this chart renders no Certificate
+in this mode - and it is not demanded either: its only required() sits inside
+calibre-web-automated.ingress.yaml, behind ingress.enabled.
+
+THE UPLOAD LIMIT IS THE ONE THING THIS MODE LOSES, AND IT IS NOT REBUILT
+
+cwa.maxUploadFileSize is rendered into nginx.ingress.kubernetes.io/proxy-body-size
+and nginx.org/client-max-body-size by the Ingress template. The Gateway API has
+NO counterpart: it knows no body size at all, because a request-body limit is
+implementation-specific policy and lives in an implementation's own object
+(ClientSettingsPolicy on nginx-gateway-fabric, ClientTrafficPolicy on Istio,
+and so on). Rendering one here would bind this chart to one implementation and
+to a CRD whose presence it cannot check, so the limit is DOCUMENTED instead -
+NOTES.txt says in this mode that the value is not enforced and names where to
+set it. The price is named and deliberate: whoever overlooks that output gets
+the Gateway's default limit, and an oversized book fails as a proxy error
+rather than as a message from CWA. This chart is an e-book library, so the
+value is not decoration - a book above the Gateway's default is rejected, and
+the rejection carries no hint that a chart value was ignored.
+
+ingress.domain, AND WHY THIS FILE CHANGES WHAT CAN BE CLAIMED ABOUT IT
+
+Checked for this chart rather than copied: ingress.domain is read in the
+Ingress template and - until this file existed - NOWHERE else. No environment
+variable, no probe Host header, no URL the app builds itself; CWA is told its
+address by nothing. That is why values.yaml could say that switching the
+Ingress off makes domain unnecessary along with clusterIssuer.
+
+This file is now a second reader (when httpRoute.hostnames is empty), so that
+sentence holds only while BOTH modes are off. It is corrected in values.yaml
+and in values.schema.json rather than left standing. In Gateway mode with
+hostnames empty, domain is required again - by the required() below.
+*/}}
+{{- /*
+Null-safe like every other block this chart dereferences (#99): an override
+written without children - "httpRoute:" with the keys below it deleted - is
+YAML null, and `.Values.httpRoute.enabled` would abort the render with a nil
+pointer. An empty block means "chart defaults apply", and all three defaults
+are empty or false, so the whole block collapses to "no HTTPRoute".
+*/ -}}
+{{- $httpRoute := .Values.httpRoute | default dict -}}
+{{- if and $httpRoute.enabled .Values.ingress.enabled -}}
+{{- fail "ingress.enabled and httpRoute.enabled are both true - set exactly one of them. The Ingress and the HTTPRoute would publish the same Service under the same hostname over two different data paths, which is already a conflict at DNS level: one name, two addresses, and which one a client reaches is luck. A migration runs over a SECOND hostname (set httpRoute.hostnames explicitly while the Ingress keeps ingress.domain), never over parallel operation of both." -}}
+{{- end -}}
+{{- if $httpRoute.enabled -}}
+{{- $parentRefs := $httpRoute.parentRefs | default list -}}
+{{- if not $parentRefs -}}
+{{- fail "httpRoute.enabled is true but httpRoute.parentRefs is empty - an HTTPRoute without a parent attaches to no Gateway. It is created, it is schema-valid, and it routes NOTHING, with no event and no condition that says so; the only symptom is a hostname that does not answer. Name the cluster's Gateway, e.g. httpRoute.parentRefs: [{name: public, namespace: gateway}]." -}}
+{{- end -}}
+{{- /*
+One source of truth for the hostname: an empty httpRoute.hostnames means
+[ingress.domain], so the two cannot drift apart. ingress.domain is read here
+even though no Ingress is rendered in this mode - the value names the public
+hostname of this release, which both modes need; it is not an Ingress switch.
+Nothing inside the pod follows it, so a hostname set explicitly here needs no
+second value changed with it - which is what makes a migration over a second
+hostname cheap in THIS chart and expensive in others.
+*/ -}}
+{{- $hostnames := $httpRoute.hostnames | default list -}}
+{{- if not $hostnames -}}
+{{- $hostnames = list (required "A Domain/Host must be provided: set ingress.domain (used as the HTTPRoute's single hostname when httpRoute.hostnames is empty) or set httpRoute.hostnames explicitly" .Values.ingress.domain) -}}
+{{- end -}}
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+  name: {{ .Release.Name }}-{{ .Chart.Name }}-httproute
+spec:
+  parentRefs:
+    {{- toYaml $parentRefs | nindent 4 }}
+  hostnames:
+    {{- toYaml $hostnames | nindent 4 }}
+  rules:
+    # The Ingress counterpart is `path: / , pathType: Prefix` on the one
+    # backend Service - CWA serves its whole UI, including the OPDS feed and
+    # the ingest views, from one process on one port, so a single path covers
+    # it. The port is the Service's port NUMBER and not its name ("http"):
+    # backendRefs takes a PortNumber, so unlike the Ingress this reference
+    # cannot be made by name and the 80 below has to track
+    # calibre-web-automated.service.yaml by hand.
+    # ci/run-httproute-match-test.sh is what holds that pair - it fails when a
+    # backendRef names a Service, or a port, the same render does not create.
+    - matches:
+        - path:
+            type: PathPrefix
+            value: /
+      backendRefs:
+        - name: {{ .Release.Name }}-{{ .Chart.Name }}-service
+          port: 80
+{{- end }}
@@ -42,7 +42,7 @@
          "type": ["string", "null"]
        },
        "maxUploadFileSize": {
-          "description": "Rendered into the ingress-nginx proxy-body-size annotation, so it only takes effect while the Ingress is enabled.",
+          "description": "Rendered into the ingress-nginx proxy-body-size and nginx.org/client-max-body-size annotations, so it is enforced by the ingress controller and by nothing inside CWA. It does nothing with ingress.enabled: false, and it is NOT ENFORCED in Gateway mode either (Gitea #114): the Gateway API has no body-size field, the effective limit is the Gateway's, and this chart deliberately renders no implementation-specific policy object to set it. NOTES.txt says so in that mode.",
          "type": ["string", "null"]
        },
        "livenessProbe": {
@@ -70,7 +70,7 @@
      "additionalProperties": false,
      "properties": {
        "enabled": {
-          "description": "Gates the whole Ingress template (issue #93). ingress.domain is read nowhere else in this chart, so switching the Ingress off makes both domain and clusterIssuer unnecessary.",
+          "description": "Gates the whole Ingress template (issue #93). Mutually exclusive with httpRoute.enabled - the render aborts when both are true. Nothing inside the pod reads ingress.domain, so switching the Ingress off makes both domain and clusterIssuer unnecessary - but only while the Gateway mode is off as well: the HTTPRoute is a second reader of domain while httpRoute.hostnames is empty.",
          "type": "boolean"
        },
        "clusterIssuer": {
@@ -83,13 +83,42 @@
          "type": ["string", "null"]
        },
        "annotations": {
-          "description": "Extra Ingress annotations, merged with the cert-manager and proxy-body-size annotations the chart always sets. Free-form keys by nature.",
+          "description": "Extra Ingress annotations, merged with the cert-manager and proxy-body-size annotations the chart always sets. Free-form keys by nature. No counterpart in Gateway mode: the Gateway API has no annotation channel, so these are gone when httpRoute.enabled is used instead - including the upload cap the chart itself sets from cwa.maxUploadFileSize.",
          "type": "object"
        }
      }
+    },
+    "httpRoute": {
+      "description": "Gateway-API alternative to the Ingress (Gitea #114). Mutually exclusive with ingress.enabled - the render aborts when both are true. The chart renders only an HTTPRoute with parentRefs; class and certificate sit on the Gateway and belong to the platform. The Gateway-API CRDs must be present in the cluster, because the chart cannot detect them. cwa.maxUploadFileSize is not enforced in this mode.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": {
+          "type": "boolean"
+        },
+        "parentRefs": {
+          "description": "The Gateway(s) the route attaches to. Required while httpRoute.enabled is true, enforced in the template (an empty list aborts the render) - a JSON Schema \"required\" cannot do it, because the key ships as an empty list and is therefore present. Entries are the Gateway API's ParentReference and are passed through unchanged.",
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/parentRef"
+          }
+        },
+        "hostnames": {
+          "description": "Empty means [ingress.domain], so the hostname has a single source of truth. Nothing inside the pod follows the hostname in this chart, so a name set here needs no second value changed with it.",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
    }
  },
  "definitions": {
+    "parentRef": {
+      "description": "A Gateway API ParentReference, passed verbatim into HTTPRoute.spec.parentRefs. Deliberately left OPEN (no additionalProperties: false), for the same reason probes and security contexts are: Kubernetes owns this schema, the Gateway API adds fields to it across releases, and a closed list here would reject a field only upstream knows about. What the chart can assert is that \"name\" is there - it is required by the API and a reference without it attaches to nothing, which is the silent failure this chart aborts the render over.",
+      "type": "object",
+      "required": ["name"]
+    },
    "resources": {
      "description": "May be null / empty: the chart then falls back to its default requests and computed limits (issue #99) instead of rendering a container without resource accounting.",
      "type": ["object", "null"],
@@ -23,6 +23,15 @@ cwa:
  storage: 10Gi
  storageClass: longhorn
  timezone: "UTC"
+  # The upload cap, and it lives entirely in the INGRESS: the chart renders it
+  # into nginx.ingress.kubernetes.io/proxy-body-size and
+  # nginx.org/client-max-body-size, so it is enforced by the nginx-family
+  # controllers and by nothing inside CWA. Consequences worth knowing before
+  # trusting it: with ingress.enabled: false it does nothing at all, and in
+  # Gateway mode (httpRoute.enabled) it is NOT ENFORCED either - the Gateway
+  # API has no body-size field, the limit is the Gateway's own, and this chart
+  # deliberately renders no implementation-specific policy object to set it
+  # (Gitea #114). NOTES.txt says so in both modes.
  maxUploadFileSize: "10m"
  livenessProbe:
    httpGet:
@@ -107,13 +116,76 @@ cwa:
  env: []

 ingress:
-  # Set to false to omit the Ingress entirely. Unlike some other charts here,
-  # ingress.domain is read nowhere but in the Ingress template, so switching
-  # the Ingress off makes both domain and clusterIssuer unnecessary.
+  # Set to false to omit the Ingress entirely. Nothing inside the pod reads
+  # ingress.domain - no environment variable, no probe Host header, no URL the
+  # app builds itself - so with the Ingress off, clusterIssuer and domain are
+  # both unnecessary. That is still true, but no longer the whole sentence:
+  # the HTTPRoute below is a SECOND reader of ingress.domain (while
+  # httpRoute.hostnames is empty), so "domain is not needed" holds only while
+  # BOTH routing modes are off.
+  #
+  # Mutually exclusive with httpRoute.enabled below (Gitea #114): with both
+  # true the render aborts, naming both values.
  enabled: true
  clusterIssuer: null
+  # The public hostname of this release. Read by the Ingress and - when
+  # httpRoute.hostnames is empty - by the HTTPRoute, and by nothing else.
  domain: null
  className: nginx
  # Extra annotations for the Ingress; merged with the cert-manager
  # cluster-issuer and proxy-body-size annotations the chart always sets.
+  #
+  # THESE HAVE NO COUNTERPART IN GATEWAY MODE. The Gateway API has no
+  # annotation channel for controller behaviour, so anything configured here is
+  # simply gone when httpRoute.enabled is used instead - it is then the
+  # Gateway's business, or that of an implementation-specific policy object
+  # this chart deliberately does not render. For THIS chart that includes the
+  # upload cap: see cwa.maxUploadFileSize above.
  annotations: {}
+
+# Gateway-API alternative to the Ingress above (Gitea #114). Off by default, so
+# an existing release is unaffected; exactly one of ingress.enabled and
+# httpRoute.enabled may be true.
+#
+# The chart renders ONLY an HTTPRoute with parentRefs - no Gateway, no
+# gatewayClassName, no Certificate and no implementation-specific policy
+# object. Class and certificate belong to the Gateway and therefore to the
+# platform, which is what keeps this chart independent of whether the cluster
+# runs nginx-gateway-fabric, Cilium, Envoy Gateway or Istio.
+#
+# WHAT THIS MODE COSTS HERE: cwa.maxUploadFileSize is not enforced. It exists
+# only as an ingress-nginx annotation and the Gateway API has no body-size
+# field, so the limit becomes whatever the Gateway enforces. For an e-book
+# library that is the one value worth checking before switching - a book above
+# the Gateway's default is rejected by the proxy, and nothing in CWA's log says
+# a chart value was ignored. NOTES.txt prints this in Gateway mode.
+#
+# The Gateway-API CRDs must be installed in the cluster: the chart does not and
+# cannot detect them (.Capabilities.APIVersions is unreliable at template
+# time), so with httpRoute.enabled: true and no CRDs the INSTALL fails.
+httpRoute:
+  enabled: false
+  # The Gateway(s) this route attaches to - a platform object, usually in
+  # another namespace, which must allow this namespace in its listener's
+  # allowedRoutes. One entry per parent, the fields are the Gateway API's
+  # ParentReference (name, and optionally namespace, sectionName, port, group,
+  # kind), passed through unchanged:
+  #
+  #   parentRefs:
+  #     - name: public
+  #       namespace: gateway
+  #       sectionName: https
+  #
+  # REQUIRED while httpRoute.enabled is true - the render aborts on an empty
+  # list, because a route without a parent is created, is valid and routes
+  # nothing, with no event to say so.
+  parentRefs: []
+  # Empty means [ingress.domain], so the hostname has one source of truth. Set
+  # explicitly only to publish under a different or an additional name - which
+  # is how a migration from the Ingress runs: the HTTPRoute takes a second
+  # hostname while the Ingress keeps ingress.domain.
+  #
+  # Cheap in this chart, because nothing inside the pod follows the hostname:
+  # CWA is told its address by nothing, so a second name needs no second value
+  # changed with it.
+  hostnames: []