sigs.k8s.io/gateway-api@v1.0.0/site-src/guides/grpc-routing.md (about)

     1  # gRPC routing
     2  
     3  !!! info "Experimental Channel"
     4  
     5      The `GRPCRoute` resource described below is currently only included in the
     6      "Experimental" channel of Gateway API. For more information on release
     7      channels, refer to the [related documentation](https://gateway-api.sigs.k8s.io/concepts/versioning).
     8  
     9  The [GRPCRoute resource](/api-types/grpcroute) allows you to match on gRPC traffic and
    10  direct it to Kubernetes backends. This guide shows how the GRPCRoute matches
    11  traffic on host, header, and service, and method fields and forwards it to different
    12  Kubernetes Services.
    13  
    14  The following diagram describes a required traffic flow across three different
    15  Services:
    16  
    17  - Traffic to `foo.example.com` for the `com.Example.Login` method is forwarded to `foo-svc`
    18  - Traffic to `bar.example.com` with an `env: canary` header is forwarded
    19  to `bar-svc-canary` for all services and methods
    20  - Traffic to `bar.example.com` without the header is forwarded to `bar-svc` for
    21    all services and methods
    22  
    23  <!--- Editable source available at site-src/images/grpc-routing.png -->
    24  ![gRPC Routing](/images/grpc-routing.png)
    25  
    26  The dotted lines show the `Gateway` resources deployed to configure this routing
    27  behavior. There are two `GRPCRoute` resources that create routing rules on the
    28  same `prod` Gateway. This illustrates how more than one Route can bind to a
    29  Gateway which allows Routes to merge on a `Gateway` as long as they don't
    30  conflict. `GRPCRoute` follows the same Route merging semantics. For more
    31  information on that, refer to the [documentation](/api-types/httproute#merging).
    32  
    33  In order to receive traffic from a [Gateway][gateway], a `GRPCRoute` resource
    34  must be configured with `ParentRefs` which reference the parent gateway(s) that it
    35  should be attached to. The following example shows how the combination
    36  of `Gateway` and `GRPCRoute` would be configured to serve gRPC traffic:
    37  
    38  ```yaml
    39  {% include 'experimental/v1alpha2/grpc-routing/gateway.yaml' %}
    40  ```
    41  
    42  A `GRPCRoute` can match against a [single set of hostnames][spec].
    43  These hostnames are matched before any other matching within the GRPCRoute takes
    44  place. Since `foo.example.com` and `bar.example.com` are separate hosts with
    45  different routing requirements, each is deployed as its own GRPCRoute -
    46  `foo-route` and `bar-route`.
    47  
    48  The following `foo-route` will match any traffic for `foo.example.com` and apply
    49  its routing rules to forward the traffic to the correct backend. Since there is
    50  only one match specified, only requests for the `com.example.User.Login` method to
    51  `foo.example.com` will be forwarded. RPCs of any other method` will not be matched
    52  by this Route.
    53  
    54  ```yaml
    55  {% include 'experimental/v1alpha2/grpc-routing/foo-grpcroute.yaml' %}
    56  ```
    57  
    58  Similarly, the `bar-route` GRPCRoute matches RPCs for `bar.example.com`. All
    59  traffic for this hostname will be evaluated against the routing rules. The most
    60  specific match will take precedence which means that any traffic with the `env:
    61  canary` header will be forwarded to `bar-svc-canary` and if the header is
    62  missing or does not have the value `canary` then it will be forwarded to `bar-svc`.
    63  
    64  ```yaml
    65  {% include 'experimental/v1alpha2/grpc-routing/bar-grpcroute.yaml' %}
    66  ```
    67  
    68  [gRPC
    69  Reflection](https://github.com/grpc/grpc/blob/v1.49.1/doc/server-reflection.md)
    70  is required to use interactive clients such as
    71  [`grpcurl`](https://github.com/fullstorydev/grpcurl) without having a local copy
    72  of the target service's protocol buffers present on your local filesysem. To
    73  enable this, first ensure that you have a gRPC reflection server listening on
    74  your application pods, then add the reflection method to your `GRPCRoute`. This
    75  is likely to be useful in development and staging environments, but this should
    76  be enabled in production environments only after the security implications have
    77  been considered.
    78  
    79  ```yaml
    80  {% include 'experimental/v1alpha2/grpc-routing/reflection-grpcroute.yaml' %}
    81  ```
    82  
    83  [gateway]: /reference/spec/#gateway.networking.k8s.io/v1beta1.Gateway
    84  [spec]: /reference/spec/#gateway.networking.k8s.io%2fv1alpha2.GRPCRouteSpec
    85  [svc]:https://kubernetes.io/docs/concepts/services-networking/service/