gRPCRoute¶

Overview¶

The gRPCRoute resource in the Kubernetes Gateway API is designed to handle and route gRPC traffic within a Kubernetes cluster. gRPCRoute is determined by the Gateway API community. It extends the capabilities of routing beyond traditional HTTP traffic to support gRPC, a modern and high-performance protocol for remote procedure calls.

Key aspects of the gRPCRoute include¶

Routing gRPC Traffic: gRPCRoute is a Gateway API type for specifying routing behavior of gRPC requests from a Gateway listener to an API object, such as Service.
Integration: Integrates with the Gateway and other related resources to manage and configure gRPC traffic efficiently.

By using gRPCRoute, Kubernetes users can effectively manage gRPC traffic, ensuring that requests are routed correctly and efficiently within their cluster.

Update service¶

When a backend service is edited, the configuration of the dataplane does not get automatically updated. You must perform these steps in sequence.

Delete the service.
Modify the yaml file of the service.
Reapply the service.

Note

Perform Custom Resource (CR) operations only when the controller is in a running state.

CR Parameters¶

The table below describes the gRPCRoute spec parameters:

Parameter	Description	Implementation Details
`parentRefs.name`	Specifies the name of the parent resources that are associated with gRPCRoute. For example, `grpc-gateway`	As per the Gateway API community standard.
`parentRefs.namespace`	Specifies the namespace of the parent resource that is associated with gRPCRoute. When unspecified, this refers to the local namespace of the Route.	As per the Gateway API community standard.
`parentRefs.port`	Specifies the network port that this gRPCRoute targets. For example, Targets all listeners on the specified port of a Gateway resource - 8080	As per the Gateway API community standard.
`parentRefs.sectionName`	Specifies the section name or category of the parent that is associated with gRPCRoute. For example, listener name of Gateway resource - grpc	As per the Gateway API community standard.
`rules.backendRefs.name`	Specifies the name of the backend service to which the traffic must be sent. For example, `go-grpc-greeter-server`	Each gRPCRoute CR supports only one rule.
`rules.backendRefs.port`	Specifies the port on which the backend service is listening. For example, 80	As per the Gateway API community standard.
`rules.backendRefs.weight`	Specifies the weight for load balancing the traffic between multiple backends. For example, 30	As per the Gateway API community standard.
`rules.backendRefs.namespace`	Specifies the namespace in which the backend service is deployed. When unspecified, this refers to the local namespace of the Route.	As per the Gateway API community standard.

Note

You can refer to gRPCRoute for more details.
Hostnames, Matches, Filters, SessionPersistence parameters in gRPCRoute CR are not supported.
gRPCRoute does not support multiple rules per CR.

gRPCRoute CR Status¶

gRPCRoute condition - Accepted

conditions.status	conditions.reason	description
Unknown	Pending	Initial state. Waiting for controller
True	Accepted	Accepted
False	- NoMatchingParent - NotAllowedByListeners - NoMatchingListenerHostname	- No matching Parents by either Name, Port, or SectionName - Route not allowed by listeners - Route has no matching listener hostname

gRPCRoute condition - ResolvedRef

conditions.status	conditions.reason	description
True	ResolvedRefs	References Resolved
False	- InvalidKind - BackendNotFound - RefNotPermitted - UnsupportedProtocol	- BackendRef has invalid kind - BackendRef not found - Referenced resource protocol is not supported

gRPCRoute condition - PartiallyInvalid

conditions.status	conditions.reason	description
True	UnsupportedValue	Found both valid and invalid rules

The descriptions in the tables above may not match the status section of the CR exactly.

Sample CRs¶

This section lists the sample CRs of use cases available to apply gRPCRoute. You must apply GatewayClass CR in the cluster and GatewaySettings in the namespace, only once.

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: f5-gateway-class
spec:
  controllerName: "f5.com/f5-bnk-f5-cne-controller"
  description: "F5 BIG-IP Kubernetes Gateway"

Basic gRPCRoute and Gateway API CRs
Client-side SSL configs
gRPCRoute with weighted traffic distribution

Basic gRPCRoute and Gateway API CRs¶

apiVersion: gateway.k8s.f5.com/v1alpha1
kind: GatewaySettings
metadata:
  name: gw-settings-app-1
  namespace: gateway-infra
spec:
  ingressConfig:
    defaultListenerNetwork:
      ipamRefs:
        - name: vip-listener-ipam
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: f5-grpc-gateway
  namespace: gateway-infra
spec:
    infrastructure:
    parametersRef:
      group: gateway.k8s.f5.com
      kind: GatewaySettings
      name: gw-settings-app-1  
  gatewayClassName: f5-gateway-class
  listeners:
  - name: grpc
    protocol: HTTP
    port: 50051
    allowedRoutes:
      namespaces:
        from: "All"
      kinds:
      - kind: GRPCRoute
---
apiVersion: gateway.networking.k8s.io/v1
kind: GRPCRoute
metadata:
  name: my-grpcroute
  namespace: app-ns
spec:
  parentRefs:
  - name: f5-grpc-gateway
    sectionName: grpc
    namespace: gateway-infra
  rules:
  - backendRefs:
    - name: go-grpc-greeter-server
      port: 80
      namespace: app-ns

Client-side SSL configs¶

apiVersion: gateway.k8s.f5.com/v1alpha1
kind: GatewaySettings
metadata:
  name: gw-settings-app-1
  namespace: gateway-infra
spec:
  ingressConfig:
    defaultListenerNetwork:
      ipamRefs:
        - name: vip-listener-ipam
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: f5-grpc-gateway
  namespace: gateway-infra
spec:
    infrastructure:
    parametersRef:
      group: gateway.k8s.f5.com
      kind: GatewaySettings
      name: gw-settings-app-1  
  gatewayClassName: f5-gateway-class
  listeners:
  - name: grpc
    protocol: HTTPS
    port: 443
    tls:
      certificateRefs:
      - kind: Secret
        group: ""
        name: tls-secret
        namespace: gateway-infra
    allowedRoutes:
      namespaces:
        from: "All"
      kinds:
      - kind: GRPCRoute
---
apiVersion: gateway.networking.k8s.io/v1
kind: GRPCRoute
metadata:
  name: my-grpcroute
  namespace: gateway-infra
spec:
  parentRefs:
  - name: f5-grpc-gateway
    sectionName: grpc
    namespace: app-ns
  rules:
  - backendRefs:
    - name: go-grpc-greeter-server
      port: 80
      namespace: app-ns

gRPCRoute with weighted traffic distribution¶

apiVersion: gateway.networking.k8s.io/v1
kind: GRPCRoute
metadata:
  name: my-grpcroute
  namespace: gateway-infra
spec:
  parentRefs:
  - name: f5-grpc-gateway
    sectionName: grpc
    namespace: gateway-infra
  rules:
  - backendRefs:
    - name: go-grpc-greeter-server
      port: 80
      namespace: app-ns
      weight: 70
    - name: go-grpc-greeter-server-2
      port: 80
      namespace: app-ns
      weight: 30