gRPC-gateway

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.

Terminology

• plugin: a plugin executing actions inside Kong before or after a request has been proxied to the upstream API.
• Service: the Kong entity representing an external upstream API or microservice.
• Route: the Kong entity representing a way to map downstream requests to upstream services.
• Upstream service: this refers to your own API/service sitting behind Kong, to which client requests are forwarded.

Configuration

This plugin is compatible with requests with the following protocols:

• http
• https

This plugin is compatible with DB-less mode.

Enabling the plugin on a Route

$ curl -X POST http://kong:8001/routes/{route}/plugins \
    --data "name=grpc-gateway"  \
    --data "config.proto=path/to/hello.proto"

plugins:
- name: grpc-gateway
  route: {route}
  config: 
    proto: path/to/hello.proto

{route} is the id or name of the Route that this plugin configuration will target.

Global plugins

A plugin which is not associated to any Service, Route, or Consumer (or API, if you are using an older version of Kong) is considered "global", and will be run on every request. Read the Plugin Reference and the Plugin Precedence sections for more information.

• Using a database, all plugins can be configured using the http://kong:8001/plugins/ endpoint.
• Without a database, all plugins can be configured via the plugins: entry on the declarative configuration file.

Parameters

Here's a list of all the parameters which can be used in this plugin's configuration:

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 -XPOST localhost:8001/services \
  --data name=grpc \
  --data protocol=grpc \
  --data host=localhost \
  --data port=9000

$ # add an http route
$ curl -XPOST localhost:8001/services/grpc/routes \
  --data protocols=http \
  --data name=web-service \
  --data paths[]=/

$ # add the plugin to the route
$ curl -XPOST 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 HelloReply {
  string message = 1;
}

Note the option (google.api.http) = {} section is required.

You can send following requests to Kong that translates to 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.

Currently only unary requests are supported; streaming requests are not supported.