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

Group 1 of the #114 sweep: the charts that render exactly one Ingress object
and set no behaviour-bearing nginx annotation - bentopdf, garage, patchmon,
rallly, searxng, sure, urlaubsverwaltung, voucher-vault.

Each gets the form the pilot (cyberchef, PR #115) fixed and template-chart
carries: an httpRoute block (enabled/parentRefs/hostnames, 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 seven of the eight, and for sure
identical in every rendered value (the diff is two YAML comment lines).

Three findings that were not in the plan, each argued in the file it changes:

  sure derived RAILS_ASSUME_SSL/RAILS_FORCE_SSL from ingress.enabled alone.
  Gateway mode sets that false by construction while TLS is still terminated at
  the Gateway, so both flags would have gone false: insecure cookies, no HSTS,
  http:// links, with a Ready pod and a working UI as the only symptom. They now
  read sure.publishedOverTls (ingress.enabled OR httpRoute.enabled), which is
  ingress.enabled while httpRoute.enabled is false - hence still Minor.

  garage claimed, in its Ingress template and its schema, that nothing outside
  that template reads ingress.domain. The HTTPRoute reads it, so the claim now
  holds only while both modes are off. Corrected rather than left standing.

  garage also depends on an upload limit it does not set: its annotations
  comment tells the operator to set proxy-body-size: "0" because ingress-nginx
  truncates S3 uploads at 1 MB. proxy-body-size has no Gateway-API counterpart,
  so its Gateway-mode NOTES prints that the limit is the Gateway's. README's
  list of affected charts named five and now names garage as a sixth.

clusterIssuer needed no change in any of the eight: its only required() sits
inside the Ingress template behind ingress.enabled, the same no-op the pilot
found. Annotation guidance that stops applying in Gateway mode moved into the
Gateway branch of NOTES.txt for bentopdf (X-Robots-Tag) and searxng
(forward-auth).

CI: one render overlay per chart under ci/httproute/, so the assertion is not
vacuum-green - ci/run-httproute-match-test.sh goes from 4 held assertions over
2 charts to 20 over 10. 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 garage the Ingress is the only place
its Service port is referenced by NAME.

Not proven, by construction: that traffic flows. No Gateway controller runs in
CI. Not run locally either: k3d, Docker, Trivy.

Part of #114

bentopdf/Chart.yaml

@@ -5,7 +5,7 @@ icon: https://raw.githubusercontent.com/alam00000/bentopdf/main/public/images/fa
 
 type: application
 
-version: 1.0.3+up2.8.8
+version: 1.1.0+up2.8.8
 appVersion: "2.8.8"
 
 maintainers:

bentopdf/templates/NOTES.txt

@@ -1,9 +1,14 @@
 {{- $replicas := include "bentopdf.replicas" (dict "scaleDown" .Values.scaleDown "replicas" .Values.bentopdf.replicas) -}}
+{{- $httpRoute := .Values.httpRoute | default dict -}}
+{{- $hostnames := $httpRoute.hostnames | default list -}}
+{{- if not $hostnames -}}
+{{- $hostnames = list .Values.ingress.domain -}}
+{{- end -}}
 BentoPDF {{ .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 }}"
@@ -13,24 +18,74 @@ ACCESS
 
   This chart has no secrets and no volumes — the two ingress values above are
   everything an installation needs.
+{{- 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 of them is
+  missing the hostname above simply does not answer:
+
+    1. The Gateway-API CRDs. Without them this install would have failed, so
+       they are present — nothing to check.
+    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 is
+       visible 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 what a working attachment looks like. 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 here, so there is no
+       tls-{{ .Release.Name }}-{{ .Chart.Name }}-ingress secret and nothing for cert-manager to do
+       on behalf of this release.
+
+  AND TWO THINGS THIS MODE TAKES AWAY FROM YOU, both because the Gateway API
+  has no annotation channel and this chart renders no implementation-specific
+  policy object on purpose:
+
+    * THE X-Robots-Tag HEADER. A publicly reachable instance gets indexed, and
+      its pages carry a canonical link to the vendor's site. In Ingress mode
+      ingress.annotations is the lever (see values.yaml); here there is none in
+      the chart at all — the header has to be added at the Gateway, or the
+      instance has to not be public.
+    * THE REPAIR FOR A PROXY THAT MANGLES RESPONSES. See the two notes below on
+      the cross-origin headers and on .mjs; in this mode neither can be fixed
+      from this chart.
 {{- else }}
 
-ACCESS — NO INGRESS
-  ingress.enabled is false, so this release has no Ingress and no certificate;
-  ingress.domain and ingress.clusterIssuer are not needed. The app is only
-  reachable inside the cluster, as
+ACCESS — NEITHER INGRESS NOR HTTPROUTE
+  ingress.enabled and httpRoute.enabled are both false, so this release has no
+  Ingress, no HTTPRoute and no certificate; ingress.domain and
+  ingress.clusterIssuer are not needed. The app is only 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 8080:80
 
-  Then browse to http://localhost:8080. Set ingress.enabled=true together with
-  ingress.domain and ingress.clusterIssuer to publish it instead.
+  Then browse to http://localhost:8080. To publish it instead, set either
+  ingress.enabled=true with ingress.domain and ingress.clusterIssuer, or
+  httpRoute.enabled=true with ingress.domain and httpRoute.parentRefs.
 {{- end }}
 {{ if eq $replicas "0" }}
 SCALED TO ZERO
   {{ if .Values.scaleDown }}scaleDown: true{{ else }}bentopdf.replicas: 0{{ end }} — the deployment runs with replicas: 0, so the endpoint
   above does not answer until you set it back and upgrade again. Service{{ if .Values.ingress.enabled }} and
-  Ingress stay in place, so the certificate is not re-issued.{{ else }} stays in
+  Ingress stay in place, so the certificate is not re-issued.{{ else if $httpRoute.enabled }} and
+  HTTPRoute stay in place, so the route keeps pointing at a Service with no
+  endpoints — the Gateway answers with an error of its own rather than with
+  nothing.{{ else }} stays in
   place.{{ end }}
 {{ end }}
 A GREEN POD ONLY PROVES DELIVERY
@@ -40,21 +95,40 @@ A GREEN POD ONLY PROVES DELIVERY
   handing out index.html — no more. Whether PDF processing works is a
   question about the browser, not about this release.
 
-TWO HEADERS HAVE TO SURVIVE YOUR INGRESS CONTROLLER
+TWO HEADERS HAVE TO SURVIVE YOUR PROXY
   The image sends Cross-Origin-Opener-Policy: same-origin and
   Cross-Origin-Embedder-Policy: credentialless. Without both arriving at the
   browser there is no SharedArrayBuffer, and the LibreOffice-backed
   conversions (Word, Excel, PowerPoint) fail while everything else keeps
-  working. Check them through the ingress, not at the pod:
+  working. Check them through the published URL, not at the pod:
 
-    curl -sI https://{{ if .Values.ingress.enabled }}{{ .Values.ingress.domain }}{{ else }}<host>{{ end }}/ | grep -i cross-origin
+    curl -sI https://{{ if .Values.ingress.enabled }}{{ .Values.ingress.domain }}{{ else if $httpRoute.enabled }}{{ first $hostnames }}{{ else }}<host>{{ end }}/ | grep -i cross-origin
+
+  The image sends them itself, so they arrive in both modes unless something
+  in the path strips or rewrites them. The difference is the repair: in Ingress
+  mode ingress.annotations can put them back, in Gateway mode that channel does
+  not exist and it is the Gateway's business. Same for the .mjs MIME type (see
+  values.yaml).
 
 ANYONE WHO REACHES THE URL CAN USE IT
+{{- if $httpRoute.enabled }}
+  BentoPDF has no login, and this chart adds none. That is defensible here —
+  the server takes nothing in, stores nothing and has no session — but a
+  public instance also gets indexed, and its pages carry a canonical link to
+  the vendor's site. In GATEWAY MODE there is no place in this chart for either
+  fix: the Gateway API has no annotation channel, so the X-Robots-Tag snippet
+  documented in values.yaml has NO counterpart here, and the chart renders no
+  implementation-specific policy object on purpose (it would bind the chart to
+  one Gateway implementation). Both have to happen at the Gateway — or the
+  instance must not be publicly reachable.
+{{- else }}
   BentoPDF has no login, and this chart adds none. That is defensible here —
   the server takes nothing in, stores nothing and has no session — but a
   public instance also gets indexed, and its pages carry a canonical link to
   the vendor's site. Both are addressed through ingress.annotations; see
-  values.yaml.
+  values.yaml. Note that this escape hatch exists in Ingress mode only:
+  httpRoute.enabled has no annotation channel at all.
+{{- end }}
 
 NOTHING TO BACK UP, NOTHING TO MIGRATE
   No database, no volumes, no uploads: documents never leave the visitor's

bentopdf/templates/bentopdf.httproute.yaml

@@ -0,0 +1,90 @@
+{{/*
+The Gateway-API alternative to bentopdf.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.
+
+WHAT THIS CHART IN PARTICULAR LOSES IN THIS MODE, AND IT IS NOT NOTHING
+
+ingress.annotations is BentoPDF's only lever for two things it cannot do
+itself, and the Gateway API has no annotation channel at all:
+
+  * the X-Robots-Tag header that keeps a public instance out of search
+    indexes (ROBOTS_NOINDEX cannot run on a read-only root filesystem, and
+    every page carries a canonical link to the vendor's domain), and
+  * the repair for controllers that override the MIME type of .mjs files or
+    strip Cross-Origin-Opener-Policy / Cross-Origin-Embedder-Policy.
+
+None of that is rebuilt here - a policy object would bind the chart to one
+implementation. NOTES.txt says so in this mode instead of leaving it to be
+discovered on a search-results page. The two cross-origin headers are sent by
+the image itself and still arrive unless something strips them, so they are a
+thing to CHECK (see NOTES.txt) rather than a thing to configure.
+
+ingress.clusterIssuer is meaningless here - this chart renders no Certificate
+in this mode - and it is not demanded either: its only required() sits inside
+bentopdf.ingress.yaml, behind ingress.enabled.
+*/}}
+{{- /*
+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.
+
+Checked for THIS chart rather than copied: nothing outside bentopdf.ingress.yaml
+and this file reads ingress.domain - BentoPDF is a static bundle and is handed
+no base URL - so with both routing modes off, domain is genuinely free. In
+Gateway mode this required() is the one that fires.
+*/ -}}
+{{- $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 - BentoPDF is served at the root and has no second path.
+    # 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
+    # bentopdf.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 }}

bentopdf/values.schema.json

@@ -49,6 +49,7 @@
       "additionalProperties": false,
       "properties": {
         "enabled": {
+          "description": "Gates the whole Ingress template. Mutually exclusive with httpRoute.enabled - the render aborts when both are true. It does not free ingress.domain by itself: the HTTPRoute reads that value too, so domain is only unnecessary while BOTH routing modes are off. clusterIssuer is read by the Ingress alone.",
           "type": "boolean"
         },
         "clusterIssuer": {
@@ -61,13 +62,42 @@
           "type": ["string", "null"]
         },
         "annotations": {
-          "description": "Extra Ingress annotations, merged with the cert-manager annotation the chart always sets. Free-form keys by nature.",
+          "description": "Extra Ingress annotations, merged with the cert-manager annotation 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 X-Robots-Tag snippet that is this chart's only lever against being indexed.",
           "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.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": {
+          "type": "boolean"
+        },
+        "parentRefs": {
+          "description": "The Gateway(s) the route attaches to. Required while httpRoute.enabled is true, enforced by required()-equivalent 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.",
+          "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"],

bentopdf/values.yaml

@@ -174,13 +174,30 @@ ingress:
   # read inside the Ingress template - unlike searxng, this chart has no
   # second reader of ingress.domain: the upstream counterpart BASE_URL is a
   # build-time argument and empty in the published image).
+  #
+  # Mutually exclusive with httpRoute.enabled below (Gitea #114): with both
+  # true the render aborts, naming both values. In Gateway mode ingress.domain
+  # is read again - by the HTTPRoute, as its single hostname - so "both modes
+  # off" is what frees it, not "ingress off".
   enabled: true
   clusterIssuer: null
+  # The public hostname of this release. Read by the Ingress AND - when
+  # httpRoute.hostnames is empty - by the HTTPRoute, so it stays the single
+  # source of truth for the hostname in both modes.
   domain: null
   className: nginx
   # Extra annotations for the Ingress; merged with the cert-manager
   # cluster-issuer annotation the chart always sets.
   #
+  # THESE HAVE NO COUNTERPART IN GATEWAY MODE, AND FOR THIS CHART THAT COSTS
+  # SOMETHING CONCRETE. The Gateway API has no annotation channel for
+  # controller behaviour, so both uses documented below - the X-Robots-Tag
+  # header and any repair for a controller that mangles the headers or the
+  # .mjs MIME type - are simply gone when httpRoute.enabled is used instead.
+  # The chart does not rebuild them: a policy object would bind it to one
+  # Gateway implementation. It is then the Gateway's business. NOTES.txt says
+  # so in that mode.
+  #
   # TWO HEADERS MUST SURVIVE THE PROXY, OR OFFICE CONVERSION BREAKS. The image
   # sends Cross-Origin-Opener-Policy: same-origin and
   # Cross-Origin-Embedder-Policy: credentialless. Together they make the page
@@ -212,6 +229,48 @@ ingress:
   # add-headers ConfigMap is the alternative.
   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.
+#
+# 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.
+#
+# WHAT THIS MODE COSTS HERE: the whole ingress.annotations escape hatch above,
+# including the X-Robots-Tag header - a public instance in Gateway mode gets
+# indexed unless the Gateway adds the header. The two cross-origin headers are
+# a different case: the image sends them itself, so they still arrive in this
+# mode unless something in the path strips them (NOTES.txt has the curl).
+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.
+  hostnames: []
+
 # WHAT THIS CHART CANNOT DO
 #
 # Almost everything else about BentoPDF is a BUILD-TIME argument and therefore