Feature: Best-Effort Maintenance Mode Support for Top 5 Ingress Controllers

[vriesdemichael]

Context

The primary maintenance mode implementation will move to the Kubernetes Gateway API (#632). However, not all clusters run Gateway API-capable controllers or have the Gateway API CRDs installed. To provide reasonable coverage for the most common ingress controllers, we will add best-effort annotation-based support for the top 5 controllers by market share.

Important: This is provided with limited guarantees. No regression tests are maintained, and implementations will NOT be updated when ingress controllers release new versions. Users relying on these should migrate to Gateway API (#632) for long-term support.

Top 5 Ingress Controllers (by market share)

Based on CNCF survey data, Datadog container reports, and industry analysis:

Rank	Controller	Approach	Status
1	NGINX Ingress Controller	server-snippet annotation	✅ Already implemented (legacy, PR #631)
2	Traefik	Traefik IngressRoute middleware or annotations	❌ To implement
3	AWS Load Balancer Controller	ALB fixed-response action annotations	❌ To implement
4	HAProxy Ingress	haproxy-ingress.github.io/server-snippet or backend rules	❌ To implement
5	Istio / Envoy Gateway	VirtualService fault injection or EnvoyFilter	❌ To implement

Design

Controller Detection Strategy

The operator should detect which ingress controller is in use via:

1. spec.ingress.className on the Keycloak CR (explicit)
2. ingressClassName on existing Ingress resources
3. Cluster introspection (check for Traefik CRDs, Istio CRDs, etc.)

Per-Controller Implementation

Each controller gets a maintenance mode annotation builder function:

def build_maintenance_annotations_nginx(spec: KeycloakSpec) -> dict[str, str]: ...
def build_maintenance_annotations_traefik(spec: KeycloakSpec) -> dict[str, str]: ...
def build_maintenance_annotations_alb(spec: KeycloakSpec) -> dict[str, str]: ...
def build_maintenance_annotations_haproxy(spec: KeycloakSpec) -> dict[str, str]: ...
def build_maintenance_annotations_istio(spec: KeycloakSpec) -> dict[str, str]: ...

Support Guarantees

• No regression tests: Unit tests only, no integration test infrastructure for each controller
• No version tracking: Implementations target current controller versions at time of writing; no updates when controllers release new versions
• Best-effort: Community contributions welcome for fixes
• Deprecation path: All legacy controller support will be deprecated once Gateway API implementation (Feature: Gateway API as Primary Maintenance Mode Implementation #632) is stable
• Documentation: Each controller's support level will be clearly documented as "best-effort, community-maintained"

Acceptance Criteria

• Traefik maintenance mode annotations implemented
• AWS ALB Controller maintenance mode annotations implemented
• HAProxy Ingress maintenance mode annotations implemented
• Istio/Envoy maintenance mode annotations implemented
• Controller auto-detection logic
• Unit tests for each controller's annotation generation
• Documentation listing supported controllers and their limitations
• Clear deprecation notice pointing to Gateway API (Feature: Gateway API as Primary Maintenance Mode Implementation #632)

References

• Feature: Gateway API as Primary Maintenance Mode Implementation #632: Gateway API as primary maintenance mode implementation
• Feature: Ingress Read-Only Maintenance Mode and Edge Proxy Hardening #601: Original maintenance mode feature request
• PR feat(operator): blue-green Phase 1 — tiered DB config, maintenance mode, cache isolation #631: Phase 1 implementation (NGINX)
• ADR-088: Blue-Green Keycloak Upgrade Strategy