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

README.md

@@ -176,9 +176,9 @@ Three things to know before touching it:
 
 - **Helm is the YAML parser**, through `ci/yaml2json`, for the same reason as the selector-match test above — the runners have neither `pyyaml` nor `yq`, and a parser written in `awk` fails by reading nothing and reporting nothing.
 - **What is deliberately not checked**, named so the gaps are not mistaken for coverage. *That traffic flows* — no Gateway controller runs in CI and none will, so `Accepted: True` is not obtainable; that claim is simply not made anywhere in this pipeline. *Mutual exclusion with the Ingress* — each chart aborts its own render when `ingress.enabled` and `httpRoute.enabled` are both true, which is where it belongs: this test renders one configuration per chart, and a rule here would have to assume the switch is chart-global, which may not survive the multi-app charts of the sweep. *Cross-namespace and non-Service backends*, and a rule with no `backendRefs` at all (legal for a filter-only rule) — all three are **reported as "not checked", never counted as passing**.
-- **Two anti-vacuum guards**, because the convention ships `httpRoute.enabled: false` and this test would otherwise be green over nothing. `ci/httproute/<chart>.yaml` is a render-only overlay applied **last** whose one job is to put a chart into Gateway mode — and a chart that *has* one and still renders no route **fails**. On top of that the run fails if **no assertion at all** held anywhere. Today `cyberchef` is exercised through its ordinary install-test fixture (which installs in Gateway mode, see below) and `template-chart` through its overlay.
+- **Two anti-vacuum guards**, because the convention ships `httpRoute.enabled: false` and this test would otherwise be green over nothing. `ci/httproute/<chart>.yaml` is a render-only overlay applied **last** whose one job is to put a chart into Gateway mode — and a chart that *has* one and still renders no route **fails**. On top of that the run fails if **no assertion at all** held anywhere. `cyberchef` is exercised through its ordinary install-test fixture (which installs in Gateway mode, see below), every other converted chart through its overlay. For a multi-app chart the overlay also has to enter every shape the template has: `ci/httproute/freesailarr.yaml` moves one app onto a host of its own so that the shared-host route *and* the per-app route are both rendered.
 
-Measured in CI (run 719): **30 charts, 4 assertions held**, whole job 13 s including checkout and the Helm setup, no cluster. The fail path was exercised rather than assumed: a Service renamed in the route, a port the Service does not expose, a port left out entirely, an emptied `parentRefs` with the chart's own guard disabled, an overlay that renders no route, and a run with zero assertions — each produced a `FAIL` naming both sides and a non-zero exit.
+Measured in CI (run 719, the pilot): **30 charts, 4 assertions held**, whole job 13 s including checkout and the Helm setup, no cluster. Group 1 took that to 20 assertions over 10 charts and group 2 to **36 over 15** — the sweep adds charts, not checks, so the job stays a render. The fail path was exercised rather than assumed: a Service renamed in the route, a port the Service does not expose, a port left out entirely, an emptied `parentRefs` with the chart's own guard disabled, an overlay that renders no route, and a run with zero assertions — each produced a `FAIL` naming both sides and a non-zero exit.
 
 ### Install-test (PR pipeline stage 2)
 
@@ -383,12 +383,17 @@ These guidelines are **binding for every current and future chart** in this repo
   - **`parentRefs` is mandatory in Gateway mode**, enforced by a `fail` on the empty list. A route without a parent attaches to nothing and is simply inert — created, schema-valid, rejected by nobody, reported by nothing.
   - **One source of truth for the hostname.** Empty `hostnames` means `[ingress.domain]`; two values that have to agree drift apart. `ingress.domain` is therefore read in Gateway mode too — it names the release's public hostname and is not an Ingress switch.
   - **`NOTES.txt` says which mode is active**, as `keycloak` already does for its cases, and names what the mode costs.
-  - **What has no counterpart, and must be said rather than rebuilt.** The Gateway API has no annotation channel for controller behaviour. `rewrite-target` has a real equivalent (the `URLRewrite` filter in a rule); **`proxy-body-size` has none** — an upload limit is implementation-specific policy, so a chart that depends on one must print in its Gateway-mode `NOTES.txt` that the limit is **not enforced** and has to be set at the Gateway. Five charts *set* one by default (`bulwark`, `calibre-web-automated`, `outline`, `paperless-ngx`, `zipline`), and `garage` is a sixth that *depends* on one without setting it: its `ingress.annotations` comment tells the operator to set `proxy-body-size: "0"` because ingress-nginx's 1 MB default truncates S3 uploads. Measured while sweeping group 1 — "sets no behaviour-bearing annotation" is not the same question as "needs none", and the sweep screens on the second one. The same applies to auth annotations in front of an app with no login of its own: in Gateway mode that escape hatch does not exist in the chart at all (`cyberchef`, `searxng`), and so does any annotation a chart documents as its only lever for a response header (`bentopdf`: `X-Robots-Tag`).
-  - **A value derived from `ingress.enabled` is a second thing the sweep has to look for, and it is not visible in the Ingress template.** Gateway mode sets `ingress.enabled: false` *by construction*, so any value computed from it flips — and where it stood for "is there a TLS-terminating proxy in front", the flipped value is wrong while nothing fails. Found in `sure`, whose `RAILS_ASSUME_SSL`/`RAILS_FORCE_SSL` would have gone `false` with TLS terminated at the Gateway: insecure cookies, no HSTS, `http://` links, green pod. The fix is one helper reading `ingress.enabled OR httpRoute.enabled`, not a new value. Still open on this count: `freesailarr` and `ytdlp-web-player` both read `.Values.ingress.enabled` outside their Ingress templates.
-  - **CI**: either the chart's install-test fixture installs in Gateway mode, or it gets a render-only overlay at `ci/httproute/<chart>.yaml` — otherwise `ci/run-httproute-match-test.sh` is green over nothing for it, which that test fails on.
+  - **What has no counterpart, and must be said rather than rebuilt.** The Gateway API has no annotation channel for controller behaviour. `rewrite-target` has a real equivalent (the `URLRewrite` filter in a rule); **`proxy-body-size` has none** — an upload limit is implementation-specific policy, so a chart that depends on one must print in its Gateway-mode `NOTES.txt` that the limit is **not enforced** and has to be set at the Gateway. Five charts *set* one by default (`bulwark`, `calibre-web-automated`, `outline`, `paperless-ngx`, `zipline` — all but `bulwark` carry that disclosure since group 2), and `garage` is a sixth that *depends* on one without setting it: its `ingress.annotations` comment tells the operator to set `proxy-body-size: "0"` because ingress-nginx's 1 MB default truncates S3 uploads. Measured while sweeping group 1 — "sets no behaviour-bearing annotation" is not the same question as "needs none", and the sweep screens on the second one. `freesailarr` is the mirror image of `garage` and was measured in group 2: it sets no body-size annotation and needs none itself, but `ingress.annotations` is the only lever an operator has for one (qBittorrent takes torrent-file uploads), so its Gateway-mode `NOTES.txt` says that an annotation set there is gone. The same applies to auth annotations in front of an app with no login of its own: in Gateway mode that escape hatch does not exist in the chart at all (`cyberchef`, `searxng`), and so does any annotation a chart documents as its only lever for a response header (`bentopdf`: `X-Robots-Tag`).
+  - **`rewrite-target` is the one place where the Gateway API is less machinery than what it replaces, not a translation of it.** `rewrite-target` applies per **Ingress object**; a `URLRewrite` filter applies per **rule**. A chart serving several apps under one host, one of which needs its prefix stripped, therefore needs a *second* Ingress object for that app — which then has to repeat the other object's TLS secret name, omit the cert-manager annotation so only one certificate is requested (conditionally, for the case where no other object renders), and match on an `ImplementationSpecific` regex path whose capture group the rewrite refers to. In Gateway mode all four disappear: one route, one rule per app, the filter on one rule, a plain `PathPrefix`. Measured on `freesailarr` in group 2, the only chart here with a `rewrite-target`; `bulwark` is the second and is in group 3.
+  - **A value derived from `ingress.enabled` is a second thing the sweep has to look for, and it is not visible in the Ingress template.** Gateway mode sets `ingress.enabled: false` *by construction*, so any value computed from it flips — and where it stood for "is there a TLS-terminating proxy in front" or "is this app published at all", the flipped value is wrong while nothing fails. Two finds so far, both fixed by one helper reading `ingress.enabled OR httpRoute.enabled` rather than by a new value:
+    - `sure` (group 1), whose `RAILS_ASSUME_SSL`/`RAILS_FORCE_SSL` would have gone `false` with TLS terminated at the Gateway: insecure cookies, no HSTS, `http://` links, green pod. Helper `sure.publishedOverTls`.
+    - `freesailarr` (group 2), whose `freesailarr.sharedIngressApps` was gated on `ingress.enabled` and is read by the `<APP>__SERVER__URLBASE` environment variables as well as by the routing objects. In Gateway mode that list would have come out **empty**, so Radarr, Sonarr and Prowlarr would have been told no base path while their routes served them under `/radarr`, `/sonarr`, `/prowlarr` — a UI whose assets and API calls are linked at the host root, behind a Ready pod. The two guards living in that helper (seerr/mediathekarr only at `/`, no duplicate paths on the shared host) would have gone unenforced in that mode for the same reason. Helper `freesailarr.published`.
 
-  Reference implementation: `template-chart/templates/xxx.httproute.yaml`. Pilot: `cyberchef`. Group 1 — the charts rendering one Ingress with no behaviour-bearing annotation — followed: `bentopdf`, `garage`, `patchmon`, `rallly`, `searxng`, `sure`, `urlaubsverwaltung`, `voucher-vault`. That leaves **twelve** charts plus `rss-bridge`, which is frozen for changes (#51) and is why #114 cannot be closed while #51 is open: group 2 is the annotation cases (`calibre-web-automated`, `outline`, `paperless-ngx`, `zipline`, `freesailarr`) and group 3 the special shapes (`homeassistant` is the documented ingress exception, `keycloak` and `bulwark` have two Ingresses each, `matrix-synapse` renders in a loop, `stalwart` renders per node group, `ytdlp-web-player` hangs off the oauth2-proxy subchart). `garage` was one of the named special cases and is done: it ships `ingress.enabled: false`, so both of its modes are off by default and its route is exercised by a render overlay rather than by the install-test, which keeps its Ingress.
-- **Documented exception — freesailarr**: the chart bundles several independently exposed apps in one pod, so it has **no** `ingress.domain`. It offers both shapes. By default each app carries its own `<app>.ingress.enabled` plus a required `<app>.ingress.host` (required only while that app's ingress is enabled and it is not on the shared domain) and renders its own Ingress object `<release>-<chart>-<app>-ingress` with its own TLS secret `tls-<release>-<chart>-<app>-ingress`. Setting the global `ingress.host` switches every app without a host of its own to the shared-domain shape under `<app>.ingress.path`; qBittorrent (no base path, needs a prefix-stripping rewrite) gets the extra object described above, and seerr as well as mediathekarr are pinned to `/` — mediathekarr because its UI links assets with root-absolute paths, which a rewrite cannot fix; with both of them on one shared host the duplicate-path guard fires and one of them needs a host of its own (its ingress is therefore off by default). `clusterIssuer`, `className` and `annotations` stay global defaults under `ingress.` and are overridable per app.
+    Still open on this count: `ytdlp-web-player`, which reads `.Values.ingress.enabled` outside its Ingress template.
+  - **CI**: either the chart's install-test fixture installs in Gateway mode, or it gets a render-only overlay at `ci/httproute/<chart>.yaml` — otherwise `ci/run-httproute-match-test.sh` is green over nothing for it, which that test fails on. An overlay for a multi-app chart has a second job: it must enter **every** shape the template has, or the branch nobody exercised is the one that breaks. `ci/httproute/freesailarr.yaml` gives one app a host of its own so both the shared-host route and the per-app route render.
+
+  Reference implementation: `template-chart/templates/xxx.httproute.yaml`. Pilot: `cyberchef`. Group 1 — the charts rendering one Ingress with no behaviour-bearing annotation — followed: `bentopdf`, `garage`, `patchmon`, `rallly`, `searxng`, `sure`, `urlaubsverwaltung`, `voucher-vault`. Group 2 — the charts whose behaviour hangs off an nginx annotation — followed: `calibre-web-automated`, `outline`, `paperless-ngx`, `zipline` (all four `proxy-body-size`) and `freesailarr` (`rewrite-target`). That leaves **seven** charts plus `rss-bridge`, which is frozen for changes (#51) and is why #114 cannot be closed while #51 is open: group 3 is the special shapes (`homeassistant` is the documented ingress exception, `keycloak` and `bulwark` have two Ingresses each, `matrix-synapse` renders in a loop, `stalwart` renders per node group, `ytdlp-web-player` hangs off the oauth2-proxy subchart). `garage` was one of the named special cases and is done: it ships `ingress.enabled: false`, so both of its modes are off by default and its route is exercised by a render overlay rather than by the install-test, which keeps its Ingress. `paperless-ngx` was the one chart in the repository that still rendered its Ingress **unconditionally**; group 2 gave it an `ingress.enabled` switch defaulting to `true`, because without a second value path there is nothing for the mutual-exclusion abort to name and the `required()` on `clusterIssuer` would have kept demanding a value the Gateway mode does not use.
+- **Documented exception — freesailarr, and it extends to the Gateway mode**: the chart bundles several independently exposed apps in one pod, so it has **no** `ingress.domain` — and therefore **no `httpRoute.hostnames`** either, the only chart without that key. A chart-global list of hostnames could not say which of the ten apps it belonged to, so the hostnames stay where they already are, in `ingress.host` and `<app>.ingress.host`; both are read by both modes and neither is an Ingress switch. In Gateway mode the per-app shape renders one `HTTPRoute` per app (`<release>-<chart>-<app>-httproute`) and the shared shape exactly one (`<release>-<chart>-httproute`) with one rule per app — qBittorrent included, since its prefix-stripping rewrite is a per-rule filter there. It offers both shapes. By default each app carries its own `<app>.ingress.enabled` plus a required `<app>.ingress.host` (required only while that app's ingress is enabled and it is not on the shared domain) and renders its own Ingress object `<release>-<chart>-<app>-ingress` with its own TLS secret `tls-<release>-<chart>-<app>-ingress`. Setting the global `ingress.host` switches every app without a host of its own to the shared-domain shape under `<app>.ingress.path`; qBittorrent (no base path, needs a prefix-stripping rewrite) gets the extra object described above, and seerr as well as mediathekarr are pinned to `/` — mediathekarr because its UI links assets with root-absolute paths, which a rewrite cannot fix; with both of them on one shared host the duplicate-path guard fires and one of them needs a host of its own (its ingress is therefore off by default). `clusterIssuer`, `className` and `annotations` stay global defaults under `ingress.` and are overridable per app.
 
 ### 5. Security hardening
 

calibre-web-automated/Chart.yaml

@@ -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:

calibre-web-automated/templates/NOTES.txt

@@ -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

calibre-web-automated/templates/calibre-web-automated.httproute.yaml

@@ -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 }}

calibre-web-automated/values.schema.json

@@ -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"],

calibre-web-automated/values.yaml

@@ -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: []

ci/httproute/calibre-web-automated.yaml

@@ -0,0 +1,28 @@
+# Render-only overlay for ci/run-httproute-match-test.sh, applied LAST.
+#
+# Its one job is to put this chart into Gateway mode, because the convention
+# ships with httpRoute.enabled: false and the test would otherwise be green
+# over nothing. A chart that has an overlay here and still renders no
+# HTTPRoute FAILS the test - that is the whole point of the file existing.
+#
+# An overlay and not a change to ci/calibre-web-automated/test-values.yaml: the
+# install-test runs exactly ONE configuration per chart and the two modes are
+# mutually exclusive, so switching the fixture would drop this chart's Ingress
+# from the install for a CRD schema cyberchef's fixture already exercises
+# against the real Gateway-API CRDs. The install keeps the Ingress; the route is
+# held here, at render level, which is where its two silent failure modes live.
+#
+# ingress.enabled: false is not optional here - the chart aborts its own render
+# when both modes are true.
+#
+# ingress.domain comes from ci/calibre-web-automated/test-values.yaml;
+# httpRoute.hostnames is left empty on purpose, so the fallback to
+# ingress.domain is what the test exercises and the two cannot disagree here.
+ingress:
+  enabled: false
+httpRoute:
+  enabled: true
+  parentRefs:
+    - name: public
+      namespace: gateway
+      sectionName: https

ci/httproute/freesailarr.yaml

@@ -0,0 +1,55 @@
+# Render-only overlay for ci/run-httproute-match-test.sh, applied LAST.
+#
+# Its one job is to put this chart into Gateway mode, because the convention
+# ships with httpRoute.enabled: false and the test would otherwise be green
+# over nothing. A chart that has an overlay here and still renders no
+# HTTPRoute FAILS the test - that is the whole point of the file existing.
+#
+# An overlay and not a change to ci/freesailarr/test-values.yaml: the
+# install-test runs exactly ONE configuration per chart, and this chart's
+# fixture is the expensive one - it brings up a real Wireguard tunnel so that
+# ten containers can become Ready. Switching it into Gateway mode would trade
+# its Ingress objects for a CRD schema cyberchef's fixture already exercises
+# against the real Gateway-API CRDs. The install keeps the Ingresses; the
+# routes are held here, at render level, which is where their two silent
+# failure modes live.
+#
+# ingress.enabled: false is not optional here - ingress.enabled is this chart's
+# MASTER switch and defaults to true, so without this line the chart aborts its
+# own render with both modes on.
+#
+# WHAT THIS OVERLAY ACTUALLY COVERS, which is more than one route:
+#
+#   - ingress.host comes from the fixture (freesailarr.example.com), so the
+#     SHARED-domain shape is what renders: one HTTPRoute with one rule per app.
+#   - qbittorrent is enabled in the fixture, so its rule is in that route WITH
+#     the URLRewrite filter - the per-rule equivalent of the rewrite-target
+#     annotation, and the reason this chart needs no second routing object in
+#     this mode.
+#   - mediathekarr is enabled in the fixture with its ingress off, so the
+#     per-app selector is exercised in the negative direction too.
+#   - every rule's backendRef is checked against the per-app Services of the
+#     same render, which is where this chart differs from the rest of the
+#     sweep: it has one Service per app and the route carries the port NUMBER,
+#     not the name the Ingress uses.
+#
+# There is no httpRoute.hostnames key in this chart (see values.yaml): the
+# hostnames come from ingress.host and <app>.ingress.host, which the fixture
+# already sets.
+#
+# A SECOND APP IS GIVEN A HOST OF ITS OWN so the MIXED shape is covered as
+# well: bazarr then renders its own route (ci-freesailarr-bazarr-httproute)
+# while the rest stay on the shared host. Without it the per-app branch of the
+# template would never be entered by any test. Bazarr is the right one to move
+# because its sub-path mode needs a manual step inside the application anyway.
+ingress:
+  enabled: false
+httpRoute:
+  enabled: true
+  parentRefs:
+    - name: public
+      namespace: gateway
+      sectionName: https
+bazarr:
+  ingress:
+    host: bazarr.ci.local

ci/httproute/outline.yaml

@@ -0,0 +1,30 @@
+# Render-only overlay for ci/run-httproute-match-test.sh, applied LAST.
+#
+# Its one job is to put this chart into Gateway mode, because the convention
+# ships with httpRoute.enabled: false and the test would otherwise be green
+# over nothing. A chart that has an overlay here and still renders no
+# HTTPRoute FAILS the test - that is the whole point of the file existing.
+#
+# An overlay and not a change to ci/outline/test-values.yaml: the install-test
+# runs exactly ONE configuration per chart and the two modes are mutually
+# exclusive, so switching the fixture would drop this chart's Ingress from the
+# install for a CRD schema cyberchef's fixture already exercises against the
+# real Gateway-API CRDs. The install keeps the Ingress; the route is held here,
+# at render level, which is where its two silent failure modes live.
+#
+# ingress.enabled: false is not optional here - the chart aborts its own render
+# when both modes are true.
+#
+# ingress.domain comes from ci/outline/test-values.yaml and keeps feeding
+# Outline's URL variable in this mode too; httpRoute.hostnames is left empty on
+# purpose, so the fallback to ingress.domain is what the test exercises - and
+# the two therefore cannot disagree here, which is the state this chart needs
+# for its OIDC redirect URI to match.
+ingress:
+  enabled: false
+httpRoute:
+  enabled: true
+  parentRefs:
+    - name: public
+      namespace: gateway
+      sectionName: https

ci/httproute/paperless-ngx.yaml

@@ -0,0 +1,32 @@
+# Render-only overlay for ci/run-httproute-match-test.sh, applied LAST.
+#
+# Its one job is to put this chart into Gateway mode, because the convention
+# ships with httpRoute.enabled: false and the test would otherwise be green
+# over nothing. A chart that has an overlay here and still renders no
+# HTTPRoute FAILS the test - that is the whole point of the file existing.
+#
+# An overlay and not a change to ci/paperless-ngx/test-values.yaml: that
+# fixture is the ONLY install of the valkey-subchart path anywhere in this
+# repository (see its header), and the install-test runs exactly one
+# configuration per chart. Switching it into Gateway mode would trade that
+# coverage, plus this chart's Ingress, for a CRD schema cyberchef's fixture
+# already exercises against the real Gateway-API CRDs. The install keeps the
+# Ingress and the subchart; the route is held here, at render level, which is
+# where its two silent failure modes live.
+#
+# ingress.enabled: false is not optional here, and in THIS chart it is also
+# new: the switch was added with the Gateway mode (#114) and defaults to true,
+# so without this line the chart aborts its own render with both modes on.
+#
+# ingress.domain comes from ci/paperless-ngx/test-values.yaml and keeps feeding
+# PAPERLESS_URL in this mode too; httpRoute.hostnames is left empty on purpose,
+# so the fallback to ingress.domain is what the test exercises - and the two
+# therefore cannot disagree here, which is the state Django's CSRF check needs.
+ingress:
+  enabled: false
+httpRoute:
+  enabled: true
+  parentRefs:
+    - name: public
+      namespace: gateway
+      sectionName: https

ci/httproute/zipline.yaml

@@ -0,0 +1,29 @@
+# Render-only overlay for ci/run-httproute-match-test.sh, applied LAST.
+#
+# Its one job is to put this chart into Gateway mode, because the convention
+# ships with httpRoute.enabled: false and the test would otherwise be green
+# over nothing. A chart that has an overlay here and still renders no
+# HTTPRoute FAILS the test - that is the whole point of the file existing.
+#
+# An overlay and not a change to ci/zipline/test-values.yaml: the install-test
+# runs exactly ONE configuration per chart and the two modes are mutually
+# exclusive, so switching the fixture would drop this chart's Ingress from the
+# install for a CRD schema cyberchef's fixture already exercises against the
+# real Gateway-API CRDs. The install keeps the Ingress; the route is held here,
+# at render level, which is where its two silent failure modes live.
+#
+# ingress.enabled: false is not optional here - the chart aborts its own render
+# when both modes are true.
+#
+# ingress.domain comes from ci/zipline/test-values.yaml and keeps feeding
+# CORE_DEFAULT_DOMAIN in this mode too; httpRoute.hostnames is left empty on
+# purpose, so the fallback to ingress.domain is what the test exercises - and
+# the two therefore cannot disagree here.
+ingress:
+  enabled: false
+httpRoute:
+  enabled: true
+  parentRefs:
+    - name: public
+      namespace: gateway
+      sectionName: https

freesailarr/Chart.yaml

@@ -8,7 +8,7 @@ description: A Helm chart to deploy a Wireguard-tunneled media automation stack
 
 type: application
 
-version: 3.1.1+up1.0.0
+version: 3.2.0+up1.0.0
 # The chart's own version marker, freely chosen and tied to no upstream. The
 # stack bundles ten independently versioned projects (nine of them on by
 # default), so there is no single "app version" to track here.

freesailarr/templates/NOTES.txt

@@ -10,6 +10,8 @@
 {{- $shared := include "freesailarr.sharedIngressApps" . | fromJsonArray -}}
 {{- $sharedNames := list -}}
 {{- range $shared }}{{ $sharedNames = append $sharedNames .name }}{{ end -}}
+{{- $httpRoute := .Values.httpRoute | default dict -}}
+{{- $published := include "freesailarr.published" . -}}
 freesailarr — release {{ .Release.Name }} in namespace {{ .Release.Namespace }}.
 {{ if .Values.mediathekarr.enabled }}Ten{{ else }}Nine{{ end }} containers in ONE pod, sharing gluetun's network namespace.
 
@@ -44,7 +46,12 @@ SET gluetun.vpn.firewallOutboundSubnets — IT IS EMPTY RIGHT NOW
 {{- end }}
 
 ACCESS
-{{- if and .Values.ingress.enabled $ingressApps }}
+{{- if and $published $ingressApps }}
+{{- if .Values.ingress.enabled }}
+  INGRESS MODE (ingress.enabled: true, httpRoute.enabled: false)
+{{- else }}
+  GATEWAY MODE (httpRoute.enabled: true, ingress.enabled: false)
+{{- end }}
 {{- range $shared }}
   {{ .name }}: https://{{ $sharedHost }}{{ if ne .path "/" }}{{ .path }}{{ end }}
 {{- end }}
@@ -56,7 +63,8 @@ ACCESS
 {{- end }}
 {{- if $shared }}
 
-  These apps share one host, one Ingress and one certificate.
+  These apps share one host{{ if .Values.ingress.enabled }}, one Ingress and one certificate{{ else }} and one HTTPRoute ({{ $name }}-httproute), one
+  rule each{{ end }}.
 {{- if has "bazarr" $sharedNames }}
 
   BAZARR NEEDS ONE MANUAL STEP UNDER A SUB-PATH
@@ -73,8 +81,17 @@ ACCESS
 {{- if has "qbittorrent" $sharedNames }}
 
   QBITTORRENT SITS BEHIND A PREFIX-STRIPPING REWRITE
-    It has no base path of its own, so it gets a second Ingress object on the
-    same host whose rewrite cuts the prefix off. Two things there look exactly
+    It has no base path of its own, so the prefix has to be cut off before the
+    request reaches it.
+    {{- if .Values.ingress.enabled }} Under an Ingress that costs a SECOND object on the
+    same host, because nginx applies rewrite-target per object and the other
+    apps must not be rewritten.
+    {{- else }} In Gateway mode that second object is gone: a
+    URLRewrite filter belongs to a RULE, so qBittorrent is one rule of
+    {{ $name }}-httproute with the filter on it and its neighbours are
+    untouched by construction — no extra object, no regex path.
+    {{- end }}
+    Two things here look exactly
     like a login failure and send you looking in the wrong place: its session
     cookie is marked "Secure" (over plain HTTP the browser never sends it back
     and every click bounces to the login form), and it bans the client IP for a
@@ -90,12 +107,48 @@ ACCESS
 {{- end }}
 {{- end }}
 
+{{- if .Values.ingress.enabled }}
   Every app listed with a host of its own has its OWN Ingress and its own TLS
   secret. While cert-manager is still issuing, the browser warns:
 
     kubectl -n {{ .Release.Namespace }} get certificate
 {{- else }}
-  No Ingress is rendered{{ if not .Values.ingress.enabled }} (ingress.enabled is false){{ end }}. Reach an app through its own service:
+  Every app listed with a host of its own has its OWN HTTPRoute
+  ({{ $name }}-<app>-httproute).
+
+  THREE THINGS BELONG TO THE CLUSTER AND NOT TO THIS CHART IN THIS MODE, and if
+  any is missing the addresses above do 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. Every route of this release
+       attaches to that same parent. A rejected attachment shows up only in a
+       route's status:
+
+         kubectl -n {{ .Release.Namespace }} get 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 certificates for these hostnames, on the Gateway's listener.
+       ingress.clusterIssuer is NOT used in this mode and is not required, and
+       neither are ingress.className or the per-app overrides of either: the
+       chart renders no Certificate and no class, so there are no
+       tls-{{ $name }}-* secrets and nothing for cert-manager to do.
+
+  ingress.annotations HAS NO COUNTERPART HERE, per-app overrides included: the
+  Gateway API has no annotation channel. The chart needs nothing from it —
+  qBittorrent's rewrite is a filter in this mode — but an annotation you added
+  yourself is gone without a word. A body-size cap for qBittorrent's
+  torrent-file uploads is the likely one; set it at the Gateway or through its
+  implementation's own policy object.
+{{- end }}
+{{- else }}
+  Nothing is published{{ if and (not .Values.ingress.enabled) (not $httpRoute.enabled) }} — ingress.enabled and httpRoute.enabled are both false{{ else if not $ingressApps }} — no enabled app carries <app>.ingress.enabled: true{{ end }}. Reach an app through its own service:
 {{- range $portApps }}
 
     kubectl -n {{ $.Release.Namespace }} port-forward svc/{{ $name }}-{{ .name }}-service {{ .port }}:{{ .port }}
@@ -105,7 +158,8 @@ ACCESS
 
   qBittorrent's WebUI rejects a Host header whose port differs from its own
   ({{ "8080" }}) with a plain 401. A port-forward on a different local port therefore
-  looks like a login failure — forward 8080:8080, or go through the ingress.
+  looks like a login failure — forward 8080:8080, or go through the published
+  address above.
 {{- if .Values.qbittorrent.savePath }}
 
 QBITTORRENT DOWNLOADS GO TO {{ .Values.qbittorrent.savePath }}
@@ -158,8 +212,8 @@ MEDIATHEKARR: TWO PORTS, AND THE SABNZBD API IS NOT AT /api
   back as the SABnzbd complete_dir. Any deviation — a remote path mapping, a
   different mount — imports NOTHING, without an error.
 
-  The UI (setup wizard and download queue) has no ingress{{ if and .Values.mediathekarr.ingress.enabled .Values.mediathekarr.ingress.host }}, other than the one
-  you gave it on {{ .Values.mediathekarr.ingress.host }}{{ end }}:
+  The UI (setup wizard and download queue) is not published{{ if and .Values.mediathekarr.ingress.enabled .Values.mediathekarr.ingress.host }}, other than on the
+  host you gave it, {{ .Values.mediathekarr.ingress.host }}{{ end }}:
 
     kubectl -n {{ .Release.Namespace }} port-forward svc/{{ $name }}-mediathekarr-service 5007:5007
 {{- if $gate.enabled }}
@@ -286,7 +340,7 @@ THE MEDIA CLAIMS ARE YOURS, THE CONFIG VOLUMES ARE THE CHART'S
 
 SCALED TO ZERO
   {{ if .Values.scaleDown }}scaleDown: true{{ else }}replicas: 0{{ end }} — the StatefulSet runs with replicas: 0. PVCs, secrets,
-  services{{ if .Values.ingress.enabled }} and ingresses{{ end }} stay in place; set it back and upgrade to bring the
+  services{{ if .Values.ingress.enabled }} and ingresses{{ else if $httpRoute.enabled }} and HTTPRoutes{{ end }} stay in place; set it back and upgrade to bring the
   stack up again.
 {{- else if ne $replicas "1" }}
 

freesailarr/templates/_helpers.tpl

@@ -205,8 +205,49 @@ in the ingress, which addresses a service port by name.
 {{- end -}}
 
 {{/*
-The apps that render an Ingress: the enabled port apps whose values carry an
-ingress block with enabled: true. Used by the ingress template.
+Is this release published through a routing object at all? Returns the string
+"true" or the empty string (falsy in a template "if").
+
+Input: the root context.
+
+ONE PLACE, BECAUSE THE WRONG ANSWER IS INVISIBLE (Gitea #114)
+
+ingress.enabled is the chart's master switch, and until the Gateway-API mode
+existed it was also the answer to "is anything published". It stopped being
+that answer in exactly one configuration - and that configuration is the whole
+point of the new mode: httpRoute.enabled: true forces ingress.enabled: false
+(the two are mutually exclusive, the render aborts otherwise), while the apps
+ARE published, now through HTTPRoutes.
+
+The consumer that makes this load-bearing is NOT the routing templates - those
+know their own mode - but freesailarr.sharedIngressApps below, which is also
+read by the <APP>__SERVER__URLBASE environment variables (see
+freesailarr.urlBase). Read from ingress.enabled alone, that list would come out
+EMPTY in Gateway mode, so Radarr, Sonarr and Prowlarr would be told no base
+path while their routes serve them under /radarr, /sonarr and /prowlarr. Each
+app would then answer at the sub-path with a page whose assets and API calls
+are linked at the host root, i.e. a broken UI behind a Ready pod - the same
+silent class as sure's TLS flags, found in the same sweep. The duplicate-path
+and root-only guards in that helper would also have gone unenforced in Gateway
+mode, for the same reason.
+
+With httpRoute.enabled at its default of false this expression IS
+ingress.enabled, which is why adding it changes nothing for an existing
+release: `helm template` with unchanged values renders byte-identically.
+*/}}
+{{- define "freesailarr.published" -}}
+{{- $httpRoute := .Values.httpRoute | default dict -}}
+{{- if or .Values.ingress.enabled $httpRoute.enabled -}}true{{- end -}}
+{{- end -}}
+
+{{/*
+The apps that are published through a routing object: the enabled port apps
+whose values carry an ingress block with enabled: true. Used by BOTH routing
+templates - the per-app <app>.ingress.enabled toggle selects which apps are
+exposed in Ingress mode and in Gateway mode alike, and only the Ingress-only
+fields of that block (clusterIssuer, className, annotations) have no meaning in
+the second one. The name is historical; renaming it would churn every call site
+for no behaviour.
 
   {{- $apps := include "freesailarr.ingressApps" . | fromJsonArray }}
 */}}
@@ -252,14 +293,19 @@ The apps served under the shared domain (ingress.host), as a JSON array of
 is deterministic.
 
 The shared-domain mode is off unless ingress.host is set; then it covers the
-apps whose ingress renders at all (freesailarr.ingressApps, i.e. the enabled
-port apps with ingress.enabled) and which do not carry a host of their own. A
-per-app host always wins and keeps rendering its own object exactly as before,
-which is what makes mixed operation fall out for free.
+apps whose routing object renders at all (freesailarr.ingressApps, i.e. the
+enabled port apps with ingress.enabled) and which do not carry a host of their
+own. A per-app host always wins and keeps rendering its own object exactly as
+before, which is what makes mixed operation fall out for free.
 
-Two guards live here rather than in the ingress template, so that every
-consumer - the ingress objects, the UrlBase env vars and NOTES.txt - sees the
-same validated list:
+Gated on freesailarr.published and NOT on ingress.enabled (Gitea #114): this
+list is read by the UrlBase env vars too, and in Gateway mode ingress.enabled
+is false by construction while the apps are published all the same. See that
+helper for what reading the switch directly would have broken silently.
+
+Two guards live here rather than in the routing templates, so that every
+consumer - the Ingress objects, the HTTPRoutes, the UrlBase env vars and
+NOTES.txt - sees the same validated list:
 
   1. seerr or mediathekarr under any path other than "/". seerr has no base-path
      support (upstream request open since May 2022) and MediathekArr's UI links
@@ -277,7 +323,7 @@ same validated list:
 {{- $root := . -}}
 {{- $apps := list -}}
 {{- $host := $root.Values.ingress.host | default "" -}}
-{{- if and $root.Values.ingress.enabled $host -}}
+{{- if and (include "freesailarr.published" $root) $host -}}
 {{- $seen := dict -}}
 {{- range $app := include "freesailarr.ingressApps" $root | fromJsonArray -}}
 {{- $config := (index $root.Values $app.name).ingress -}}
@@ -320,9 +366,16 @@ base path from this environment variable (schema
 <APP>__CONFIGNAMESPACE__CONFIGITEM, https://wiki.servarr.com/sonarr/environment-variables),
 so the chart can configure them itself as soon as they render under a sub-path.
 
+Mode-independent by construction (Gitea #114): the sub-path an app is served
+under is the same in Ingress and in Gateway mode, so this variable follows
+freesailarr.sharedIngressApps and not the routing object. That is only true
+because that helper asks freesailarr.published rather than ingress.enabled -
+reading the switch directly would have emptied this variable in Gateway mode
+while the route still served the app under its prefix.
+
 Empty - i.e. the chart sets nothing - in three cases:
 
-  - the app does not render under the shared host, or renders at "/";
+  - the app is not served under the shared host, or is served at "/";
   - the app's own env block already carries the variable. The env blocks are
     documented as additive; emitting a second entry with the same name would
     break that promise, and two identically named variables in one container

freesailarr/templates/freesailarr.httproute.yaml

@@ -0,0 +1,188 @@
+{{/*
+The Gateway-API alternative to freesailarr.ingress.yaml (Gitea #114). Form and
+reasoning: template-chart/templates/xxx.httproute.yaml and README, "Ingress and
+Gateway API".
+
+Only HTTPRoutes 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, ingress.className,
+ingress.annotations and their per-app overrides are all inert in this mode.
+
+THE SAME TWO SHAPES AS THE INGRESS, AND THEY STILL MIX
+
+  1. One host per app (the default): every published app gets its own
+     HTTPRoute with its own hostname, pointing at its own app's Service.
+  2. One shared domain with sub-paths (ingress.host): the apps that carry no
+     host of their own move into ONE route with one rule each.
+
+THIS CHART HAS NO ingress.domain, SO httpRoute HAS NO hostnames
+
+It is the documented exception on that point (README, guideline 4): the chart
+bundles ten independently exposed apps, so there is no single hostname to put
+in a chart-global list - a hostnames entry could not say which app it belonged
+to. The hostnames therefore come from the values that already hold them,
+ingress.host and <app>.ingress.host, which keeps the single source of truth the
+convention is actually about. Those two are not Ingress switches: they name the
+public addresses of this release, and both modes read them.
+
+Consequence for a migration: the "second hostname" the convention offers
+elsewhere is done here by changing <app>.ingress.host, which in Gateway mode
+feeds only the route - there is no Ingress rendered to disagree with it.
+
+WHERE THE GATEWAY API IS BETTER THAN WHAT IT REPLACES, AND IT IS NOT A
+TRANSLATION
+
+qBittorrent has no base-path setting: it serves its WebUI at the root and the
+proxy has to strip the prefix. nginx applies rewrite-target per INGRESS OBJECT
+and not per path, and the other apps must NOT be rewritten - their UrlBase
+contains the prefix, so they expect the full path. That is why
+freesailarr.ingress.yaml splits qBittorrent into a SECOND Ingress object on the
+same host, which then has to
+
+  - repeat the same TLS secret name as the main object, so that neither object
+    depends on an assumption about whether nginx applies the other one's TLS
+    configuration to its paths,
+  - OMIT the cert-manager annotation so only one Certificate is requested for
+    that one secret - except when no main object renders at all, which is a
+    conditional inside the annotation block, and
+  - match on an ImplementationSpecific path with a regex
+    ("<path>(/|$)(.*)") whose capture group 2 the rewrite refers to.
+
+The Gateway API's URLRewrite filter is per RULE. All of that disappears: one
+route, one rule per app, and qBittorrent's rule carries the filter while its
+neighbours do not. The path match goes back to a plain PathPrefix, there is no
+second object, no duplicated TLS block, no conditional annotation and no
+regex. The convention's own summary says rewrite-target "has a real
+equivalent"; in this chart the equivalent is strictly less machinery than the
+original, and that is the reason this chart was worth converting rather than
+merely translating.
+
+WHAT IS NOT BETTER: ANYTHING THAT WAS AN ANNOTATION AND IS NOT A FILTER. The
+per-app and global ingress.annotations have no counterpart at all here. This
+chart sets no body-size annotation of its own, so nothing it NEEDS is lost -
+but an operator who added one through ingress.annotations (qBittorrent takes
+torrent file uploads) loses it silently in this mode. NOTES.txt says so.
+*/}}
+{{- /*
+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 both 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 Ingresses and the HTTPRoutes would publish the same Services under the same hostnames 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. ingress.enabled is this chart's MASTER switch and defaults to true, so turning the Gateway mode on means setting ingress.enabled: false in the same values file. A migration runs over different hostnames (change ingress.host or <app>.ingress.host), never over parallel operation of both modes." -}}
+{{- 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 -}}
+{{- $sharedHost := .Values.ingress.host | default "" }}
+{{- /* The same validated list the Ingress uses, and the same list the UrlBase
+       env vars read: it is gated on freesailarr.published, so it is populated
+       in this mode as well. Its two guards - seerr/mediathekarr only at "/",
+       no duplicate paths on the shared host - therefore apply here unchanged,
+       which is the whole reason they live in the helper. */}}
+{{- $shared := include "freesailarr.sharedIngressApps" $ | fromJsonArray }}
+{{- range $app := include "freesailarr.ingressApps" $ | fromJsonArray }}
+{{- $config := (index $.Values $app.name).ingress }}
+{{- /* Skip the apps that live on the shared domain; they are one rule each in
+       the single route below. */}}
+{{- if or (not $sharedHost) ($config.host | default "") }}
+{{- $host := required (printf "%s.ingress.host must be provided while %s.ingress.enabled is true (or set the shared ingress.host to serve the app under a sub-path instead). The value is the app's public hostname and is read in Gateway mode as well - it is not an Ingress switch." $app.name $app.name) $config.host }}
+---
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+  name: {{ $.Release.Name }}-{{ $.Chart.Name }}-{{ $app.name }}-httproute
+spec:
+  parentRefs:
+    {{- toYaml $parentRefs | nindent 4 }}
+  hostnames:
+    - {{ $host | quote }}
+  rules:
+    {{- /* The Ingress counterpart is `path: / , pathType: Prefix` on this
+           app's own Service. An app on a host of its own is served at the
+           root, so no rewrite is involved in either mode - that question only
+           arises under the shared host below.
+
+           The port is the Service's port NUMBER and not its name (the Ingress
+           addresses it by name, which is the app name): backendRefs takes a
+           PortNumber, so this reference cannot be made by name and the number
+           has to track freesailarr.service.yaml. Both come from
+           freesailarr.portApps, which is also what the Service renders from,
+           so they cannot drift - and
+           ci/run-httproute-match-test.sh 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 }}-{{ $app.name }}-service
+          port: {{ int $app.port }}
+{{- end }}
+{{- end }}
+{{- if $shared }}
+{{/*
+The shared-domain route: ONE object for every app under ingress.host, one rule
+each, rendered only when at least one app actually contributes a path - so
+switching every app off while leaving ingress.host set produces no object
+rather than an empty one without rules.
+
+qBittorrent is in here with the others, which is the difference to the Ingress:
+its rule carries the URLRewrite filter that strips the prefix, and a filter in
+the Gateway API belongs to a RULE. No second object, no repeated TLS secret, no
+conditional cert-manager annotation, no regex path - see the header.
+
+The rules come sorted by path length descending, as the Ingress paths do. The
+Gateway API specifies matching precedence by longest path match independent of
+order (and so does nginx), so this is about a deterministic, reviewable
+rendering, not about matching behaviour.
+*/}}
+---
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+  name: {{ .Release.Name }}-{{ .Chart.Name }}-httproute
+spec:
+  parentRefs:
+    {{- toYaml $parentRefs | nindent 4 }}
+  hostnames:
+    - {{ $sharedHost | quote }}
+  rules:
+    {{- range $app := $shared }}
+    - matches:
+        - path:
+            type: PathPrefix
+            value: {{ $app.path | quote }}
+      {{- if eq $app.name "qbittorrent" }}
+      {{- /* qBittorrent has no base-path setting - it serves its WebUI at the
+             root, so the prefix has to be stripped
+             (https://github.com/qbittorrent/wiki/blob/master/NGINX-Reverse-Proxy-for-Web-UI.md).
+             ReplacePrefixMatch replaces exactly the PathPrefix matched above,
+             which is why the match must be a PathPrefix and not a regex.
+
+             The apps around it must NOT be rewritten: their UrlBase carries
+             the prefix, so they expect the full path. Under an Ingress that
+             made a second object unavoidable, because rewrite-target applies
+             per object; here the filter is scoped to this rule and the others
+             are untouched by construction. */}}
+      filters:
+        - type: URLRewrite
+          urlRewrite:
+            path:
+              type: ReplacePrefixMatch
+              replacePrefixMatch: /
+      {{- end }}
+      backendRefs:
+        - name: {{ $.Release.Name }}-{{ $.Chart.Name }}-{{ $app.name }}-service
+          port: {{ int $app.port }}
+    {{- end }}
+{{- end }}
+{{- end }}

freesailarr/values.schema.json

@@ -127,11 +127,11 @@
       "additionalProperties": false,
       "properties": {
         "enabled": {
-          "description": "Master switch; false suppresses every app ingress regardless of the per-app toggles.",
+          "description": "Master switch; false suppresses every app ingress regardless of the per-app toggles. Mutually exclusive with httpRoute.enabled - the render aborts when both are true, and since this defaults to true it has to be switched off explicitly to use the Gateway mode.",
           "type": "boolean"
         },
         "host": {
-          "description": "Shared domain for the sub-path mode. Empty or null means the default: every app on a host of its own.",
+          "description": "Shared domain for the sub-path mode. Empty or null means the default: every app on a host of its own. Read by BOTH routing modes - it names the public address of the stack and is not an Ingress switch. This chart has no ingress.domain, so this value and the per-app <app>.ingress.host are also where the HTTPRoutes take their hostnames from.",
           "type": [
             "string",
             "null"
@@ -150,11 +150,28 @@
           ]
         },
         "annotations": {
-          "description": "Extra Ingress annotations, merged with the cert-manager annotation the chart always sets. Free-form keys by nature, so this object stays open.",
+          "description": "Extra Ingress annotations, merged with the cert-manager annotation the chart always sets. Free-form keys by nature, so this object stays open. No counterpart in Gateway mode, per-app overrides included: the Gateway API has no annotation channel, so anything set here is gone when httpRoute.enabled is used instead. The chart needs nothing from it - qBittorrent's prefix-stripping rewrite has a per-rule URLRewrite filter as its equivalent there - but an annotation you added yourself is lost silently.",
           "type": "object"
         }
       }
     },
+    "httpRoute": {
+      "description": "Gateway-API alternative to the Ingress (Gitea #114). Mutually exclusive with ingress.enabled - the render aborts when both are true, and ingress.enabled defaults to true in this chart. The chart renders only HTTPRoutes with parentRefs; class and certificate sit on the Gateway and belong to the platform. Both ingress shapes work unchanged, and the sub-path shape gets simpler: a URLRewrite filter is per rule, so qBittorrent needs no second routing object. There is deliberately no hostnames key - this chart 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. The Gateway-API CRDs must be present in the cluster, because the chart cannot detect them.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": {
+          "type": "boolean"
+        },
+        "parentRefs": {
+          "description": "The Gateway(s) every route of this release 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"
+          }
+        }
+      }
+    },
     "gluetun": {
       "type": "object",
       "additionalProperties": false,
@@ -608,6 +625,13 @@
     }
   },
   "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"
+      ]
+    },
     "image": {
       "description": "Every image in this chart is pinned here, gluetun included; no tag comes from appVersion. This is also what puts them all under Renovate's helm-values manager, which reads exactly these two keys.",
       "type": "object",

freesailarr/values.yaml

@@ -227,8 +227,12 @@ media:
 #     startupProbe accordingly (they are values, precisely for cases like this).
 #   - qbittorrent: it has no base path at all, so the chart gives it its own
 #     Ingress object on the same host with an nginx rewrite that strips the
-#     prefix. Two traps from the upstream recipe, both of which look like a
-#     login failure and therefore point in the wrong direction:
+#     prefix. (In GATEWAY MODE that second object is gone: the Gateway API's
+#     URLRewrite filter is per RULE, not per object, so qBittorrent is one rule
+#     in the shared route while its neighbours stay unrewritten. The traps
+#     below are the application's and apply in both modes.) Two traps from the
+#     upstream recipe, both of which look like a login failure and therefore
+#     point in the wrong direction:
 #       * qBittorrent marks its session cookie "Secure". Reaching the UI over
 #         plain HTTP means the browser never sends the cookie back and every
 #         click bounces to the login form. Use https.
@@ -247,16 +251,79 @@ media:
 ingress:
   # Master switch: false suppresses every app ingress regardless of the
   # per-app toggles.
+  #
+  # Mutually exclusive with httpRoute.enabled below (Gitea #114): with both
+  # true the render aborts, naming both values. Mind that this defaults to
+  # TRUE, so turning the Gateway mode on means setting enabled: false in the
+  # same values file.
   enabled: true
   # The shared domain for the sub-path mode, e.g. "media.example.com". Empty
   # means the default: each app on a host of its own.
+  #
+  # Read by BOTH routing modes: it names the public address of the stack and is
+  # not an Ingress switch. Same for the per-app <app>.ingress.host.
   host: ""
   clusterIssuer: null
   className: nginx
   # Extra annotations for the Ingress objects; merged with the cert-manager
   # cluster-issuer annotation the chart always sets.
+  #
+  # NO COUNTERPART IN GATEWAY MODE, and the same goes for the per-app
+  # overrides: the Gateway API has no annotation channel for controller
+  # behaviour, so anything set here is simply gone when httpRoute.enabled is
+  # used instead. This chart NEEDS nothing from it - the one behaviour-bearing
+  # annotation it sets itself, qBittorrent's prefix-stripping rewrite, has a
+  # real and better equivalent in that mode (a per-rule URLRewrite filter). But
+  # an annotation YOU added here is lost without a word; a body-size cap for
+  # qBittorrent's torrent-file uploads is the likely candidate, and it then has
+  # to be set at the Gateway or through its implementation's own policy object.
   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 - and ingress.enabled defaults to true, so it
+# has to be switched off explicitly.
+#
+# The chart renders ONLY HTTPRoutes 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.
+#
+# Both shapes above work unchanged, and the sub-path mode gets SIMPLER: the
+# Gateway API's URLRewrite filter is per rule, so qBittorrent no longer needs a
+# second routing object of its own. One route, one rule per app, the filter on
+# qBittorrent's rule only.
+#
+# There is deliberately NO httpRoute.hostnames here, unlike every other chart
+# in the repository: this chart has no ingress.domain either (it bundles ten
+# independently exposed apps - README, guideline 4, documented exception), so a
+# chart-global list of hostnames could not say which app it belonged to. The
+# hostnames come from ingress.host and <app>.ingress.host, which is where this
+# chart's single source of truth for them already is.
+#
+# 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) every route of this release 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. The same list is used for every route
+  # this chart renders; the hosts differ, the Gateway does not.
+  parentRefs: []
+
 gluetun:
   # Pinned here like every other image in this chart, so Renovate's helm-values
   # manager proposes gluetun updates too. Docker Hub tags carry a v prefix.

outline/Chart.yaml

@@ -5,7 +5,7 @@ icon: https://raw.githubusercontent.com/outline/outline/main/public/images/icon-
 
 type: application
 
-version: 7.1.3+up1.10.1
+version: 7.2.0+up1.10.1
 appVersion: 1.10.1
 
 maintainers:

outline/templates/NOTES.txt

@@ -1,21 +1,70 @@
 {{- $replicas := include "outline.replicas" (dict "scaleDown" .Values.scaleDown "replicas" .Values.outline.replicas) -}}
 {{- $startup := fromYaml (include "outline.startupProbe" .Values.outline.startupProbe) -}}
 {{- $upload := .Values.outline.maxUploadSize | toString -}}
+{{- $httpRoute := .Values.httpRoute | default dict -}}
+{{- $hostnames := $httpRoute.hostnames | default list -}}
+{{- if not $hostnames -}}
+{{- $hostnames = list .Values.ingress.domain -}}
+{{- end -}}
 Outline {{ .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 becomes
+  Outline's URL variable, which builds every generated link, every share URL
+  and the OIDC redirect URI. 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 the app hands out links for another — and an OIDC
+  login then fails on a redirect_uri the provider does not know. Set both
+  together.
+
+  ingress.annotations is inert in this mode: the Gateway API has no annotation
+  channel. WebSockets need none — Outline's realtime editing upgrades on the
+  same port and a plain HTTPRoute passes that through, exactly as the Ingress
+  did without an annotation.
 {{- 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.domain is still required: it becomes Outline's URL variable, which
   builds every generated link, every share URL and the OIDC redirect URI.
   Reach the instance inside the cluster with
@@ -31,7 +80,9 @@ SCALED TO ZERO
   {{ if .Values.scaleDown }}scaleDown: true{{ else }}outline.replicas: 0{{ end }} — the StatefulSet runs with replicas: 0, so the endpoint
   above does not answer until you set it back and upgrade again. PVC, Secrets,
   Service{{ if .Values.ingress.enabled }} and Ingress stay in place, so neither the uploads nor the
-  certificate are touched.{{ else }} and the uploads on the PVC stay in place.{{ end }}
+  certificate are touched.{{ else if $httpRoute.enabled }} and HTTPRoute stay in place, so the uploads are not touched — the
+  route then resolves to a Service with no endpoints and the Gateway answers
+  its own error.{{ else }} and the uploads on the PVC stay in place.{{ end }}
 {{ end }}
 WHAT THE THREE 1PASSWORD ITEMS MUST CONTAIN
   The chart creates OnePasswordItem CRs; the operator turns each into a
@@ -135,13 +186,35 @@ TWO UPLOAD CEILINGS, THE SMALLER ONE WINS
   ingress controller's 413 page instead of a message from the app. With the
   chart defaults the Ingress is the tighter of the two by a factor of ten.
   Raise both, or neither.
+{{- else if $httpRoute.enabled }}
+
+YOUR UPLOAD CEILING IS NOT ingress.maxUploadFileSize ANY MORE — IT IS THE GATEWAY'S
+  outline.maxUploadSize        {{ $upload }}{{ if regexMatch "^[0-9]+$" $upload }} bytes (~{{ div (int64 $upload) 1048576 }} MiB){{ else }} — Outline reads this as a plain byte count{{ end }}
+  ingress.maxUploadFileSize    {{ .Values.ingress.maxUploadFileSize }} — NOT ENFORCED in this mode
+
+  The chart renders ingress.maxUploadFileSize 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. The ceiling that actually bites is therefore
+  the smaller of outline.maxUploadSize and WHATEVER THE GATEWAY ENFORCES, and
+  the chart can only name the first of those two. Set the limit at the Gateway
+  or through its implementation's own policy object, next to the Gateway and
+  not here.
+
+  Read that next to Gitea #12, which is about exactly this pair: with the chart
+  defaults the two documented numbers are a factor of ten apart. In this mode
+  the ingress half is gone, so neither of them is necessarily the one that
+  decides — which moves that defect rather than fixing it. Check the Gateway's
+  own limit before trusting either number.
 {{- else }}
 
 UPLOAD CEILING
   outline.maxUploadSize   {{ $upload }}{{ if regexMatch "^[0-9]+$" $upload }} bytes (~{{ div (int64 $upload) 1048576 }} MiB){{ else }} — Outline reads this as a plain byte count{{ end }}
 
-  Without an Ingress this is the only limit the chart sets — whatever proxy
-  you put in front adds its own, usually much smaller, body-size cap.
+  With neither routing mode on, this is the only limit the chart sets —
+  whatever proxy you put in front adds its own, usually much smaller,
+  body-size cap. ingress.maxUploadFileSize ({{ .Values.ingress.maxUploadFileSize }}) is rendered nowhere.
 {{- end }}
 
 THE CHART CONFIGURES NO MAIL

outline/templates/outline.httproute.yaml

@@ -0,0 +1,110 @@
+{{/*
+The Gateway-API alternative to outline.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
+outline.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 outline.sfs.yaml, where it builds Outline's
+URL variable and carries its own required(). URL is what every generated link,
+every share URL and the OIDC redirect URI are built from, so domain is
+mandatory in EVERY mode of this chart - the fallback below is never its only
+reader. Setting httpRoute.hostnames to a name ingress.domain does not carry
+therefore publishes the route under one name while the app hands out links
+under another, and an OIDC login fails on a redirect_uri the provider does not
+know. Set both together.
+
+THE UPLOAD LIMIT, AND WHY THIS MODE MOVES Gitea #12 INSTEAD OF FIXING IT
+
+ingress.maxUploadFileSize is rendered into proxy-body-size and
+nginx.org/client-max-body-size by the Ingress template. 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.
+
+That matters more here than anywhere else in this sweep, because this chart is
+the one with the open defect: outline.maxUploadSize is 250 MB by default while
+ingress.maxUploadFileSize is 25m - a factor of ten, and the smaller number
+wins (Gitea #12). In Gateway mode the ingress half of that pair DISAPPEARS, so
+the effective ceiling becomes the Gateway's, which is neither of the two values
+the chart documents. That CHANGES the situation of #12; it does not resolve it,
+and this file deliberately does not try to: the chart would have to render a
+policy object to do so, which is exactly the portability the sweep is buying.
+The honest statement is in NOTES.txt for this mode: whichever of
+outline.maxUploadSize and the Gateway's limit is smaller decides, and the chart
+can only name one of them.
+*/}}
+{{- /*
+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 Outline's URL variable with it:
+that keeps following ingress.domain, so the two have to be set together or the
+app publishes links nobody can follow.
+*/ -}}
+{{- $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 - Outline serves its UI, its API and its collaborative
+    # WebSocket from one process on one port, so a single path covers all
+    # three. 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
+    # outline.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.
+    #
+    # WEBSOCKETS: nothing to configure, in either mode. Outline's realtime
+    # editing runs over a WebSocket upgrade on the same port, and the Gateway
+    # API passes an upgrade through on a plain HTTPRoute - there is no
+    # annotation involved in Ingress mode either.
+    - matches:
+        - path:
+            type: PathPrefix
+            value: /
+      backendRefs:
+        - name: {{ .Release.Name }}-{{ .Chart.Name }}-service
+          port: 80
+{{- end }}

outline/values.schema.json

@@ -90,11 +90,11 @@
       "additionalProperties": false,
       "properties": {
         "enabled": {
-          "description": "Gates the whole Ingress template. false omits the Ingress and makes clusterIssuer unnecessary - but NOT domain, which is also Outline's public URL.",
+          "description": "Gates the whole Ingress template. 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 Outline's public URL and carries its own required() in the StatefulSet.",
           "type": "boolean"
         },
         "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 takes effect only 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. Together with outline.maxUploadSize this is the pair of Gitea #12 - the smaller of the two wins, and in Gateway mode the smaller one may be neither.",
           "type": ["string", "null"]
         },
         "clusterIssuer": {
@@ -107,13 +107,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 ingress.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. ingress.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 Outline's URL variable, which keeps following ingress.domain - set both together or the app hands out links under the old name.",
+          "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"],

outline/values.yaml

@@ -88,11 +88,86 @@ outline:
       ephemeralStorage: 10Mi
 
 ingress:
+  # Set to false to omit the Ingress entirely. clusterIssuer is then not needed
+  # either, because it is only read inside the Ingress template. ingress.domain
+  # is a different case: it is also Outline's URL variable (see below) and
+  # stays mandatory in every mode.
+  #
+  # Mutually exclusive with httpRoute.enabled below (Gitea #114): with both
+  # true the render aborts, naming both values.
   enabled: true
+  # 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 Outline.
+  #
+  # TWO CEILINGS APPLY TO AN UPLOAD AND THE SMALLER ONE WINS: this value and
+  # outline.maxUploadSize above, which default to 25m and ~250 MB - a factor of
+  # ten apart, with the ingress limit the tighter one (Gitea #12, open). In
+  # GATEWAY MODE this half disappears: the Gateway API has no body-size field,
+  # the value is NOT ENFORCED, and the ceiling becomes whatever the Gateway
+  # enforces - which is neither of the two numbers this chart documents. That
+  # moves #12 rather than resolving it; NOTES.txt says so in that mode.
   maxUploadFileSize: 25m
   clusterIssuer: null
+  # The public hostname of this release. Read by the Ingress, by Outline's URL
+  # variable 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 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 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: ingress.maxUploadFileSize is not enforced, so the
+# upload ceiling is the Gateway's. Check it before switching - this chart is
+# the one with the open upload defect (#12), and in this mode neither of the
+# two numbers the chart knows is necessarily the one that bites.
+#
+# 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 Outline's URL
+  # variable with it: it keeps following ingress.domain, so every generated
+  # link, every share URL and the OIDC redirect URI still name the old host
+  # until ingress.domain is changed too.
+  hostnames: []

paperless-ngx/Chart.yaml

@@ -5,7 +5,7 @@ icon: https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/dev/src-ui/s
 
 type: application
 
-version: 12.2.0+up3.2.1
+version: 12.3.0+up3.2.1
 
 appVersion: 3.2.1
 

paperless-ngx/templates/NOTES.txt

@@ -8,12 +8,18 @@
 {{- $valkeySvc := printf "%s-valkey-service" .Release.Name -}}
 {{- $pre := default (list) $scripts.preConsumptionScripts -}}
 {{- $post := default (list) $scripts.postConsumptionScripts -}}
+{{- $httpRoute := .Values.httpRoute | default dict -}}
+{{- $hostnames := $httpRoute.hostnames | default list -}}
+{{- if not $hostnames -}}
+{{- $hostnames = list .Values.ingress.domain -}}
+{{- end -}}
 Paperless-ngx {{ .Chart.AppVersion }} — release {{ .Release.Name }} in namespace {{ .Release.Namespace }}.
 
-ACCESS
+{{- if .Values.ingress.enabled }}
+
+ACCESS — INGRESS MODE (ingress.enabled: true, httpRoute.enabled: false)
   https://{{ .Values.ingress.domain }}
 
-  This chart has no ingress.enabled switch — the Ingress is always rendered.
   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
@@ -32,12 +38,87 @@ ACCESS
   PAPERLESS_CSRF_TRUSTED_ORIGINS through paperless.env for as long as you need
   it. Changing ingress.domain later changes PAPERLESS_URL with it, and the
   pods have to restart before they notice.
+{{- 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
+  PAPERLESS_URL ("https://{{ .Values.ingress.domain }}"), the only origin this release declares to
+  Django, 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
+  Django trusts another — pages load and every login POST is refused as a CSRF
+  failure. Set both together, and remember the pods have to restart before they
+  notice a changed domain.
+
+  YOUR WEB-UI UPLOAD LIMIT IS NOT paperless.files.maxUploadFileSize ANY MORE.
+  That value ({{ .Values.paperless.files.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 caps
+  uploads through the web UI, and the symptom is the proxy's error rather than a
+  message from paperless. Set it at the Gateway or through its
+  implementation's own policy object, next to the Gateway and not here.
+
+  The consume directory is unaffected: it passes no proxy and has no size limit
+  in any mode, so a document too large for the web UI still gets in that way.
+
+  ingress.annotations is inert in this mode for the same reason — the Gateway
+  API has no annotation channel.
+{{- else }}
+
+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, and
+  ingress.clusterIssuer is not needed.
+
+  ingress.domain IS still required and is {{ .Values.ingress.domain }}: the chart hands it to the
+  container as PAPERLESS_URL ("https://{{ .Values.ingress.domain }}"), the only origin this
+  release declares. Reach the instance inside the cluster with
+
+    kubectl -n {{ .Release.Namespace }} port-forward svc/{{ .Release.Name }}-{{ .Chart.Name }}-service 8000:80
+
+  Pages then load over http://localhost:8000, but expect the login POST to be
+  refused as a CSRF failure — that origin is not PAPERLESS_URL. Add
+  PAPERLESS_CSRF_TRUSTED_ORIGINS through paperless.env for as long as you need
+  it. paperless.files.maxUploadFileSize ({{ .Values.paperless.files.maxUploadFileSize }}) does nothing in this mode:
+  it exists only as an ingress-nginx annotation.
+{{- end }}
 {{ if eq $replicas "0" }}
 SCALED TO ZERO
   {{ if .Values.scaleDown }}scaleDown: true{{ else }}paperless.replicas: 0{{ end }} — the StatefulSet runs with replicas: 0, so the URL above
   does not answer until you set it back and upgrade again. PVCs, Secrets,
-  Service and Ingress stay in place, so neither the documents nor the
-  certificate are touched.
+  Service{{ if .Values.ingress.enabled }} and Ingress stay in place, so neither the documents nor the
+  certificate are touched.{{ else if $httpRoute.enabled }} and HTTPRoute stay in place, so the documents are not touched —
+  the route then resolves to a Service with no endpoints and the Gateway
+  answers its own error.{{ else }} stay in place, so the documents are not touched.{{ end }}
 {{- if .Values.smbConnection.enabled }}
 {{- if .Values.scaleDown }}
   scaleDown also suspends the SMB consume CronJob, so nothing is moved off the
@@ -227,11 +308,24 @@ HOW DOCUMENTS GET IN
   paperless.files.storage ({{ .Values.paperless.files.storage }}) sizes only the main volume, which holds
   data/, media/ and export/ as subPaths.
 
+{{- if .Values.ingress.enabled }}
   Uploads through the web UI take the second route and pass the Ingress, where
   the chart sets a body-size cap of {{ .Values.paperless.files.maxUploadFileSize }} (paperless.files.maxUploadFileSize,
   rendered into both the nginx.ingress and nginx.org annotations). A larger
   file is rejected by the ingress controller with a 413 before paperless ever
   sees it — the consume directory has no such limit.
+{{- else if $httpRoute.enabled }}
+  Uploads through the web UI take the second route, and in GATEWAY MODE
+  paperless.files.maxUploadFileSize ({{ .Values.paperless.files.maxUploadFileSize }}) is NOT ENFORCED: it exists only as
+  an ingress-nginx annotation and the Gateway API has no body-size field, so
+  the cap is whatever the Gateway enforces. The consume directory has no limit
+  in either mode.
+{{- else }}
+  Uploads through the web UI take the second route, but nothing publishes this
+  release and paperless.files.maxUploadFileSize ({{ .Values.paperless.files.maxUploadFileSize }}) is rendered nowhere:
+  it exists only as an ingress-nginx annotation. The consume directory has no
+  limit either way.
+{{- end }}
 {{- if .Values.smbConnection.enabled }}
 
   SMB CONSUME IS ON — AND IT MOVES ONLY TOP-LEVEL PDFs

paperless-ngx/templates/paperless-server.sfs.yaml

@@ -140,8 +140,21 @@ spec:
               value: "{{ .Values.paperless.ocr.output_type }}"
             - name: PAPERLESS_FILENAME_FORMAT
               value: "{{ .Values.paperless.files.filenameFormat }}"
+            {{- /*
+            ingress.domain is not a pure Ingress value: it is also
+            PAPERLESS_URL, the ONLY origin this release declares to Django, so
+            it stays required when ingress.enabled is false and in Gateway mode
+            (#114). The required() is here and not only in the Ingress template
+            because this is the read that cannot be switched off - an empty
+            value would render "https://" and every login POST would be refused
+            as a CSRF failure, with nothing in the log naming a chart value.
+
+            A template comment and not a YAML one on purpose: a "#" line here
+            is part of the rendered manifest, and this change has to leave
+            `helm template` byte-identical for unchanged values.
+            */}}
             - name: PAPERLESS_URL
-              value: "https://{{ .Values.ingress.domain }}"
+              value: "https://{{ required "A Domain/Host must be provided (ingress.domain) - it is also PAPERLESS_URL, the only origin this release declares" .Values.ingress.domain }}"
             - name: PAPERLESS_CONSUMER_ENABLE_ASN_BARCODE
               value: "{{ $barcodes.asn.enabled }}"
             - name: PAPERLESS_CONSUMER_ENABLE_BARCODES

paperless-ngx/templates/paperless.httproute.yaml

@@ -0,0 +1,112 @@
+{{/*
+The Gateway-API alternative to paperless.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.
+
+THIS CHART NEEDED AN ingress.enabled SWITCH BEFORE THIS FILE COULD EXIST
+
+It was the only chart here still rendering its Ingress unconditionally, so
+there was no second value path for the mutual-exclusion abort to name - and
+in Gateway mode the Ingress would have kept rendering, together with the
+unconditional required() on ingress.clusterIssuer, i.e. a value demanded for
+nothing. The switch was added with this file, defaulting to true so an existing
+release renders byte-identically. See the header of paperless.ingress.yaml.
+
+ingress.clusterIssuer is meaningless here - this chart renders no Certificate
+in this mode - and since the switch exists it is no longer demanded either: its
+required() now sits 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 paperless-server.sfs.yaml, where it becomes
+PAPERLESS_URL - the ONLY origin this release declares to Django. That read used
+to rely on the Ingress template's required() firing first, which stopped being
+true the moment the Ingress became switchable, so it now carries its own
+required(). Without it an empty domain would render "https://" and every login
+POST would be refused as a CSRF failure, with nothing in the log naming a chart
+value. Consequence in this mode: a hostname in httpRoute.hostnames that
+ingress.domain does not carry publishes the route under one name while Django
+trusts another, and the login breaks exactly that way. Set both together, and
+remember the pods have to restart before they notice a changed domain.
+
+THE UPLOAD LIMIT IS WHAT THIS MODE LOSES, AND IT IS NOT REBUILT
+
+paperless.files.maxUploadFileSize is rendered into proxy-body-size and
+nginx.org/client-max-body-size by the Ingress template. 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.
+
+The second route documents is unaffected, and that is worth knowing here: the
+consume directory (and the SMB CronJob that feeds it) has no size limit at all
+and does not pass any proxy, so in Gateway mode a document too large for the
+web UI still gets in that way.
+*/}}
+{{- /*
+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. Note that ingress.enabled defaults to TRUE in this chart, so setting httpRoute.enabled alone is not enough - switch the Ingress off explicitly." -}}
+{{- 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 PAPERLESS_URL with it, which is
+why the two have to be set together in this chart.
+*/ -}}
+{{- $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 - paperless serves its UI, its API and the document
+    # downloads from one process on one port, so a single path covers them.
+    #
+    # The port is the Service's port NUMBER, not its name: the Ingress
+    # references it as "pless-s-port" and backendRefs takes a PortNumber, so
+    # this reference cannot be made by name and the 80 below has to track
+    # paperless.service.yaml by hand. Three different names describe the same
+    # hop in this chart (service port "pless-s-port", targetPort
+    # "paperless-port", container port), which is exactly why the number is
+    # kept under a test rather than under review:
+    # ci/run-httproute-match-test.sh 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 }}

paperless-ngx/templates/paperless.ingress.yaml

@@ -1,3 +1,22 @@
+{{/*
+THIS CHART GAINED AN ingress.enabled SWITCH WITH THE GATEWAY-API SWEEP (#114),
+AND IT IS THE ONLY CHART IN THE REPOSITORY THAT WAS STILL MISSING ONE.
+
+It defaults to true, so an existing release renders byte-identically and the
+addition is additive. It is not cosmetic uniformity: the Gateway mode is
+defined as mutually exclusive with the Ingress, the render abort has to name
+BOTH value paths, and there was no second path to name. Worse, without the
+switch the Ingress would keep rendering in Gateway mode, and with it the
+unconditional required() on ingress.clusterIssuer below - a value that demands
+to be set and then does nothing, which is the defect README guideline 12 and
+issue #114's "Folge 1" exist to remove. The switch is what makes that required()
+conditional, exactly as every other chart here has it.
+
+What does NOT become optional with the Ingress off: ingress.domain. It is also
+PAPERLESS_URL (paperless-server.sfs.yaml), the only origin this release
+declares to Django, and it therefore carries its own required() there.
+*/}}
+{{- if .Values.ingress.enabled }}
 apiVersion: networking.k8s.io/v1
 kind: Ingress
 metadata:
@@ -25,4 +44,5 @@ spec:
   tls:
     - hosts:
         - {{ required "A Domain/Host must be provided" .Values.ingress.domain }}
-      secretName: tls-{{ .Release.Name }}-{{ .Chart.Name }}-ingress
+      secretName: tls-{{ .Release.Name }}-{{ .Chart.Name }}-ingress
+{{- end }}

paperless-ngx/values.schema.json

@@ -79,6 +79,10 @@
       "type": "object",
       "additionalProperties": false,
       "properties": {
+        "enabled": {
+          "description": "Gates the whole Ingress template. Added with the Gateway-API mode (Gitea #114), defaulting to true - this chart used to render its Ingress unconditionally, which left no second value path for the mutual-exclusion abort to name and kept the required() on clusterIssuer demanding a value the Gateway mode does not use. Mutually exclusive with httpRoute.enabled - the render aborts when both are true, and since this defaults to true it has to be switched off explicitly. false makes clusterIssuer unnecessary but NOT domain, which is also PAPERLESS_URL and carries its own required() in the StatefulSet.",
+          "type": "boolean"
+        },
         "clusterIssuer": {
           "type": ["string", "null"]
         },
@@ -89,11 +93,35 @@
           "type": ["string", "null"]
         },
         "annotations": {
-          "description": "Extra Ingress annotations, merged with the cert-manager and upload-size annotations the chart always sets. Free-form keys by nature.",
+          "description": "Extra Ingress annotations, merged with the cert-manager and upload-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 paperless.files.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, and ingress.enabled defaults to true in this chart. 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. paperless.files.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 PAPERLESS_URL, which keeps following ingress.domain - so Django refuses every login POST from the new name as a CSRF failure until both are set.",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
     "paperless": {
       "type": "object",
       "additionalProperties": false,
@@ -158,6 +186,7 @@
               "type": ["string", "null"]
             },
             "maxUploadFileSize": {
+              "description": "Rendered into the ingress-nginx proxy-body-size and nginx.org/client-max-body-size annotations, so it caps web-UI uploads at the ingress controller and nowhere inside paperless. 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 ceiling is the Gateway's, and this chart deliberately renders no implementation-specific policy object to set it. The consume directory is unaffected in every mode - it passes no proxy and has no limit.",
               "type": ["string", "null"]
             },
             "barcodes": {
@@ -321,6 +350,11 @@
     }
   },
   "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"],

paperless-ngx/values.yaml

@@ -16,13 +16,88 @@ secrets:
   oidcSecretRef: null
 
 ingress:
+  # Set to false to omit the Ingress entirely. NEW in the chart version that
+  # added the httpRoute block below (Gitea #114): this chart used to render its
+  # Ingress unconditionally, which is why it has no issue-#93 switch like the
+  # rest. The default is true, so an existing release is unaffected.
+  #
+  # It was not added for uniformity. Without it the Ingress would keep
+  # rendering in Gateway mode, and with it the required() on clusterIssuer -
+  # a value demanded for something the chart then does not render. With the
+  # switch that required() is conditional, as everywhere else here.
+  #
+  # clusterIssuer becomes unnecessary with the Ingress off. ingress.domain does
+  # NOT: it is also PAPERLESS_URL, the only origin this release declares to
+  # Django, and it carries its own required() in the StatefulSet.
+  #
+  # Mutually exclusive with httpRoute.enabled below: with both true the render
+  # aborts, naming both values. Mind that enabled defaults to TRUE here, so
+  # turning the Gateway mode on means switching this off in the same values
+  # file.
+  enabled: true
   clusterIssuer: null
+  # The public hostname of this release. Read by the Ingress, by PAPERLESS_URL
+  # 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 paperless.files.maxUploadFileSize.
   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 - and ingress.enabled defaults to true, so it
+# has to be switched off explicitly.
+#
+# 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: paperless.files.maxUploadFileSize is not enforced,
+# so the web UI's upload ceiling is the Gateway's. The consume directory is
+# unaffected - it passes no proxy and has no limit at all.
+#
+# 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 PAPERLESS_URL
+  # with it: Django keeps trusting the origin built from ingress.domain, and
+  # every login POST from the new name is refused as a CSRF failure until that
+  # value is changed too (and the pods restarted).
+  hostnames: []
+
 paperless:
   # Replica count for this workload; 0 is allowed and scales it down.
   # The chart-global scaleDown flag takes precedence.

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: []