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

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.