GRPCRoute

Written by

Updated at November 10, 2025

Cheatsheet
GRPCRouteMeta
- Annotations cheatsheet
- Annotations reference
GRPCRouteSpec

GRPCRoute provides a way to route gRPC requests. This includes the capability to match requests by hostname, gRPC service, or method. Requests are routed to backend services that support gRPC.

GRPCRoute is a Kubernetes Gateway API project resource. Below, we describe its fields and annotations used by Gwin. For configuration details, see the upstream documentation.

GRPCRoute resources must be attached to Gateway resources to function properly.

Cheatsheet

Note

Specification provided below is not valid configuration.

It's just demonstration of all GRPCRoute fields.

apiVersion: gateway.networking.k8s.io/v1
kind: GRPCRoute
metadata:
  name: example-grpc-route
  namespace: example-ns
  annotations: ...  # see annotations example below
spec:
  parentRefs:  # attach to Gateway resources
    - group: gateway.networking.k8s.io
      kind: Gateway
      namespace: gateway-ns
      name: example-gateway
      sectionName: grpc-listener  # specific listener name
  hostnames:  # domains this route handles
    - "grpc.example.com"  # gRPC service domain
    - "api.example.com"   # API domain
  rules:
    - name: service-rule  # rule identifier
      matches:  # conditions for this rule
        - method:
            type: Exact  # exact method match
            service: "example.UserService"  # gRPC service
            method: "GetUser"  # gRPC method
        - method:
            type: RegularExpression  # regex method match
            method: "List.*"  # match List* methods
        - headers:  # header matching
            - name: "grpc-timeout"
              value: "30s"
      filters:  # modify requests before routing
        - type: RequestHeaderModifier
          requestHeaderModifier:
            set:  # replace header values
              - name: "x-custom-header"
                value: "custom-value"
            add:  # add new headers
              - name: "x-added-header"
                value: "added-value"
            remove:  # remove headers
              - "x-remove-header"
        - type: ResponseHeaderModifier
          responseHeaderModifier: ... # same as RequestHeaderModifier
      backendRefs:  # where to route requests
        - group: ""  # core Kubernetes API
          kind: Service  # Kubernetes service
          name: grpc-service
          namespace: grpc-ns
          port: 9090
          weight: 80  # 80% of traffic
        - group: gwin.yandex.cloud  # Gwin custom resources
          name: grpc-backends
          weight: 20  # 20% of traffic

Field	Description
metadata	GRPCRouteMeta Name, namespace and annotations.
spec	GRPCRouteSpec Resource specification.

GRPCRouteMeta

Appears in: GRPCRoute

Field	Description
name	string Name of the GRPCRoute.
namespace	string Namespace of the GRPCRoute.
annotations	map[string]string Annotations of the GRPCRoute.

Annotations cheatsheet

Note

You can also set policy parameters using RoutePolicy resource. The RoutePolicy resource parameters and GRPCRoute annotations are equivalent.

Specification provided below is not valid configuration.
It's just demonstration of all GRPCRoute annotations.

apiVersion: gateway.networking.k8s.io/v1
kind: GRPCRoute
metadata:
  annotations:
    # Backend group configuration
    gwin.yandex.cloud/rules.backends.balancing.mode: "ROUND_ROBIN"  # load balancing algorithm
    gwin.yandex.cloud/rules.backends.balancing.localityAwareRouting: "80"  # prefer same zone
    gwin.yandex.cloud/rules.backends.balancing.strictLocality: "false"  # allow cross-zone routing
    gwin.yandex.cloud/rules.backends.balancing.panicThreshold: "50"  # panic mode threshold
    
    # Health checks
    gwin.yandex.cloud/rules.backends.hc.timeout: "5s"  # health check timeout
    gwin.yandex.cloud/rules.backends.hc.interval: "10s"  # check interval
    gwin.yandex.cloud/rules.backends.hc.healthyThreshold: "2"  # checks to mark healthy
    gwin.yandex.cloud/rules.backends.hc.unhealthyThreshold: "3"  # checks to mark unhealthy
    gwin.yandex.cloud/rules.backends.hc.port: "9090"  # health check port
  
    gwin.yandex.cloud/rules.backends.hc.grpc.serviceName: "health.HealthService"  # gRPC service
    
    # Health check transport settings
    gwin.yandex.cloud/rules.backends.hc.transportSettings.plaintext: "true"  # use plaintext for health checks
    gwin.yandex.cloud/rules.backends.hc.transportSettings.tls.sni: "health.example.com"  # SNI for health check TLS
    gwin.yandex.cloud/rules.backends.hc.transportSettings.tls.trustedCA.id: "health-cert-123"  # health check TLS cert ID
    gwin.yandex.cloud/rules.backends.hc.transportSettings.tls.trustedCA.bytes: "-----BEGIN CERTIFICATE-----..."  # health check TLS cert PEM
    
    # Backend TLS configuration
    gwin.yandex.cloud/rules.backends.tls.sni: "grpc.example.com"  # SNI for TLS
    gwin.yandex.cloud/rules.backends.tls.trustedCA.id: "cert-123456"  # cloud certificate ID
    gwin.yandex.cloud/rules.backends.tls.trustedCA.bytes: "-----BEGIN CERTIFICATE-----..."  # PEM certificate
    
    # Session affinity
    gwin.yandex.cloud/rules.sessionAffinity.header.name: "X-Session-ID"  # header-based affinity
    gwin.yandex.cloud/rules.sessionAffinity.cookie.name: "session"  # cookie name
    gwin.yandex.cloud/rules.sessionAffinity.cookie.ttl: "3600s"  # cookie lifetime
    gwin.yandex.cloud/rules.sessionAffinity.sourceIP: "true"  # IP-based affinity
    
    # Route timeouts
    gwin.yandex.cloud/rules.timeout: "60s"  # overall connection timeout
    gwin.yandex.cloud/rules.idleTimeout: "300s"  # idle connection timeout
    
    # Host rewriting
    gwin.yandex.cloud/rules.hostRewrite.auto: "true"  # automatically rewrite host to backend target
    gwin.yandex.cloud/rules.hostRewrite.replace: "grpc.backend.example.com"  # static host replacement
    
    # Security
    gwin.yandex.cloud/rules.securityProfileID: "security-profile-1"  # WAF profile for routes
    gwin.yandex.cloud/hosts.securityProfileID: "host-security-profile-1"  # WAF profile for hosts
    
    # Rate limiting
    gwin.yandex.cloud/rules.rateLimit.allRequests.perSecond: "100"  # route-level rate limit for all requests
    gwin.yandex.cloud/rules.rateLimit.allRequests.perMinute: "6000"  # route-level rate limit for all requests
    gwin.yandex.cloud/rules.rateLimit.requestsPerIP.perSecond: "10"  # route-level rate limit per IP
    gwin.yandex.cloud/rules.rateLimit.requestsPerIP.perMinute: "600"  # route-level rate limit per IP

    gwin.yandex.cloud/hosts.rateLimit.allRequests.perSecond: "100"  # host-level rate limit for all requests
    gwin.yandex.cloud/hosts.rateLimit.allRequests.perMinute: "6000"  # host-level rate limit for all requests
    gwin.yandex.cloud/hosts.rateLimit.requestsPerIP.perSecond: "10"  # host-level rate limit per IP
    gwin.yandex.cloud/hosts.rateLimit.requestsPerIP.perMinute: "600"  # host-level rate limit per IP
    
    # RBAC configuration
    gwin.yandex.cloud/rules.rbac.action: "ALLOW"  # default RBAC action
    gwin.yandex.cloud/rules.rbac.principals.admin.check-token.header.name: "authorization"  # header to check
    gwin.yandex.cloud/rules.rbac.principals.admin.check-token.header.exact: "Bearer admin123"  # required value
    gwin.yandex.cloud/rules.rbac.principals.admin.check-ip.ip.remoteIp: "10.0.0.0/8"  # allowed IP range
    gwin.yandex.cloud/hosts.rbac.action: "DENY"  # host-level RBAC action
    
    # Rule-specific configuration (overrides global settings)
    gwin.yandex.cloud/rule.service-rule.backends.balancing.mode: "LEAST_REQUEST"  # per-rule balancing
    gwin.yandex.cloud/rule.service-rule.timeout: "30s"  # per-rule timeout
    gwin.yandex.cloud/rule.service-rule.idleTimeout: "120s"  # per-rule idle timeout

Annotations reference

Backend group configuration

Annotation and description
`gwin.yandex.cloud/rules.backends.balancing.mode` (string) Load balancing mode for backend group. Possible values: `RANDOM`, `ROUND_ROBIN`, `LEAST_REQUEST`. Example: `ROUND_ROBIN`
`gwin.yandex.cloud/rules.backends.balancing.localityAwareRouting` (number) Percentage of traffic sent to backends in the same availability zone. Example: `80`
`gwin.yandex.cloud/rules.backends.balancing.strictLocality` (boolean) Route traffic only to backends in the same availability zone. Example: `false`
`gwin.yandex.cloud/rules.backends.balancing.panicThreshold` (number) Panic mode threshold percentage for load balancing. Example: `50`

Health check configuration

Common health check settings

Annotation and description
`gwin.yandex.cloud/rules.backends.hc.timeout` (duration) Health check timeout. Example: `5s`
`gwin.yandex.cloud/rules.backends.hc.interval` (duration) Interval between health checks. Example: `10s`
`gwin.yandex.cloud/rules.backends.hc.healthyThreshold` (number) Number of successful checks to mark backend as healthy. Example: `2`
`gwin.yandex.cloud/rules.backends.hc.unhealthyThreshold` (number) Number of failed checks to mark backend as unhealthy. Example: `3`
`gwin.yandex.cloud/rules.backends.hc.port` (number) Port for health checks. Example: `9090`

gRPC health checks

Annotation and description
`gwin.yandex.cloud/rules.backends.hc.grpc.serviceName` (string) gRPC service name for health checks. Example: `health.HealthService`

Health check transport settings

Annotation and description
`gwin.yandex.cloud/rules.backends.hc.transportSettings.plaintext` (boolean) Use plaintext protocol for health checks. Set to `true` to force HTTP health checks even for HTTPS backends. Example: `true`
`gwin.yandex.cloud/rules.backends.hc.transportSettings.tls.sni` (string) Server Name Indication (SNI) for health check TLS connections. Example: `health.example.com`
`gwin.yandex.cloud/rules.backends.hc.transportSettings.tls.trustedCA.id` (string) Cloud certificate ID for health check TLS validation. Example: `health-cert-123`
`gwin.yandex.cloud/rules.backends.hc.transportSettings.tls.trustedCA.bytes` (string) X.509 certificate contents in PEM format for health check TLS validation. Example: `-----BEGIN CERTIFICATE-----...`

Backend TLS configuration

Annotation and description
`gwin.yandex.cloud/rules.backends.tls.sni` (string) Server Name Indication (SNI) for TLS connections to backends. Example: `grpc.example.com`
`gwin.yandex.cloud/rules.backends.tls.trustedCA.id` (string) Cloud certificate ID for backend TLS validation. Example: `cert-123456`
`gwin.yandex.cloud/rules.backends.tls.trustedCA.bytes` (string) X.509 certificate contents in PEM format for backend TLS validation. Example: `-----BEGIN CERTIFICATE-----...`

Session affinity

Annotation and description
`gwin.yandex.cloud/rules.sessionAffinity.header.name` (string) HTTP header name for session affinity. Example: `X-Session-ID`
`gwin.yandex.cloud/rules.sessionAffinity.cookie.name` (string) Cookie name for session affinity. Example: `session`
`gwin.yandex.cloud/rules.sessionAffinity.cookie.ttl` (duration) Cookie TTL for session affinity. Example: `3600s`
`gwin.yandex.cloud/rules.sessionAffinity.sourceIP` (boolean) Use source IP for session affinity. Example: `true`

Route configuration

Annotation and description
`gwin.yandex.cloud/rules.timeout` (duration) Overall timeout for gRPC connection between load balancer and backend. Example: `60s`
`gwin.yandex.cloud/rules.idleTimeout` (duration) Idle timeout for gRPC connection. Example: `300s`

Route rate limiting

Annotation and description
`gwin.yandex.cloud/rules.rateLimit.allRequests.perSecond` (number) Route-level rate limit for all requests per second. Example: `100`
`gwin.yandex.cloud/rules.rateLimit.allRequests.perMinute` (number) Route-level rate limit for all requests per minute. Example: `6000`
`gwin.yandex.cloud/rules.rateLimit.requestsPerIP.perSecond` (number) Route-level rate limit per IP address per second. Example: `10`
`gwin.yandex.cloud/rules.rateLimit.requestsPerIP.perMinute` (number) Route-level rate limit per IP address per minute. Example: `600`

Host rewriting

Annotation and description
`gwin.yandex.cloud/rules.hostRewrite.auto` (boolean) Automatically replaces the host with that of the target backend. Cannot be used together with `hostRewrite.replace`. Example: `true`
`gwin.yandex.cloud/rules.hostRewrite.replace` (string) Static host replacement value for gRPC :authority pseudo-headers. Cannot be used together with `hostRewrite.auto`. Example: `grpc.backend.example.com`

Security configuration

Annotation and description
`gwin.yandex.cloud/rules.securityProfileID` (string) Security profile ID for route-level protection. Example: `security-profile-1`
`gwin.yandex.cloud/hosts.securityProfileID` (string) Security profile ID for host-level protection. Example: `host-security-profile-1`

Rate limiting

Annotation and description
`gwin.yandex.cloud/hosts.rateLimit.allRequests.perSecond` (number) Rate limit for all requests per second. Example: `100`
`gwin.yandex.cloud/hosts.rateLimit.allRequests.perMinute` (number) Rate limit for all requests per minute. Example: `6000`
`gwin.yandex.cloud/hosts.rateLimit.requestsPerIP.perSecond` (number) Rate limit per IP address per second. Example: `10`
`gwin.yandex.cloud/hosts.rateLimit.requestsPerIP.perMinute` (number) Rate limit per IP address per minute. Example: `600`

RBAC configuration

RBAC allows controlling access to routes or hosts based on request attributes.

Annotations follow the pattern:
gwin.yandex.cloud/{resource}.rbac.principals.{principal-group}.{principal}.{rule-type}

Where:

{resource} — resource type (rules, hosts);
{principal-group} — logical group of checks (e.g. admin);
{principal} — specific principal identifier (e.g. check-token);
{rule-type} — matching rule type (header, ip, etc.).

Combination Rules

All checks within the same principal group are combined with AND logic.
Different principal groups are combined with OR logic.

Annotation and description
`gwin.yandex.cloud/rules.rbac.action` (string) Action when principals match (ALLOW/DENY) for route access control. Example: `ALLOW`
`gwin.yandex.cloud/rules.rbac.principals.{group}.{principal}.header.name` (string) Header name to match for route RBAC. Example: `authorization`
`gwin.yandex.cloud/rules.rbac.principals.{group}.{principal}.header.exact` (string) Exact header value match for route RBAC. Example: `Bearer admin123`
`gwin.yandex.cloud/rules.rbac.principals.{group}.{principal}.header.regex` (string) Regex pattern for header value match for route RBAC. Example: `^Bearer .*`
`gwin.yandex.cloud/rules.rbac.principals.{group}.{principal}.header.prefix` (string) Header value prefix match for route RBAC. Example: `Bearer`
`gwin.yandex.cloud/rules.rbac.principals.{group}.{principal}.ip.remoteIp` (string) IP address or CIDR block for route RBAC. Example: `10.0.0.0/8`
`gwin.yandex.cloud/rules.rbac.principals.{group}.{principal}.any` (boolean) Match any request for route RBAC. Example: `true`
`gwin.yandex.cloud/hosts.rbac.action` (string) Action when principals match (ALLOW/DENY) for host access control. Example: `DENY`

Rule-specific configuration

Note

Any rules option can be applied to a specific rule by prefixing with rule.{rule-name}.

For example: gwin.yandex.cloud/rule.service-rule.backends.balancing.mode: "LEAST_REQUEST".

Annotation and description
`gwin.yandex.cloud/rule.{rule-name}.backends.balancing.mode` (string) Load balancing mode for specific rule. Example: `LEAST_REQUEST`
`gwin.yandex.cloud/rule.{rule-name}.timeout` (duration) Timeout for specific rule. Example: `30s`
`gwin.yandex.cloud/rule.{rule-name}.idleTimeout` (duration) Idle timeout for specific rule. Example: `120s`

GRPCRouteSpec

GRPCRoute specification defines the desired state of GRPCRoute.

Appears in: GRPCRoute

Field	Description
parentRefs	[]ParentReference References to Gateway resources that this GRPCRoute should attach to.
hostnames	[]string Hostnames that should match against the gRPC :authority header.
rules	[]GRPCRouteRule Rules for routing gRPC requests.

ParentReference

Reference to a Gateway resource that this route should attach to.

Appears in: GRPCRouteSpec

Field	Description
group	string API group of the parent resource. Example: `gateway.networking.k8s.io`
kind	string Kind of the parent resource. Example: `Gateway`
namespace	string Namespace of the parent resource. Example: `gateway-ns`
name	string Name of the parent resource. Example: `example-gateway`
sectionName	string Name of the specific listener to attach to. Example: `grpc-listener`
port	int32 Port number of the listener to attach to. Example: `80`

GRPCRouteRule

GRPCRouteRule defines semantics for matching a gRPC request based on conditions (matches), processing it (filters), and forwarding the request to an API object (backendRefs).

Appears in: GRPCRouteSpec

Field	Description
name	string Name of the route rule. Must be unique within a Route if set. Example: `service-rule`
matches	[]GRPCRouteMatch Conditions required for a request to match this rule.
filters	[]GRPCRouteFilter Filters to modify requests before forwarding to backends.
backendRefs	[]GRPCBackendRef Backend services to route requests to.
sessionPersistence	SessionPersistence Session persistence configuration for the route rule.

GRPCRouteMatch

GRPCRouteMatch defines the predicate used to match requests to a given action. Multiple match types are ANDed together.

Appears in: GRPCRouteRule

Field	Description
method	GRPCMethodMatch gRPC method matcher.
headers	[]GRPCHeaderMatch gRPC header matchers.

GRPCMethodMatch

GRPCMethodMatch describes how to select a gRPC route by matching the gRPC request method.

Appears in: GRPCRouteMatch

Field	Description
type	string Method match type. `Exact` for exact method match, `RegularExpression` for regex match. Example: `Exact`, `RegularExpression`.
service	string gRPC service name to match against. Example: `example.UserService`
method	string gRPC method name to match against. For regex type, this is a regular expression pattern. Example: `GetUser`, `List.*`.

GRPCHeaderMatch

GRPCHeaderMatch describes how to select a gRPC route by matching gRPC request headers.

Appears in: GRPCRouteMatch

Field	Description
type	string Header match type. `Exact` for exact match, `RegularExpression` for regex match. Example: `Exact`, `RegularExpression`.
name	string Name of the gRPC header to be matched. Example: `grpc-timeout`
value	string Value of the gRPC header to be matched. Example: `30s`

GRPCRouteFilter

GRPCRouteFilter defines processing steps that must be completed during the request or response lifecycle.

Appears in: GRPCRouteRule, GRPCBackendRef

Field	Description
type	string Filter type. Supported: `RequestHeaderModifier`, `ResponseHeaderModifier`, `RequestMirror`, `ExtensionRef` Example: `RequestHeaderModifier`
requestHeaderModifier	GRPCHeaderFilter Request header modification configuration.
responseHeaderModifier	GRPCHeaderFilter Response header modification configuration.

GRPCHeaderFilter

GRPCHeaderFilter defines configuration for header modification filters (both RequestHeaderModifier and ResponseHeaderModifier).

Appears in: GRPCRouteFilter

Field	Description
set	[]GRPCHeader Headers to set, replacing any existing values.
add	[]GRPCHeader Headers to add to the request/response.
remove	[]string Header names to remove from the request/response.

GRPCBackendRef

GRPCBackendRef defines how a GRPCRoute forwards a gRPC request.

Appears in: GRPCRouteRule

Field	Description
group	string API group of the backend resource. Example: `""`, `gwin.yandex.cloud`.
kind	string Kind of the backend resource. Example: `Service`
name	string Name of the backend resource. Example: `grpc-service`
namespace	string Namespace of the backend resource. Example: `grpc-ns`
port	int32 Port of the backend service (for Service kind only). Example: `9090`
weight	int32 Weight for traffic distribution between backends. Example: `80`

GRPCRoute

CheatsheetCheatsheet

GRPCRouteMetaGRPCRouteMeta

Annotations cheatsheetAnnotations cheatsheet

Annotations referenceAnnotations reference

Backend group configurationBackend group configuration

Health check configurationHealth check configuration

Common health check settingsCommon health check settings

gRPC health checksgRPC health checks

Health check transport settingsHealth check transport settings

Backend TLS configurationBackend TLS configuration

Session affinitySession affinity

Route configurationRoute configuration

Route rate limitingRoute rate limiting

Host rewritingHost rewriting

Security configurationSecurity configuration

Rate limitingRate limiting

RBAC configurationRBAC configuration

Combination RulesCombination Rules

Rule-specific configurationRule-specific configuration

GRPCRouteSpecGRPCRouteSpec

ParentReferenceParentReference

GRPCRouteRuleGRPCRouteRule

GRPCRouteMatchGRPCRouteMatch

GRPCMethodMatchGRPCMethodMatch

GRPCHeaderMatchGRPCHeaderMatch

GRPCRouteFilterGRPCRouteFilter

GRPCHeaderFilterGRPCHeaderFilter

GRPCBackendRefGRPCBackendRef

Was the article helpful?

Cheatsheet

GRPCRouteMeta

Annotations cheatsheet

Annotations reference

Backend group configuration

Health check configuration

Common health check settings

gRPC health checks

Health check transport settings

Backend TLS configuration

Session affinity

Route configuration

Route rate limiting

Host rewriting

Security configuration

Rate limiting

RBAC configuration

Combination Rules

Rule-specific configuration

GRPCRouteSpec

ParentReference

GRPCRouteRule

GRPCRouteMatch

GRPCMethodMatch

GRPCHeaderMatch

GRPCRouteFilter

GRPCHeaderFilter

GRPCBackendRef