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

garage/Chart.yaml

@@ -19,7 +19,7 @@ type: application
 # offer those as "updates", which is why the garage block in renovate.json5
 # carries a versioningTemplate anchored to ^v<major>.<minor>.<patch>$ - same
 # shape as the stalwart block, for the same reason.
-version: 1.0.0+upv2.4.1
+version: 1.1.0+upv2.4.1
 appVersion: "v2.4.1"
 
 maintainers:

garage/templates/NOTES.txt

@@ -1,6 +1,11 @@
 {{- $settings := fromYaml (include "garage.settings" .) -}}
 {{- $pod := printf "%s-%s-sfs-0" .Release.Name .Chart.Name -}}
 {{- $svc := printf "%s-%s-service" .Release.Name .Chart.Name -}}
+{{- $httpRoute := .Values.httpRoute | default dict -}}
+{{- $hostnames := $httpRoute.hostnames | default list -}}
+{{- if not $hostnames -}}
+{{- $hostnames = list .Values.ingress.domain -}}
+{{- end -}}
 Garage {{ .Chart.AppVersion }} installed as release {{ .Release.Name }} in namespace {{ .Release.Namespace }}.
 
 ONE node, replication_factor = {{ $settings.replicationFactor | int64 }}, metadata engine {{ $settings.dbEngine }}.
@@ -9,7 +14,64 @@ S3 ENDPOINT (in-cluster, path-style addressing):
   http://{{ $svc }}.{{ .Release.Namespace }}.svc.cluster.local:{{ $settings.ports.s3 | int64 }}
   region: {{ $settings.s3.region }}
 {{- if .Values.ingress.enabled }}
-  published at: https://{{ .Values.ingress.domain }}
+  published at: https://{{ .Values.ingress.domain }}   (INGRESS MODE)
+{{- else if $httpRoute.enabled }}
+{{- range $hostnames }}
+  published at: https://{{ . }}   (GATEWAY MODE)
+{{- end }}
+{{- end }}
+
+{{- if .Values.ingress.enabled }}
+
+PUBLISHED THROUGH AN INGRESS (ingress.enabled: true, httpRoute.enabled: false)
+  The certificate is requested by cert-manager through the "{{ .Values.ingress.clusterIssuer }}"
+  cluster issuer:
+
+    kubectl -n {{ .Release.Namespace }} get certificate tls-{{ .Release.Name }}-{{ .Chart.Name }}-ingress
+
+  The Ingress references the Service's s3 port BY NAME, so the port number
+  never has to be kept in step by hand here.
+{{- else if $httpRoute.enabled }}
+
+PUBLISHED THROUGH AN HTTPROUTE (httpRoute.enabled: true, ingress.enabled: false)
+  This release renders an HTTPRoute ({{ .Release.Name }}-{{ .Chart.Name }}-httproute) pointing at the
+  Service's s3 port ({{ $settings.ports.s3 | int64 }}) and NOTHING else of the routing path — no
+  Gateway, no class, no Certificate. So three things belong to the cluster and
+  not to this chart, and if any is missing the hostname 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.
+
+  YOUR UPLOAD LIMIT IS NOW THE GATEWAY'S, AND THIS IS AN OBJECT STORE.
+  In Ingress mode the advice is nginx.ingress.kubernetes.io/proxy-body-size: "0"
+  via ingress.annotations, because the controller's 1m default truncates
+  uploads. The Gateway API has NO counterpart — it knows no body size at all,
+  that is implementation-specific policy — and this chart deliberately renders
+  no policy object, which would bind it to one implementation. So whatever
+  limit the Gateway has is the limit your S3 PUTs get, and the symptom is
+  uploads failing by size rather than by permission. Raise it at the Gateway
+  or at its implementation's own policy object, next to the Gateway and not
+  here.
+
+  Mind also that the route carries the port NUMBER ({{ $settings.ports.s3 | int64 }}), not the name
+  "s3": an HTTPRoute backendRef takes a PortNumber. The chart renders it from
+  the same garage.ports.s3 value the Service uses, so the two cannot drift.
 {{- end }}
 {{- if $settings.web.enabled }}
   static website endpoint on port {{ $settings.ports.web | int64 }}{{ with $settings.web.rootDomain }} (root domain {{ . }}){{ else }} - WITHOUT a rootDomain it serves nothing; set garage.web.rootDomain{{ end }}

garage/templates/garage.httproute.yaml

@@ -0,0 +1,105 @@
+{{/*
+The Gateway-API alternative to garage.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.
+
+OFF BY DEFAULT, AND SO IS THE INGRESS. This chart publishes nothing unless
+asked (ingress.enabled: false, httpRoute.enabled: false), because the consumer
+it was built for speaks S3 inside the cluster. Both routing modes are therefore
+a values change, and both expose THE S3 API - not a web UI. Garage's admin API
+is JSON and its authenticated half is closed in this chart, and the project's
+web interface is a separate program that is not in this image. Whoever turns
+either mode on is putting an S3 endpoint on the internet; it authenticates
+every request with a signature, and the credentials are the two fields of the
+s3 vault item.
+
+WHAT CHANGES FOR ingress.domain, AND IT IS THE ONE CLAIM THIS FILE INVALIDATES
+
+garage.ingress.yaml used to be able to say that NOTHING outside it reads
+ingress.domain, so that switching the Ingress off freed domain as well as
+clusterIssuer. This file is now a second reader (when httpRoute.hostnames is
+empty), so the sentence holds only while BOTH modes are off. That is corrected
+in that template's header and in values.schema.json rather than left standing.
+
+Unchanged: garage.s3.rootDomain is still its own value and still not coupled to
+ingress.domain. A wildcard vhost suffix for bucket addressing and the single
+host a route answers on are different things, and the Gateway API does not make
+them the same.
+
+ingress.clusterIssuer is meaningless here - this chart renders no Certificate
+in this mode - and it is not demanded either: its only required() sits inside
+garage.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 -}}
+{{- $settings := fromYaml (include "garage.settings" .) -}}
+{{- $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.
+*/ -}}
+{{- $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
+  labels:
+    app: {{ .Release.Name }}-{{ .Chart.Name }}-sfs
+spec:
+  parentRefs:
+    {{- toYaml $parentRefs | nindent 4 }}
+  hostnames:
+    {{- toYaml $hostnames | nindent 4 }}
+  rules:
+    # The Ingress counterpart is `path: / , pathType: Prefix` on the S3 port of
+    # the one Service.
+    #
+    # THE PORT IS WHERE THIS CHART DIFFERS FROM EVERY OTHER ONE IN THE SWEEP.
+    # backendRefs takes a PortNumber and cannot name a port, while
+    # garage.ingress.yaml references it BY NAME ("s3") and is therefore immune
+    # to the number changing. Here the number has to be rendered - and
+    # garage.ports.s3 is a value, so a literal 3900 would be a lie the moment
+    # anyone changes it. It comes out of the same garage.settings helper that
+    # garage.service.yaml renders its port from, which is what keeps the two
+    # in step by construction instead of by hand.
+    #
+    # The admin port is deliberately NOT routed: with this chart's config it
+    # serves /health and /metrics without authentication and answers everything
+    # else 401/403. That is a monitoring surface for the cluster, not something
+    # to publish.
+    #
+    # ci/run-httproute-match-test.sh holds the pair either way - 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: {{ $settings.ports.s3 | int64 }}
+{{- end }}

garage/templates/garage.ingress.yaml

@@ -5,11 +5,17 @@ values exist anyway, built to this repo's ingress convention, so that
 publishing the endpoint later is a values change rather than a chart change.
 
 GUIDELINE 1, CHECKED IN BOTH DIRECTIONS (README, "Values that must not lie"):
-nothing outside this template reads ingress.domain. The S3 API's vhost-style
-suffix is its own value, garage.s3.rootDomain, because the two are not the same
-thing - a wildcard vhost domain and the single host an Ingress answers on. So
-with the Ingress switched off, BOTH domain and clusterIssuer are free, and
-their required() lives here where it can actually fire.
+the S3 API's vhost-style suffix is its own value, garage.s3.rootDomain, because
+the two are not the same thing - a wildcard vhost domain and the single host a
+route answers on.
+
+This template used to be able to add "and nothing outside it reads
+ingress.domain", so that switching the Ingress off freed domain as well as
+clusterIssuer. SINCE #114 THAT IS NO LONGER TRUE: garage.httproute.yaml reads
+ingress.domain too, as its single hostname when httpRoute.hostnames is empty.
+So domain is free only while BOTH routing modes are off. clusterIssuer is
+unchanged - it is read nowhere but here, Gateway mode renders no Certificate,
+and its required() below still lives where it can actually fire.
 
 WHAT IT PUBLISHES: the S3 API. There is no web UI to expose - Garage's admin
 API is JSON and the authenticated half is closed in this chart (no token), and

garage/values.schema.json

@@ -114,7 +114,7 @@
               "minLength": 1
             },
             "rootDomain": {
-              "description": "Optional suffix for vhost-style bucket access. Deliberately not coupled to ingress.domain - the two are different things.",
+              "description": "Optional suffix for vhost-style bucket access. Deliberately not coupled to ingress.domain or httpRoute.hostnames - a wildcard vhost domain and the single host a route answers on are different things.",
               "type": ["string", "null"]
             }
           }
@@ -182,7 +182,7 @@
       "additionalProperties": false,
       "properties": {
         "enabled": {
-          "description": "Gates the whole Ingress template (issue #93). Checked in both directions for this chart: nothing outside that template reads ingress.domain, so switching the Ingress off frees domain as well as clusterIssuer.",
+          "description": "Gates the whole Ingress template (issue #93), and ships false. Mutually exclusive with httpRoute.enabled - the render aborts when both are true. Checked in both directions for this chart, and the answer moved with Gitea #114: the HTTPRoute reads ingress.domain too (as its single hostname), so domain is free only while BOTH routing modes are off; clusterIssuer is read by the Ingress alone and ingress.enabled: false still frees it.",
           "type": "boolean"
         },
         "clusterIssuer": {
@@ -195,13 +195,42 @@
           "type": ["string", "null"]
         },
         "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: the Gateway API has no annotation channel and no notion of a body size, so the proxy-body-size an S3 endpoint needs cannot be set here when httpRoute.enabled is used - it has to be raised at the Gateway.",
           "type": "object"
         }
       }
+    },
+    "httpRoute": {
+      "description": "Gateway-API alternative to the Ingress (Gitea #114), and off by default like the Ingress here. Mutually exclusive with ingress.enabled - the render aborts when both are true. The chart renders only an HTTPRoute with parentRefs, pointing at the Service's s3 port; 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 wildcard for vhost-style bucket access goes here, alongside garage.s3.rootDomain.",
+          "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"]
+    },
     "port": {
       "type": ["integer", "null"],
       "minimum": 1,

garage/values.yaml

@@ -421,11 +421,21 @@ ingress:
   # there is nothing to publish. The values exist, built to this repo's
   # convention, so that publishing the endpoint later is a values change.
   #
-  # Guideline 1, checked in both directions: nothing outside the Ingress
-  # template reads ingress.domain (the vhost suffix is its own value,
-  # garage.s3.rootDomain), so switching the Ingress off frees BOTH domain and
-  # clusterIssuer. With it on, both are required and the required() fires in
-  # the template.
+  # Mutually exclusive with httpRoute.enabled below (Gitea #114): with both
+  # true the render aborts, naming both values. Both ship off, so this chart
+  # publishes nothing until asked - in either mode.
+  #
+  # Guideline 1, checked in both directions, and the answer MOVED with #114:
+  # the Ingress template is no longer the only reader of ingress.domain - the
+  # HTTPRoute reads it too, as its single hostname, when httpRoute.hostnames is
+  # empty. So domain is free only while BOTH routing modes are off; with either
+  # one on it is required, and the required() fires in whichever template is
+  # rendering. clusterIssuer is unchanged: it is read only by the Ingress, so
+  # ingress.enabled: false frees it in every case - Gateway mode renders no
+  # Certificate at all.
+  #
+  # Unchanged as well: the vhost suffix is its own value, garage.s3.rootDomain,
+  # and is still deliberately not coupled to ingress.domain.
   enabled: false
   clusterIssuer: null
   domain: null
@@ -434,4 +444,60 @@ ingress:
   # cluster-issuer annotation the chart always sets. An S3 endpoint behind
   # nginx usually wants nginx.ingress.kubernetes.io/proxy-body-size: "0" -
   # without it the controller's 1m default truncates uploads.
+  #
+  # THAT ONE HAS NO COUNTERPART IN GATEWAY MODE. The Gateway API has no
+  # annotation channel and no notion of a body size at all - an upload limit is
+  # implementation-specific policy - so an S3 endpoint published through an
+  # HTTPRoute silently inherits the Gateway's limit, whatever it is. For an
+  # object store that is not a detail: it is where PUTs start failing by size.
+  # The chart does not rebuild it (a policy object would bind it to one
+  # implementation); NOTES.txt prints the warning in that mode and the limit
+  # has to be raised at the Gateway.
   annotations: {}
+
+# Gateway-API alternative to the Ingress above (Gitea #114). Off by default -
+# like the Ingress here, so this chart still publishes nothing unless asked.
+# 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 GETS PUBLISHED IS THE S3 API, in this mode exactly as in Ingress mode:
+# the route points at the Service's s3 port and nothing else. The admin port is
+# deliberately not routed. Read the Ingress comment above before turning either
+# mode on - and read the upload-limit note, which is the one real regression of
+# this mode for an object store.
+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 vhost-style bucket access this is where the wildcard goes
+  # ("*.s3.example.com" alongside the plain host), together with
+  # garage.s3.rootDomain - the two still have to be set in step, as they do for
+  # the Ingress.
+  hostnames: []