GRPCRoute resource fields

The GRPCRoute resource sets rules for routing between Kubernetes services operating as backends (Service resources) or for traffic redirection. GRPCRoute receives incoming traffic from those Gateway resources whose requirements it meets.

GRPCRoute is designed for application developers. Cluster operators should use the Gateway resource.

GRPCRoute is a Kubernetes Gateway API project resource. Below, we describe its fields and annotations used by the Application Load Balancer Gateway API. For resource configuration details, see this Kubernetes Gateway API guide.

GRPCRouteGRPCRoute

apiVersion: gateway.networking.k8s.io/v1
kind: GRPCRoute
metadata:
  name: <string>
  namespace: <string>
spec: <GRPCRouteSpec>

Where:

• apiVersion: gateway.networking.k8s.io/v1

• kind: GRPCRoute

• metadata (ObjectMeta; this is a required field)

  Resource metadata.

  • name (string; this is a required field)

    Resource name. The format is described in this Kubernetes guide.

    Do not mistake this name for the Application Load Balancer route name.

  • namespace (string)

    Namespace the resource belongs to. The default value is default.

• spec (GRPCRouteSpec; this is a required field)

  Resource specification. Read more below.

apiVersion: gateway.networking.k8s.io/v1
kind: GRPCRoute
metadata:
  name: mosquitoes-grpc-route
  namespace: mosquitoes-ns
spec:
  hostnames:
  - "forest.zoo.com"
  parentRefs:
  - name: gateway-api-test-gateway
    namespace: default
  rules:
  - backendRefs:
    - name: mosquitoes-service
      port: 8080
    matches:
    - method:
        type: "Exact"
        method: "IdentifyA"

GRPCRouteSpecGRPCRouteSpec

parentRefs:
  - namespace: <string>
    name: <string>
    sectionName: <string>
  - ...
hostnames:
  - <string>
  - ...
rules:
  - matches:
      - method:
          type: <string>
          service: <string>
          method: <string>
      - ...
    filters:
      - type: <string>
        requestHeaderModifier:
          set:
            - name: <string>
              value: <string>
            - ...
          add:
            - name: <string>
              value: <string>
            - ...
          remove:
            - <string>
            - ...
    backendRefs:
      - name: <string>
        namespace: <string>
        port: <int32>
        weight: <int32>
      - ...
  - ...

Where:

• parentRefs ([]ParentReference; this is a required field)

  Gateway resources or their listeners specified in the spec.listeners field associated with GRPCRoute. For more information, see this reference.

  The route must also comply with the rules described in the Gateway configuration (spec.listeners.allowedRoutes field).

  • namespace (string)

    Gateway resource namespace specified in its metadata.namespace field.

    By default, it matches the GRPCRoute resource namespace (metadata.namespace field).

  • name (string; this is a required field)

    Name of the Gateway resource (see the metadata.name field in its metadata).

  • sectionName (string)

    Name of the listener specified in the Gateway resource under spec.listeners.name.

• hostnames ([]string)

  List of domain names (:authority pseudoheader values) for the route. The system will create HTTP router virtual hosts for each specified domain name.

  To match all subdomains at any level, use a wildcard * in place of the first-level domain name. Wildcard domain values must be quoted.

  For example, "*.example.com" matches foo.example.com, foo-bar.example.com, foo.bar.example.com, and foo.bar.baz.example.com, but not example.com.

  Wildcards must replace complete domain levels; for example, *foo.example.com is invalid.

• rules ([]GRPCRouteRule)

  Rules for routing and redirecting gRPC calls.

  • matches ([]GRPCRouteMatch)

    List of conditions for the rule to apply to a gRPC call if it meets at least one of them.

    For example, all gRPC calls with names that include service.example and the Login method as well as calls with names that include service.v2.example and any of that service’s methods will fulfill the following list of conditions:

    - matches:
      - method:
          service: service.example
          method: Login
      - method:
          service: service.v2.example
    

    Only the method field is supported. The headers field described in the Gateway API reference is not supported.

    • method (GRPCMethodMatch)

      Indicates the gRPC service and gRPC method the call name must consist of. Make sure to fill in at least one of these fields.

      • service

        Indicates the gRPC service.

      • method

        Indicates the gRPC method.

      • type (GRPCMethodMatchType)

        Specifies how to indicate the method and service in the call name:

        • Exact: Method and/or service must match the rules.matches.method value.
        • RegularExpression: Method and/or service must match the regular expression specified in the rules.matches.method field.

  • filters ([]GRPCRouteFilter)

    Call header modification settings for backend routing.

    • type (string)

      Filter type:

      • RequestHeaderModifier: Call header modification. Specify the required settings in the requestHeaderModifier field.

    • requestHeaderModifier (HTTPHeaderFilter)

      Call header modification settings for the RequestHeaderModifier filter type.

      • set ([]HTTPHeader)

        Headers to overwrite.

        • name (string)

          Header name to overwrite.

        • value (string)

          Value written to the header.

      • add ([]HTTPHeader)

        Headers to add.

        • name (string)

          Name of the header to add.

        • value (string)

          Value of the header to add.

      • remove ([]string)

        Header names to remove.

  • backendRefs ([]GRPCBackendRef)

    Kubernetes services for processing calls as backends.

    • name (string)

      Kubernetes service name. The referred Service resource must be described per the standard configuration.

    • namespace (string)

      Namespace the Service resource belongs to. By default, it matches the GRPCRoute resource namespace (metadata.namespace field).

    • port (int32)

      Service port number.

      This number must match one of the port numbers specified in the spec.ports.port fields of the Service resource. For more information, see the resource configuration.

    • weight (int32)

      Backend weight. Backends in a group receive traffic in proportion to their weights.

      You should either specify weights for all backends in a group, or not specify them at all. If weights are not specified, traffic will be equally distributed across backends.

      A backend with zero or negative weight will not be receiving traffic.