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
Example plugin configuration
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.name or route.id
Type: string |
The name or ID of the route the plugin targets.
Set one of these parameters if adding the plugin to a route through the top-level /plugins endpoint.
Not required if using /routes/ROUTE_NAME|ROUTE_ID/plugins . |
enabled
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: "3.0"
services:
- protocol: grpc
host: localhost
port: 9000
routes:
- protocols:
- name: 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.
See also
Introduction to Kong gRPC plugins
Changelog
Kong Gateway 2.6.x
- Fields of type
.google.protobuf.Timestamp
on the gRPC side are now transcoded to and from ISO8601 strings on the REST side. - URI arguments like
..?foo.bar=x&foo.baz=y
are interpreted as structured fields, equivalent to{"foo": {"bar": "x", "baz": "y"}}
.