Document updated on Mar 18, 2024
gRPC Server
The gRPC server integration allows you to expose an additional gRPC service under the same HTTP port. The gRPC service can consume data from mixed upstream services, whether they are also gRPC, HTTP, Lambdas, queues, or any other supported type.
Due to its nature, when you access the gateway through gRPC, you cannot use HTTP components in the user request (but you can work with the HTTP layer when connecting to your services). With this in mind, HTTP-specific components like CORS or HTTP Security aren’t loaded in this context.
gRPC server configuration
To configure a gRPC server, you must define the services available and which methods you want to offer. The services and methods are defined in the catalog
definition, and in the services
section, you decide which ones to expose and where to connect them.
Each method is connected to one or more backends, which do not need to be gRPC.
The example below reads Protobuff definitions from the local folder ./grpc/definitions
and decides to expose the method FindFlight
service that belongs to the flight_finder.Flights
service:
{
"version": 3,
"grpc": {
"catalog": [
"./grpc/definitions"
],
"server": {
"services": [
{
"name": "flight_finder.Flights",
"methods": [
{
"name": "FindFlight",
"input_headers": [
"*"
],
"payload_params": {
"page.cursor": "cursor"
},
"backend": [
{
"host": [
"example.com:4242"
],
"url_pattern": "/flight_finder.Flights/FindFlight",
"extra_config": {
"backend/grpc": {
"use_request_body": true
}
}
},
{
"method": "GET",
"host": [
"http://example.com:8000"
],
"url_pattern": "/articles.json?q={cursor}"
}
]
}
]
}
]
}
}
}
As you can see in the example above, this gRPC server fetches content from one HTTP service and one gRPC service (the flight finder). The upstream gRPC service uses a gRPC Client configuration.
The accepted parameters are as follows:
Fields of gRPC server
catalog
* array- The paths to the different
.pb
files you want to load, or the paths to directories containing.pb
files. All content is scanned in the order of the list, and after fetching all files it resolves the dependencies of their imports. The order you use here is not important to resolve imports, but it matters when there are conflicts (different files using the same namespace and package type).Examples:"./grpc/flights.pb"
,"./grpc/definitions"
,"/etc/krakend/grpc"
server
object- Defines the gRPC server properties.
opentelemetry
object- Overrides OpenTelemetry settings for the gRPC server.
disable_metrics
boolean- Whether you want to disable all metrics happening in the gRPC server.Defaults to
false
disable_traces
boolean- Whether you want to disable all traces happening in the gRPC server.Defaults to
false
services
array- Defines one object per available gRPC service.Each item is an object with the following properties:
methods
array- The gRPC methods available for this service (this is not related with HTTP methods despite using the same name).Each item is an object with the following properties:
backend
array- An array with all the backend objects mapped to this method
extra_config
object- Extra configuration for this method
auth/validator
object- The JWT validation for this method. The configuration underneath is exactly as in the JWT validator
input_headers
array- Defines the list of all client headers that you can use as gRPC metadata.
By default, KrakenD won’t pass any header from the client to the backend. This list is case-insensitive. You can declare headers in lowercase, uppercase, or mixed.
An entry["X-Something"]
forwards a singleX-Something
header to the backend, ignoring everything else. A single star element["*"]
as value forwards everything to the backend (it’s safer to avoid this option).Examples:"X-Custom-Trace"
,"*"
Defaults to[]
name
string- The name of the published gRPC method.Example:
"FindFlight"
payload_params
object- Maps a property of the gRPC incoming payload to a
{parameter}
that you can inject and reuse in aurl_pattern
. It supports dot nation to access nested objects.Example:{"some.grpc.object":"param1"}
name
string- The name of the published gRPC service.Example:
"flight_finder.Flights"
gRPC server authorization
If your gRPC server requires authenticated users using JWT, then you need to add the information to the gRPC server under the extra_config
of the method, exactly as you do for JWT validation in endpoints.
Here is an example, notide the placement of the auth/validator
namespace:
{
"version": 3,
"grpc": {
"catalog": [
"./grpc/definitions"
],
"server": {
"services": [
{
"name": "flight_finder.Flights",
"methods": [
{
"name": "FindFlight",
"input_headers": [
"*"
],
"extra_config": {
"auth/validator": {
"alg": "RS256",
"audience": [
"http://api.example.com"
],
"roles_key": "http://api.example.com/custom/roles",
"roles": [
"user",
"admin"
],
"jwk_url": "https://identity.example.com/.well-known/jwks.json",
"cache": true
}
},
"payload_params": {
"page.cursor": "cursor"
},
"backend": [
{
"host": [
"example.com:4242"
],
"url_pattern": "/flight_finder.Flights/FindFlight",
"extra_config": {
"backend/grpc": {
"use_request_body": true
}
}
}
]
}
]
}
]
}
}
}