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.

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

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

apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: <grpc-gateway-example>
config: 
  proto: path/to/hello.proto
plugin: grpc-gateway

apiVersion: networking/v1beta1
kind: Ingress
metadata:
  name: {ROUTE}
  annotations:
    kubernetes.io/ingress.class: kong
    konghq.com/plugins: <grpc-gateway-example>
spec:
  rules:
  - host: examplehostname.com
    http:
      paths:
      - path: /bar
        backend:
          serviceName: echo
          servicePort: 80

plugins:
- name: grpc-gateway
  route: <route>
  config: 
    proto: path/to/hello.proto

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.

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

apiVersion: configuration.konghq.com/v1
kind: KongClusterPlugin
metadata:
  name: <global-grpc-gateway>
  annotations:
    kubernetes.io/ingress.class: kong
  labels:
    global: \"true\"
config: 
  proto: path/to/hello.proto
plugin: grpc-gateway

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

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 -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