fix(gateway-api): address round 2 review — comments and fail on misconfiguration

Add architecture documentation comment to extra/gateway explaining the
two-Gateway model on port 80, mergeGateways reliance, and why one
rejected parentRef per ACME challenge is expected.

Add comment to cert-manager-issuers explaining dual parentRef strategy.

Replace silent ingress fallback with fail() when both ingress and
gatewayAPI are disabled — catches misconfiguration at template time.

Assisted-By: Claude AI
Signed-off-by: Kirill Ilin <stitch14@yandex.ru>

Author: sircthulhu

packages/extra/gateway/templates/gateway.yaml

@@ -39,6 +39,29 @@ spec:
     name: gateway-proxy
     namespace: {{ .Release.Namespace }}
 ---
+{{/*
+  HTTP port 80 architecture — two Gateways with mergeGateways:
+
+  1. acme-challenge (from: Selector, cozystack.io/system label)
+     Accepts ACME HTTP-01 challenge HTTPRoutes from system namespaces
+     (cozy-dashboard, cozy-keycloak, etc.) and per-hostname redirect
+     HTTPRoutes created by system service charts.
+
+  2. http-redirect (from: Same)
+     Accepts the catch-all redirect-to-https HTTPRoute and ACME
+     challenges from this tenant namespace (e.g., bucket certificates).
+
+  Both Gateways declare port 80 HTTP with no hostname filter. This
+  relies on Envoy Gateway's mergeGateways to combine them into one
+  Envoy listener. Standard Gateway API conformance tests may flag this
+  as a conflict — if a future Envoy Gateway release tightens spec
+  compliance, consolidation into a single Gateway will be needed
+  (requires OR logic in label selectors or operator-managed labels).
+
+  cert-manager solver references both Gateways as parentRefs. Each
+  challenge HTTPRoute will have one accepted and one rejected parent —
+  this is expected and cert-manager handles partial acceptance correctly.
+*/}}
 apiVersion: gateway.networking.k8s.io/v1
 kind: Gateway
 metadata:

packages/system/cert-manager-issuers/templates/cluster-issuers.yaml

@@ -21,6 +21,10 @@ solvers:
     ingress:
       class: nginx
 {{- end }}
+{{/* Dual parentRef: acme-challenge accepts system namespaces (Selector),
+     http-redirect accepts the gateway's own namespace (Same). Each challenge
+     HTTPRoute will have one accepted and one rejected parent — this is
+     expected, cert-manager handles partial acceptance correctly. */}}
 {{- if and (eq $gatewayAPI "true") (ne $gateway "") }}
 - http01:
     gatewayHTTPRoute:
@@ -33,9 +37,7 @@ solvers:
         kind: Gateway
 {{- end }}
 {{- if and (ne $ingressEnabled "true") (or (ne $gatewayAPI "true") (eq $gateway "")) }}
-- http01:
-    ingress:
-      class: nginx
+{{- fail "At least one of gateway.ingress or gateway.gatewayAPI must be enabled for ACME HTTP-01 solver" }}
 {{- end }}
 {{- end }}
 {{- end -}}