gRPC PR description

grpc_pr.md

Summary

This PR adds native gRPC proxying support to Kong. New named location blocks -- grpc and grpcs were added to the Kong Nginx template. Incoming gRPC requests are redirected to said locations, where a grpc_pass happens -- as opposed to proxy_pass. New protocols were added for gRPC and gRPCs, which can be specified, e.g., upon Route and Service creation.

Examples

The following example shows how to create a gRPC Service and Route. grpcbin and grpcurl are used in these examples.

Single Service and Route

1. Enable an HTTP/2 listener; refer to the docs for how to:

KONG_PROXY_LISTEN="0.0.0.0:9080 http2" bin/kong restart -c kong.conf.default

2. Create the gRPC Service and Route:

$ curl -XPOST localhost:8001/services --data name=s1 --data protocol=grpc --data host=localhost --data port=15002

$ curl -XPOST localhost:8001/services/s1/routes --data protocols=grpc --data paths=/

3. Using a gRPC client, issue a gRPC request:

$ grpcurl -v -d '{"greeting": "Kong!"}' -plaintext localhost:9080 hello.HelloService.SayHello

Resolved method descriptor:
rpc SayHello ( .hello.HelloRequest ) returns ( .hello.HelloResponse );

Request metadata to send:
(empty)

Response headers received:
content-type: application/grpc
date: Tue, 16 Jul 2019 21:37:36 GMT
server: openresty/1.15.8.1
via: kong/1.2.1
x-kong-proxy-latency: 0
x-kong-upstream-latency: 0

Response contents:
{
  "reply": "hello Kong!"
}

Response trailers received:
(empty)
Sent 1 request and received 1 response

Single Service, Multiple Routes

Different Routes can be created for different gRPC services or methods. Let's create two additional routes, one routing to the SayHello method, and the other routing to the LotsOfReplies method (check out the gRPC service's protobuf here):

$ curl -XPOST localhost:8001/services/s1/routes --data protocols=grpc --data paths=/hello.HelloService/SayHello

curl -XPOST localhost:8001/services/s1/routes --data protocols=grpc --data paths=/hello.HelloService/LotsOfReplies

With this setup, gRPC requests to the SayHello method will go to the former, while requests to LotsOfReplies will be routed to the latter. (Note: gRPC reflection requests will still be routed to the first route we created, since the request won't match neither of SayHello nor LotsOfReplies routes.)

Issue a gRPC request to SayHello and LotsOfReplies:

$ grpcurl -v -d '{"greeting": "Kong!"}' -H 'kong-debug: 1' -plaintext localhost:9080 hello.HelloService.SayHello

Resolved method descriptor:
rpc SayHello ( .hello.HelloRequest ) returns ( .hello.HelloResponse );

Request metadata to send:
kong-debug: 1

Response headers received:
content-type: application/grpc
date: Tue, 16 Jul 2019 21:57:00 GMT
kong-route-id: 390ef3d1-d092-4401-99ca-0b4e42453d97
kong-service-id: d82736b7-a4fd-4530-b575-c68d94c3493a
kong-service-name: s1
server: openresty/1.15.8.1
via: kong/1.2.1
x-kong-proxy-latency: 0
x-kong-upstream-latency: 0

Response contents:
{
  "reply": "hello Kong!"
}

Response trailers received:
(empty)
Sent 1 request and received 1 response

Notes

• gRPC over HTTP/2 is assumed
• Not all Kong plugins are supported with gRPC yet. As of writing, only logging and observability plugins are planned to be supported in Kong 1.3
• Integration tests will be added for plugins with gRPC
• Documentation PR will be created on the docs repository