Feature: Gateway API as Primary Maintenance Mode Implementation

[vriesdemichael]

Context

The current maintenance mode implementation (#601, PR #631) uses nginx-ingress-specific annotations (nginx.ingress.kubernetes.io/server-snippet) to inject traffic control directives. This is tightly coupled to the NGINX Ingress Controller and will silently fail with any other ingress controller (Traefik, HAProxy, AWS ALB, Istio, etc.).

The Kubernetes Gateway API is the official successor to the Ingress API, reached GA (v1.1.0) in October 2023, and is now implemented by every major ingress controller and service mesh. It provides a standardized, portable way to express traffic policies.

Decision

• Gateway API becomes the primary, fully-supported mechanism for maintenance mode traffic control
• The existing NGINX Ingress Controller implementation (server-snippet annotations) is retained as a legacy fallback with limited future investment
• See also: Feature: Best-Effort Maintenance Mode Support for Top 5 Ingress Controllers #633 for best-effort support of top 5 traditional ingress controllers

Proposed Implementation

Gateway API HTTPRoute-Based Maintenance Mode

Use Gateway API HTTPRoute resources with request matching to implement maintenance mode. When maintenance mode is enabled, the operator creates/patches HTTPRoute resources to:

1. full-block mode: Match all traffic except health check paths → return 503 via a backend ref to a maintenance backend (or use HTTPRoute RequestRedirect filter)
2. read-only mode: Match mutating HTTP methods (POST, PUT, DELETE, PATCH) except on excluded paths → return 503

Key Design Points

• The operator should detect whether Gateway API CRDs are installed in the cluster
• If Gateway API is available, use it; otherwise fall back to legacy nginx annotations
• Gateway API HTTPRoute filters provide portable RequestHeaderModifier, RequestRedirect, and backend weighting
• For 503 responses, consider a lightweight maintenance-page backend (e.g., a static nginx pod returning 503) or HTTPRoute ExtensionRef where supported
• Health/readiness exclusions work natively via HTTPRoute path matching priority

Migration Path

1. Detect cluster capabilities (Gateway API CRDs present?)
2. Prefer Gateway API when available
3. Log a deprecation warning when falling back to legacy nginx annotations
4. Document migration guide for users on nginx-ingress wanting to adopt Gateway API

Acceptance Criteria

• Maintenance mode works via Gateway API HTTPRoute resources
• Automatic detection of Gateway API availability in cluster
• Fallback to legacy nginx annotations when Gateway API not available
• Deprecation warning logged when using legacy path
• Integration tests covering Gateway API-based maintenance mode
• Documentation for Gateway API setup and migration from nginx

References

• Gateway API docs: https://gateway-api.sigs.k8s.io/
• Gateway API HTTP routing: https://gateway-api.sigs.k8s.io/guides/http-routing/
• ADR-088: Blue-Green Keycloak Upgrade Strategy
• Feature: Ingress Read-Only Maintenance Mode and Edge Proxy Hardening #601: Ingress Read-Only Maintenance Mode (original implementation)
• Feature: Best-Effort Maintenance Mode Support for Top 5 Ingress Controllers #633: Legacy ingress controller support (top 5)