gRPC Proxy
Using Tyk as a gRPC Proxy
Tyk supports gRPC passthrough proxying when using HTTP/2 as a transport (the most common way to deploy gRPC services).
You also need to set your listen_path
in your API definition and a specific port where the service will be exposed.
The gRPC over HTTP2 specification defines the rules on how the gRPC protocol maps to a HTTP request, for more information see. In the context of the API Gateway, we are interested in the following:
- You can target specific methods of the gRPC service using the format:
/{Service-Name}/{method name}
, for example:/google.pubsub.v2.PublisherService/CreateTopic
. You can use this feature to apply standard ACL rules via Keys and Policies, or use URL rewrite plugins in our Endpoint Desiger. - HTTP method is always
POST
. gRPC custom request metadata is added as HTTP headers, where metadata key is directly mapped to the HTTP header with the same name.
You can also perform gRPC load balancing.
Prerequisites
- Enable HTTP/2 support on the Gateway side, for both incoming and upstream connections, by setting
http_server_options.enable_http2
to true in your Gateway config file. - Set
disable_ports_whitelist
to true, so the gateway can use additional ports to expose the service.
Secure gRPC Proxy
Tyk Supports secure gRPC proxy connections, in order to do so you only need to attach a certificate to the API that you want to expose just as you do for regular apis, after that you can consume the service via https.
Insecure gRPC Proxy (H2C)
For those scenarios that you want to connect 2 services that call each other or just need an insecure connection you can use h2c (that is the non-TLS version of HTTP/2). Tyk supports h2c, this can be enabled at api level by setting h2c
as protocol in the address of the gRPC server (target_url
) e.g: h2c://my-grpc-server.com
.
gRPC streaming
Tyk supports gRPC streaming, it only requires to set a low value for flush_interval
, a low flush interval is required in order to forward data to the downstream as soon as the upstream replies. A high flush interval would delay the communication. We recommend the lowest possible value: 1 (1 millisecond), you can set this value in the gateway config http_server_options.flush_interval
Mutual Authentication
Tyk supports Mutual Authentication in gRPC. See Mutual TLS to configure Mutual Authentication in Tyk.
Basic Authentication
Tyk supports Basic Authentication in gRPC. See Basic Authentication to configure Basic Authentication in Tyk.
After setting your Tyk configuration, all you need to do is to send credentials with the correct base64 format in an Authorization
header from your gRPC client.
Basic base64Encode(username:password)
Token Based Authentication
Tyk supports Token Based Authentication in gRPC. See Bearer Tokens to configure Token Based Authentication in Tyk.
After setting your Tyk configuration, all you need to do is to send a token in an Authorization
header from your gRPC client.
Example of gRPC proxy using H2C
This is the simplest way to have a working gRPC proxy setup, in order to do so we will need:
- A gRPC server, for this example we will use this server
- A gRPC client, we will use grpcurl which is basically curl but for gRPC
- An instance of Tyk gateway and dashboard
Steps:
- Execute the gRPC server (for this example we will expose it at port
:50051
) - Create the API via dashboard with the next configuration:
- Set HTTP as protocol
- Set a custom port to expose the api. Let’s use
12345
- Set listen path:
/
- Now, let’s set the
target_url
, in order to tyk to detect that we will useh2c
for this api we will need to write the url with the prefixh2c://
, so for this example the value ish2c://localhost:50051
- Hit save, and once the gateway finish the reload we can test the solution
- From the command line we can consume the service via tyk gateway, just type
grpcurl -plaintext -proto helloworld.proto -d '{"name": "joe"}' tyk-gateway:12345 helloworld.Greeter/SayHello
and we get as response:{"message": "Hello joe"}
which means that everything went as it should.
Example of gRPC proxy using HTTPS
Prerequisites:
- a gRPC server, for this example we will use this server as this example already supports TLS.
- A gRPC client, we will use grpcurl which is basically curl but for gRPC (or you can use the client application)
- A certificate to expose the API via HTTPS
- An instance of Tyk gateway and dashboard
Steps:
- Execute the gRPC server (for this example we will expose it at port
:10000
), theroute_guide
application receives a flag to use TLS (go run server.go -tls=true
). It’s exposed ingrpc.test.example.com:10000
- Create the API via dashboard with the next configuration:
- Set HTTPS as protocol
- Set a custom port to expose the api. Let’s use
4444
- Add the certificate
- Set a custom domain, for this example will set
tyk
- Set as listen path:
/
- Now in target URL we will set the location of the service:
https://grpc.test.example.com:10000
- Hit save
- At this point we’re ready to test the solution, so, from the command line will type:
grpcurl -proto route_guide.proto -d '{"latitude": 1, "longitude":2}' tyk:4444 routeguide.RouteGuide/GetFeature
and we should get a successful response, note that we are not sending the flag-plaintext
as our desire is to connect via HTTPS.
gRPC load balancing
Tyk is able to perform load balancing on gRPC traffic using an approach similar to our native Load Balancing functionality.
For both secure and insecure gRPC scenarios, the above steps serve as a starting point.
For configuring multiple upstream targets in a secure gRPC scenario, follow these additional steps:
- Check the “Enable round-robin load balancing” flag in the “Core Settings” section of your API.
- Define each target as
https://grpc.test.example.com:10000
,https://grpc.test.example.com:10001
and so on.
For insecure scenarios (H2C) use the same approach but use the H2C scheme instead: h2c://grpc.test.example.com:10000
, h2c://grpc.test.example.com:10001
, etc.