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

patchmon/Chart.yaml

@@ -5,7 +5,7 @@ icon: https://raw.githubusercontent.com/PatchMon/PatchMon/main/frontend/public/a
 
 type: application
 
-version: 7.0.2+up2.1.3
+version: 7.1.0+up2.1.3
 appVersion: "2.1.3"
 
 maintainers:

patchmon/templates/NOTES.txt

@@ -4,21 +4,65 @@
 {{- $startup := fromYaml (include "patchmon.server.startupProbe" (dict "given" .Values.patchmon.server.startupProbe "root" $)) -}}
 {{- $budget := mul (int $startup.periodSeconds) (int $startup.failureThreshold) -}}
 {{- $name := printf "%s-%s" .Release.Name .Chart.Name -}}
+{{- $httpRoute := .Values.httpRoute | default dict -}}
+{{- $hostnames := $httpRoute.hostnames | default list -}}
+{{- if not $hostnames -}}
+{{- $hostnames = list .Values.ingress.domain -}}
+{{- end -}}
 PatchMon {{ .Chart.AppVersion }} — release {{ .Release.Name }} in namespace {{ .Release.Namespace }}.
 
 ACCESS
 {{- if .Values.ingress.enabled }}
+  INGRESS MODE (ingress.enabled: true, httpRoute.enabled: false)
   https://{{ .Values.ingress.domain }}
 
   While cert-manager is still issuing the certificate the browser warns:
 
     kubectl -n {{ .Release.Namespace }} get certificate tls-{{ $name }}-ingress
+{{- else if $httpRoute.enabled }}
+  GATEWAY MODE (httpRoute.enabled: true, ingress.enabled: false)
+{{- range $hostnames }}
+  https://{{ . }}
+{{- end }}
+
+  This release renders an HTTPRoute ({{ $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:
+
+    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 {{ $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-{{ $name }}-ingress
+       secret and nothing for cert-manager to do.
+
+  ingress.domain is still required in this mode and is {{ .Values.ingress.domain }}: it builds
+  CORS_ORIGIN and the probes' Host header, neither of which the route replaces.
+  If you set httpRoute.hostnames to a name ingress.domain does not carry, the
+  server answers that name with a rejection — set both together.
+
+  ingress.annotations is inert in this mode: the Gateway API has no annotation
+  channel. Nothing this chart needs lives there, though — the WebSocket upgrade
+  works on a plain route, and TRUST_PROXY stays correct behind a Gateway.
 {{- else }}
-  ingress.enabled is false, so there is no Ingress. Reach it directly with
+  NEITHER INGRESS NOR HTTPROUTE — ingress.enabled and httpRoute.enabled are
+  both false, so this release is not published. Reach it directly with
 
     kubectl -n {{ .Release.Namespace }} port-forward svc/{{ $name }}-service 3000:80
 
-  ingress.domain stays required even without an Ingress — the server's
+  ingress.domain stays required even without either — the server's
   CORS_ORIGIN is built from it — and it is still {{ .Values.ingress.domain }} here. The server
   answers 403 to any Host header it does not know, so address it under that
   name rather than as plain localhost:
@@ -54,10 +98,10 @@ SIGN-IN IS OIDC-ONLY — THERE IS NO LOCAL ACCOUNT TO FALL BACK ON
   there is no built-in admin. If the OIDC item is wrong, nobody gets in —
   including you. Users are created on first login with the "readonly" role;
   admin rights follow the group named in the item's admin-group-name field.
-  The item's redirect-uri has to point back at this installation{{ if .Values.ingress.enabled }} under
-  https://{{ .Values.ingress.domain }}{{ end }}, and it must match what is registered at the
+  The item's redirect-uri has to point back at this installation{{ if or .Values.ingress.enabled $httpRoute.enabled }} under
+  https://{{ first $hostnames }}{{ end }}, and it must match what is registered at the
   identity provider exactly.
-{{- if .Values.ingress.enabled }}
+{{- if or .Values.ingress.enabled $httpRoute.enabled }}
 
 A WRONG ingress.domain KEEPS THE POD OUT OF READY FOREVER
   The 2.x server answers 403 to any request whose Host header is neither
@@ -66,6 +110,11 @@ A WRONG ingress.domain KEEPS THE POD OUT OF READY FOREVER
   If that value is not the hostname the server is actually reached under, the
   probes get 403, the pod never turns Ready and nothing in the log looks like
   a configuration error — just repeated 403s.
+{{- if $httpRoute.enabled }}
+  In GATEWAY MODE that applies to httpRoute.hostnames as well: the route
+  publishes {{ join ", " $hostnames }}, while CORS_ORIGIN and the probes still
+  follow ingress.domain ({{ .Values.ingress.domain }}). The two have to agree.
+{{- end }}
 {{- end }}
 
 GIVE THE FIRST START TIME
@@ -94,7 +143,7 @@ GUACD SIDECAR IS ON
 
 SCALED TO ZERO
   {{ if .Values.scaleDown }}scaleDown: true{{ else }}patchmon.server.replicas: 0{{ end }} — the deployment runs with replicas: 0. Secrets,
-  Service{{ if .Values.ingress.enabled }} and Ingress{{ end }} stay in place, and the agents on your hosts keep
+  Service{{ if .Values.ingress.enabled }} and Ingress{{ else if $httpRoute.enabled }} and HTTPRoute{{ end }} stay in place, and the agents on your hosts keep
   retrying, so nothing is lost; they simply report nothing until you set it
   back and upgrade again.
 {{- end }}

patchmon/templates/patchmon.httproute.yaml

@@ -0,0 +1,93 @@
+{{/*
+The Gateway-API alternative to patchmon.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
+patchmon.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 twice more
+outside both routing templates. CORS_ORIGIN in patchmon.deployment.yaml carries
+its own required() and is therefore what makes domain mandatory in EVERY mode
+of this chart, Gateway mode included - the fallback below is never the only
+reader. The second read is the explicit "Host" header the probes send
+(patchmon.server.httpGet in _helpers.tpl), which deliberately uses
+`| default ""` and demands nothing itself, because the required() above has
+already fired by the time it runs.
+
+The consequence that matters in this mode is the one NOTES.txt already spells
+out for the Ingress: the 2.x server rejects requests whose Host is neither
+loopback nor a CORS_ORIGIN host, so a domain the app does not answer on keeps
+the pod out of Ready forever. Nothing about that changes with a Gateway in
+front instead of an Ingress - and TRUST_PROXY stays right either way, since a
+Gateway is a reverse proxy too.
+
+WEBSOCKETS: nothing to configure, in either mode. The 2.x server serves the
+frontend, /api/* and its WebSocket upgrade from one process on one port, and
+the Gateway API passes an upgrade through on a plain HTTPRoute - there is no
+annotation involved in Ingress mode either.
+*/}}
+{{- /*
+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. Setting httpRoute.hostnames
+explicitly is what a migration over a second hostname needs - but mind that it
+does NOT move CORS_ORIGIN or the probes' Host header, which keep following
+ingress.domain. For this chart the two therefore have to be set together, or
+the app rejects the browser's requests from the new name.
+*/ -}}
+{{- $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 - the 2.x server serves the frontend and /api/* from one
+    # process, so a single path covers everything. 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 patchmon.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 }}

patchmon/values.schema.json

@@ -91,7 +91,7 @@
       "additionalProperties": false,
       "properties": {
         "enabled": {
-          "description": "Gates the whole Ingress template (issue #93). false omits the Ingress, and the required domain/clusterIssuer values are then not needed either.",
+          "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: that value also builds CORS_ORIGIN and the probes' Host header, keeps its own required() there and therefore stays mandatory in every mode (the earlier wording lumped the two together, which was wrong).",
           "type": "boolean"
         },
         "clusterIssuer": {
@@ -104,11 +104,35 @@
           "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. Nothing the chart needs lives here - the WebSocket upgrade works on a plain route and TRUST_PROXY is an environment variable.",
           "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. A hostname set here does not move CORS_ORIGIN or the probes' Host header, which keep following ingress.domain.",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
     "secrets": {
       "type": "object",
       "additionalProperties": false,
@@ -129,6 +153,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"],

patchmon/values.yaml

@@ -147,17 +147,78 @@ patchmon:
     env: []
 
 ingress:
-  # Set to false to omit the Ingress entirely (the required domain and
-  # clusterIssuer values are then not needed either, because they are only
-  # read inside the Ingress template).
+  # 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 and the comment here used to lump the
+  # two together, which was wrong: it is read twice MORE outside the Ingress -
+  # CORS_ORIGIN in the Deployment (with its own required()) and the explicit
+  # Host header the probes send - so it stays mandatory with the Ingress off.
+  # The 2.x server rejects requests whose Host is neither loopback nor a
+  # CORS_ORIGIN host, so an empty value keeps the pod out of Ready forever.
+  #
+  # 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 CORS_ORIGIN,
+  # by the probes' Host header, and - when httpRoute.hostnames is empty - by
+  # the HTTPRoute. Required in every mode (see above).
   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. 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. Nothing this chart NEEDS lives
+  # here: the server's WebSocket upgrade works on a plain route, and TRUST_PROXY
+  # is an environment variable, not an annotation.
   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.
+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 CORS_ORIGIN or
+  # the probes' Host header with it: both keep following ingress.domain, and
+  # the server answers the new name with a rejection until ingress.domain names
+  # it too.
+  hostnames: []
+
 secrets:
   redisSecretRef: null
   postgresSecretRef: null