Support Gateway API GRPCRoute for gRPC canary deployments

[dgmbx]

Describe the feature

Flagger's Gateway API integration currently supports only HTTPRoute for traffic shifting during canary deployments. The Gateway API GRPCRoute resource reached GA in Gateway API v1.1 and is the first-class way to manage gRPC traffic with Gateway API.

While gRPC traffic can be routed using HTTPRoute, the Gateway API docs identify specific scenarios where GRPCRoute is the correct choice:

• Service/method matching: GRPCRoute matches on gRPC service and method names (e.g., service: com.example.UserService, method: Login) directly, rather than mapping them to URI paths (e.g., /com.example.UserService/Login) as HTTPRoute requires.
• gRPC-aware retry policies: Retries conditioned on gRPC status codes (CANCELLED, RESOURCE_EXHAUSTED, UNAVAILABLE, etc.) are only expressible on GRPCRoute. HTTPRoute retries operate on HTTP status codes only.
• gRPC-oriented observability: Implementations that support GRPCRoute can expose gRPC-specific metrics; this is explicitly not available when routing gRPC over HTTPRoute.
• Protocol isolation: The Gateway API guidance for controller implementers is to offer GRPCRoute alongside HTTPRoute so users can access protocol-specific features and to avoid adding gRPC-specific policies to HTTPRoute.

Without GRPCRoute support, Flagger users running gRPC services with a Gateway API-compatible controller (e.g., Envoy Gateway, Istio, Cilium) cannot perform canary analysis with gRPC-native semantics. They are forced to use HTTPRoute (losing the features above).

Proposed solution

Add a GRPCRoute router implementation to Flagger's Gateway API provider, mirroring how HTTPRoute is handled today.

Flagger should manage a GRPCRoute resource with the following capabilities, analogous to the existing HTTPRoute integration:

1. Traffic splitting via backendRefs[].weight: On canary promotion, Flagger shifts traffic from the primary backend to the canary backend by adjusting weight on the two backendRefs entries within a single rule, identical in mechanism to how HTTPRoute canaries work.

2. Service/method matching (rules[].matches): GRPCRoute matches on service (e.g., com.example.UserService) and method (e.g., Login) rather than URI path. Flagger should preserve user-defined match rules when reconciling the route, only modifying backendRefs weights.

3. Header matching (rules[].matches[].headers): Support for gRPC metadata header matching, enabling header-based canary routing (e.g., routing a specific tenant or test header to the canary backend).

4. Filters (rules[].filters): Passthrough of user-defined filters (e.g., RequestHeaderModifier) without interference during weight reconciliation.

5. Hostname matching: Respect spec.hostnames for multi-host gateway setups, consistent with the HTTPRoute implementation.

Any alternatives you've considered?

• Use HTTPRoute for gRPC: HTTPRoute can technically route gRPC-over-HTTP/2 traffic, but loses gRPC-specific match semantics (service/method names), gRPC-aware retry policies, and gRPC-oriented metrics. The Gateway API docs explicitly advise against adding gRPC-specific policies to HTTPRoute.
• Use App Mesh: App Mesh appears to have GRPCRoute support in Flagger today, but is not a viable alternative for users on Gateway API-compatible controllers.
• Use Istio's native VirtualService: Works for gRPC via HTTP/2, but bypasses Gateway API entirely and is Istio-specific.