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

rallly/Chart.yaml

@@ -5,7 +5,7 @@ icon: https://raw.githubusercontent.com/lukevella/rallly/main/apps/landing/publi
 
 type: application
 
-version: 8.1.8+up4.15.4
+version: 8.2.0+up4.15.4
 appVersion: "4.15.4"
 
 maintainers:

rallly/templates/NOTES.txt

@@ -6,11 +6,16 @@
 {{- $service := printf "%s-%s-service" .Release.Name .Chart.Name -}}
 {{- $envNames := list -}}
 {{- range $entry := .Values.rallly.env }}{{- $envNames = append $envNames $entry.name }}{{- end }}
+{{- $httpRoute := .Values.httpRoute | default dict -}}
+{{- $hostnames := $httpRoute.hostnames | default list -}}
+{{- if not $hostnames -}}
+{{- $hostnames = list .Values.ingress.domain -}}
+{{- end -}}
 Rallly {{ .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 }}"
@@ -18,11 +23,50 @@ ACCESS
   it with
 
     kubectl -n {{ .Release.Namespace }} get certificate tls-{{ .Release.Name }}-{{ .Chart.Name }}-ingress
+{{- else if $httpRoute.enabled }}
+
+ACCESS — GATEWAY MODE (httpRoute.enabled: true, ingress.enabled: false)
+{{- range $hostnames }}
+  https://{{ . }}
+{{- end }}
+
+  This release renders an HTTPRoute ({{ .Release.Name }}-{{ .Chart.Name }}-httproute) and NOTHING else
+  of the routing path — no Gateway, no class, no Certificate. Three things
+  therefore belong to the cluster and not to this chart:
+
+    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.annotations is inert in this mode — the Gateway API has no annotation
+  channel — and nothing this chart needs lives there.
+
+  MIND THE HOSTNAME IN THIS MODE. NEXT_PUBLIC_BASE_URL still follows
+  ingress.domain ("https://{{ .Values.ingress.domain }}"), not httpRoute.hostnames, and the OIDC
+  redirect URI registered at the provider is built from it. Publishing under a
+  name that ingress.domain does not carry gives you an instance whose links and
+  sign-in all leave for the other host.
 {{- else }}
 
-ACCESS — NO INGRESS
-  ingress.enabled is false, so this release has no Ingress and no certificate;
-  ingress.clusterIssuer is not needed. ingress.domain still is — see below.
+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.clusterIssuer is not
+  needed. ingress.domain still is — see below.
 
     kubectl -n {{ .Release.Namespace }} port-forward svc/{{ $service }} 3000:80
 
@@ -34,7 +78,8 @@ ACCESS — NO INGRESS
 
   ingress.domain is not only the Ingress host. The chart passes it to the app as
   NEXT_PUBLIC_BASE_URL — upstream's "fully qualified public URL of your
-  instance" — which is why it stays required with the Ingress switched off.
+  instance" — which is why it stays required in every mode, with the Ingress
+  switched off and in Gateway mode alike.
 
 SIGN-IN GOES THROUGH THE PROVIDER, AND ONLY THROUGH THE PROVIDER
   This chart sets EMAIL_LOGIN_ENABLED and REGISTRATION_ENABLED to "false" in the
@@ -172,12 +217,18 @@ THE CACHE VOLUME COUNTS AGAINST THE EPHEMERAL-STORAGE LIMIT
   is rebuilt on demand, at the cost of a slower first request.
 
 CHANGING THE DOMAIN LATER IS A CHANGE ON TWO SIDES
-  ingress.domain is the Ingress host, the app's NEXT_PUBLIC_BASE_URL and
+  ingress.domain is the published host, the app's NEXT_PUBLIC_BASE_URL and
   therefore the OIDC redirect URI in one value. Editing it here alone breaks the
   login: the provider refuses a callback it was never told about, and it is the
   provider that reports it — Kubernetes reports a healthy pod{{ if .Values.ingress.enabled }} and a valid
-  certificate for the new name{{ end }}. Register the new redirect URI first, then
-  upgrade.
+  certificate for the new name{{ else if $httpRoute.enabled }} and an accepted
+  route{{ end }}. Register the new redirect URI first, then upgrade.
+{{- if $httpRoute.enabled }}
+  In GATEWAY MODE there is a third side: httpRoute.hostnames, which is what the
+  route actually publishes. It does not follow ingress.domain once set
+  explicitly, so a migration over a second hostname means the provider, the
+  route and ingress.domain all have to end up agreeing.
+{{- end }}
 {{- if $envNames }}
 
 rallly.env ADDS {{ len $envNames }} VARIABLE(S): {{ join ", " $envNames }}
@@ -191,5 +242,5 @@ rallly.env ADDS {{ len $envNames }} VARIABLE(S): {{ join ", " $envNames }}
 SCALED TO ZERO
   {{ if .Values.scaleDown }}scaleDown: true{{ else }}rallly.replicas: 0{{ end }} — the Deployment runs with replicas: 0, so nothing answers
   until you set it back and upgrade again. Secrets and Service{{ if .Values.ingress.enabled }}, and the Ingress
-  with its certificate,{{ end }} stay in place.
+  with its certificate,{{ else if $httpRoute.enabled }}, and the HTTPRoute,{{ end }} stay in place.
 {{- end }}

rallly/templates/rallly.httproute.yaml

@@ -0,0 +1,82 @@
+{{/*
+The Gateway-API alternative to rallly.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
+rallly.ingress.yaml, behind ingress.enabled.
+
+ingress.domain IS STILL REQUIRED, AND NOT BECAUSE OF THIS FILE
+
+Checked for this chart rather than copied: rallly.deployment.yaml reads
+ingress.domain with its own required() to build NEXT_PUBLIC_BASE_URL, which
+Rallly bakes into every invitation mail and every OIDC redirect. So domain is
+mandatory in every mode of this chart and the fallback below is never the only
+reader.
+
+That also means the hostname is not a routing detail here: it is registered at
+the identity provider as the callback URL. Changing it - including by setting
+httpRoute.hostnames to a second name for a migration - needs the provider
+updated too, or logins fail with a redirect-uri mismatch while the pod stays
+green. NOTES.txt says this for both modes.
+*/}}
+{{- /*
+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 does NOT move NEXT_PUBLIC_BASE_URL, which keeps following
+ingress.domain - see the header: for this chart the two belong together.
+*/ -}}
+{{- $hostnames := $httpRoute.hostnames | default list -}}
+{{- if not $hostnames -}}
+{{- $hostnames = list (required "A Domain/Host must be provided: set ingress.domain (used as the HTTPRoute's single hostname when httpRoute.hostnames is empty) or set httpRoute.hostnames explicitly" .Values.ingress.domain) -}}
+{{- end -}}
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+  name: {{ .Release.Name }}-{{ .Chart.Name }}-httproute
+spec:
+  parentRefs:
+    {{- toYaml $parentRefs | nindent 4 }}
+  hostnames:
+    {{- toYaml $hostnames | nindent 4 }}
+  rules:
+    # The Ingress counterpart is `path: / , pathType: Prefix` on the one
+    # backend Service - the Next.js server serves the app, its API routes and
+    # /api/auth/* 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 rallly.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 }}

rallly/values.schema.json

@@ -113,7 +113,7 @@
       "additionalProperties": false,
       "properties": {
         "enabled": {
-          "description": "Gates the whole Ingress template (issue #93). false omits the Ingress and makes clusterIssuer unnecessary - but NOT domain, which is also the app's public base URL.",
+          "description": "Gates the whole Ingress template (issue #93). Mutually exclusive with httpRoute.enabled - the render aborts when both are true. false omits the Ingress and makes clusterIssuer unnecessary - but NOT domain, which is also the app's public base URL.",
           "type": "boolean"
         },
         "clusterIssuer": {
@@ -126,13 +126,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.",
           "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 NEXT_PUBLIC_BASE_URL or the OIDC redirect URI, which keep following ingress.domain.",
+          "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"],

rallly/values.yaml

@@ -125,10 +125,64 @@ ingress:
   # required even then: it is also the app's public base URL
   # (NEXT_PUBLIC_BASE_URL), not just the Ingress host. Only clusterIssuer
   # becomes unnecessary.
+  #
+  # Mutually exclusive with httpRoute.enabled below (Gitea #114): with both
+  # true the render aborts, naming both values.
   enabled: true
   clusterIssuer: null
+  # The public hostname of this release. Read by the Ingress, by
+  # NEXT_PUBLIC_BASE_URL, 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 by default.
   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
+  # NEXT_PUBLIC_BASE_URL with it, and that the OIDC redirect URI registered at
+  # the provider is built from ingress.domain - a new name needs both sides
+  # updated or logins fail on a redirect-uri mismatch while the pod stays green.
+  hostnames: []