A Kong plugin to allow access to a gRPC service via HTTP REST requests and translate requests and responses in a JSON format. Similar to gRPC-gateway.
Configuration Reference
This plugin is compatible with DB-less mode.
In DB-less mode, you configure Kong Gateway declaratively. Therefore, the Admin API is mostly read-only. The only tasks it can perform are all related to handling the declarative config, including:
- Setting a target's health status in the load balancer
- Validating configurations against schemas
- Uploading the declarative configuration using the
/config
endpoint
Enable the plugin on a route
Enable the plugin globally
A plugin which is not associated to any service, route, or consumer is considered global, and will be run on every request. Read the Plugin Reference and the Plugin Precedence sections for more information.
Parameters
Here's a list of all the parameters which can be used in this plugin's configuration:
Form Parameter | Description |
---|---|
name
required Type: string |
The name of the plugin, in this case grpc-gateway . |
route.id
Type: string |
The ID of the Route the plugin targets. |
enabled
required Type: boolean Default value: true |
Whether this plugin will be applied. |
config.proto
optional Type: string |
Describes the gRPC types and methods. HTTP configuration must be defined in the file. |
Purpose
This plugin translates requests and responses between gRPC and HTTP REST.
Image credit: grpc-gateway
Usage
This plugin should be enabled on a Kong Route
that serves the http(s)
protocol
but proxies to a Service
with the grpc(s)
protocol.
Sample configuration via declarative (YAML):
_format_version: "1.1"
services:
- protocol: grpc
host: localhost
port: 9000
routes:
- protocols:
- http
paths:
- /
plugins:
- name: grpc-gateway
config:
proto: path/to/hello.proto
Sample configuration via the Admin API:
$ # add the gRPC service
$ curl -X POST localhost:8001/services \
--data name=grpc \
--data protocol=grpc \
--data host=localhost \
--data port=9000
$ # add an http route
$ curl -X POST localhost:8001/services/grpc/routes \
--data protocols=http \
--data name=web-service \
--data paths[]=/
$ # add the plugin to the route
$ curl -X POST localhost:8001/routes/web-service/plugins \
--data name=grpc-gateway
The proto file must contain the HTTP REST to gRPC mapping rule.
The example uses the following mapping:
syntax = "proto2";
package hello;
service HelloService {
rpc SayHello(HelloRequest) returns (HelloResponse) {
option (google.api.http) = {
get: "/v1/messages/{name}"
additional_bindings {
get: "/v1/messages/legacy/{name=**}"
}
post: "/v1/messages/"
body: "*"
}
}
}
// The request message containing the user's name.
message HelloRequest {
string name = 1;
}
// The response message containing the greetings
message HelloResponse {
string message = 1;
}
Note the option (google.api.http) = {}
section is required.
You can send the following requests to Kong that translate to the corresponding gRPC requests:
curl -XGET localhost:8000/v1/messages/Kong2.0
{"message":"Hello Kong2.0"}
curl -XGET localhost:8000/v1/messages/legacy/Kong2.0
{"message":"Hello Kong2.0"}
curl -XGET localhost:8000/v1/messages/legacy/Kong2.0/more/paths
{"message":"Hello Kong2.0\/more\/paths"}
curl -XPOST localhost:8000/v1/messages/Kong2.0 -d '{"name":"kong2.0"}'
{"message":"Hello kong2.0"}
All syntax defined in Path template syntax is supported.
Object fields not mentioned in the endpoint paths as in /messages/{name}
can be passed as URL arguments, for example /v1/messages?name=Kong
. Structured arguments are supported.
For example, a request like the following:
/v1/messages?dest.name=Freddy&dest.address=1428+Elm+Street&message=One+Two...
is interpreted like the following JSON object:
{
"dest": {
"name": "Freddy",
"address": "1428 Elm Street"
},
"message": "One Two..."
}
Similarly, fields of the type google.protobuf.Timestamp
are converted to and from strings in ISO8601 format.
Currently only unary requests are supported; streaming requests are not supported.