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

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