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

zipline/Chart.yaml

@@ -16,7 +16,7 @@ type: application
 # This is the chart version. This version number should be incremented each time you make changes
 # to the chart and its templates, including the app version.
 # Versions are expected to follow Semantic Versioning (https://semver.org/)
-version: 7.1.1+up4.7.0
+version: 7.2.0+up4.7.0
 
 # This is the version number of the application being deployed. This version number should be
 # incremented each time you make changes to the application. Versions are not expected to

zipline/templates/NOTES.txt

@@ -6,21 +6,66 @@
 {{- if and (kindIs "float64" $startup.periodSeconds) (kindIs "float64" $startup.failureThreshold) -}}
 {{- $budget = printf "%.0f seconds" (mulf $startup.periodSeconds $startup.failureThreshold) -}}
 {{- end -}}
+{{- $httpRoute := .Values.httpRoute | default dict -}}
+{{- $hostnames := $httpRoute.hostnames | default list -}}
+{{- if not $hostnames -}}
+{{- $hostnames = list .Values.ingress.domain -}}
+{{- end -}}
 Zipline {{ .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 }}"
   cluster issuer. Until it has been issued the browser shows a warning; follow it with
 
     kubectl -n {{ .Release.Namespace }} get certificate tls-{{ .Release.Name }}-{{ .Chart.Name }}-ingress
+{{- 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.
+
+  ingress.domain is still required in this mode and is {{ .Values.ingress.domain }}: it is also
+  CORE_DEFAULT_DOMAIN, the host Zipline puts into every share link it hands
+  out, and the route does not replace it. If you set httpRoute.hostnames to a
+  name ingress.domain does not carry, the route publishes one host while every
+  link the app generates names another — set both together.
+
+  ingress.annotations is inert in this mode: the Gateway API has no annotation
+  channel. For this chart that includes the upload cap — see below.
 {{- else }}
 
-ACCESS — NO INGRESS
-  ingress.enabled is false, so this release has no Ingress and no certificate;
+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;
   ingress.clusterIssuer is not needed. ingress.domain still is: it is also
   CORE_DEFAULT_DOMAIN, the host Zipline puts into every share link it hands
   out. Reach the instance inside the cluster with
@@ -35,7 +80,9 @@ SCALED TO ZERO
   {{ if .Values.scaleDown }}scaleDown: true{{ else }}zipline.replicas: 0{{ end }} — the StatefulSet runs with replicas: 0, so the endpoint
   above does not answer until you set it back and upgrade again. The uploads
   PVC, both Secrets 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 }}
+  lost and the certificate 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 }}
 THE FIRST VISITOR CHOOSES THE ADMINISTRATOR
   Against an empty database Zipline has no users, and it sends every visitor
@@ -94,7 +141,7 @@ WHAT A READY POD PROVES — AND WHAT AN OUTAGE LOOKS LIKE
   deliberately uses "/" instead, so a database outage cannot restart the pod.
   Know the resulting picture in advance: during such an outage the container
   keeps running and stays quiet, the pod goes NotReady, its endpoint is
-  dropped{{ if .Values.ingress.enabled }} and the Ingress answers 503{{ end }} — and nothing in the pod's log or
+  dropped{{ if .Values.ingress.enabled }} and the Ingress answers 503{{ else if $httpRoute.enabled }} and the Gateway answers its own error for the route{{ end }} — and nothing in the pod's log or
   restart count points at the database. Look there first.
 
 TWO DIFFERENT CEILINGS APPLY TO AN UPLOAD
@@ -105,9 +152,21 @@ TWO DIFFERENT CEILINGS APPLY TO AN UPLOAD
   ({{ .Values.config.maxUploadFileSize }}), so that is the ceiling that actually bites: anything larger is
   rejected by ingress-nginx with 413 before Zipline sees a byte of it. Raise
   config.maxUploadFileSize to move it.
+  {{- else if $httpRoute.enabled }}
+  IN GATEWAY MODE config.maxUploadFileSize ({{ .Values.config.maxUploadFileSize }}) IS NOT ENFORCED. 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 ceiling your uploads get, and this is an upload service: an
+  oversized upload is rejected by the proxy before Zipline sees a byte, the
+  user gets the Gateway'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 and not
+  here.
   {{- else }}
   config.maxUploadFileSize ({{ .Values.config.maxUploadFileSize }}) is rendered nowhere in this release: it exists
-  only as an ingress-nginx annotation, and the Ingress is switched off.
+  only as an ingress-nginx annotation, and neither routing mode is on.
   Whatever proxy you put in front needs its own body-size limit.
   {{- end }}
 

zipline/templates/zipline.httproute.yaml

@@ -0,0 +1,104 @@
+{{/*
+The Gateway-API alternative to zipline.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
+zipline.ingress.yaml, behind ingress.enabled.
+
+ingress.domain IS STILL REQUIRED, AND NOT BECAUSE OF THIS FILE
+
+Checked for this chart rather than copied: ingress.domain is read once more
+outside both routing templates, in zipline.sfs.yaml, where it becomes
+CORE_DEFAULT_DOMAIN and carries its own required(). That is the host Zipline
+puts into every share link it hands out - the whole point of the application -
+so domain is mandatory in EVERY mode of this chart and the fallback below is
+never its only reader. Setting httpRoute.hostnames to a name ingress.domain
+does not carry publishes the route under one host while every link the app
+generates names another, and the links simply do not resolve. Set both
+together.
+
+THE UPLOAD LIMIT IS WHAT THIS MODE LOSES, AND IT IS NOT REBUILT
+
+config.maxUploadFileSize is rendered into proxy-body-size and
+nginx.org/client-max-body-size by the Ingress template, and in Ingress mode it
+is the ceiling that actually bites: it is far below the app's own
+UPLOADER_ADMIN_LIMIT of 500mb, which this chart pins and does not expose. The
+Gateway API has NO counterpart - a request-body limit is implementation-
+specific policy and lives in an implementation's own object
+(ClientSettingsPolicy, ClientTrafficPolicy and their equivalents), which this
+chart deliberately does not render. So the value is DOCUMENTED as unenforced in
+NOTES.txt rather than rebuilt.
+
+This chart is a file-upload service, so that is not a footnote: in Gateway mode
+the ceiling is whatever the Gateway enforces, and the failure arrives as the
+proxy's error rather than as a message from Zipline. There is a second,
+quieter consequence that does NOT change with the mode and is worth re-reading
+before raising anything: /tmp is an emptyDir and counts against the container's
+ephemeral-storage limit, so an upload that fits through the Gateway can still
+get the whole pod evicted. NOTES.txt covers both.
+*/}}
+{{- /*
+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.
+A hostname set explicitly here does NOT move CORE_DEFAULT_DOMAIN with it: the
+share links keep naming ingress.domain, so the two have to be set together.
+*/ -}}
+{{- $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 - Zipline serves its UI, its API and the short URLs of
+    # every upload from one process on one port, so a single path covers all of
+    # them. 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
+    # zipline.service.yaml by hand (whose targetPort is the container's
+    # "zipline-server", which is a third name again).
+    # 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 }}

zipline/values.schema.json

@@ -37,7 +37,7 @@
           "type": ["string", "null"]
         },
         "maxUploadFileSize": {
-          "description": "Rendered into the ingress-nginx body-size annotations, so it only takes effect while the Ingress is enabled.",
+          "description": "Rendered into the ingress-nginx body-size annotations, so it only takes effect while the Ingress is enabled. NOT ENFORCED in Gateway mode (Gitea #114): the Gateway API has no body-size field, the effective ceiling 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"]
         }
       }
@@ -75,7 +75,7 @@
       "additionalProperties": false,
       "properties": {
         "enabled": {
-          "description": "Gates the whole Ingress template (issue #93). false omits the Ingress and makes clusterIssuer unnecessary - but NOT domain, which is also the app's default domain for generated share links.",
+          "description": "Gates the whole Ingress template (issue #93). Mutually exclusive with httpRoute.enabled - the render aborts when both are true. false omits the Ingress and makes clusterIssuer unnecessary - but NOT domain, which is also the app's default domain for generated share links and carries its own required() in the StatefulSet.",
           "type": "boolean"
         },
         "clusterIssuer": {
@@ -88,13 +88,42 @@
           "type": ["string", "null"]
         },
         "annotations": {
-          "description": "Extra Ingress annotations, merged with the cert-manager and body-size annotations the chart always sets. Free-form keys by nature.",
+          "description": "Extra Ingress annotations, merged with the cert-manager and 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 config.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. config.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. A hostname set here does not move CORE_DEFAULT_DOMAIN, which keeps following ingress.domain - so every share link still names the old host until both are set.",
+          "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"],

zipline/values.yaml

@@ -11,6 +11,19 @@ secrets:
 config:
   storage: 50Gi
   storageClass: longhorn
+  # The request-body 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 Zipline. In Ingress mode it is the
+  # ceiling that actually bites, far below the app's own UPLOADER_ADMIN_LIMIT
+  # of 500mb (pinned in the template, not a value).
+  #
+  # 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 ceiling becomes the Gateway's, and this chart
+  # deliberately renders no implementation-specific policy object to set it
+  # (Gitea #114). For an upload service that is the value to check before
+  # switching modes; NOTES.txt prints it.
   maxUploadFileSize: 30m
 
 zipline:
@@ -88,10 +101,69 @@ ingress:
   # required even then: it is also the app's default domain for generated
   # share links (CORE_DEFAULT_DOMAIN), not just the Ingress host. Only
   # clusterIssuer becomes unnecessary.
+  #
+  # 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, by
+  # CORE_DEFAULT_DOMAIN in the StatefulSet (with its own required()), and -
+  # when httpRoute.hostnames is empty - by the HTTPRoute. Required in every
+  # mode.
   domain: null
   className: nginx
   # Extra annotations for the Ingress; merged with the cert-manager
   # cluster-issuer and upload-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 config.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: config.maxUploadFileSize is not enforced, so the
+# upload ceiling is the Gateway's. This is a file-upload service - that is the
+# one value to check before switching, and an oversized upload then fails as a
+# proxy error rather than as a message from Zipline.
+#
+# 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.
+  #
+  # For THIS chart, mind that a second hostname does not move
+  # CORE_DEFAULT_DOMAIN with it: every share link Zipline hands out keeps
+  # naming ingress.domain until that value is changed too.
+  hostnames: []