gRPC-JSON reverse transcoder

  • gRPC architecture overview

  • This filter should be configured with the type URL type.googleapis.com/envoy.extensions.filters.http.grpc_json_reverse_transcoder.v3.GrpcJsonReverseTranscoder.

  • v3 API reference

This is a filter which allows a gRPC client to send requests to Envoy and get proxied to a RESTful JSON API service. The HTTP mapping for the gRPC service has to be defined by custom options.

Unsupported options from google.api.http

  • additional_binding: The gRPC-JSON reverse transcoder ignores this options, if set, as it makes binding a gRPC method to a single HTTP endpoint difficult.

  • response_body: The gRPC-JSON reverse transcoder uses the whole response from the upstream service as a response to the gRPC client and ignores this options, if set.

JSON mapping

The protobuf to JSON mapping is defined here.

  • NOTE: The gRPC-JSON reverse transcoder uses the proto field names as the JSON field names by default. This behavior can be overridden by setting use_canonical_field_names field to true. With this the transcoder will convert the proto field names to json_name annotation value, or lower camel case in absence of json_name annotation.

How to generate proto descriptor set

Envoy has to know the proto descriptor of your gRPC service in order to do the transcoding.

To generate a protobuf descriptor set for the gRPC service, you’ll also need to clone the googleapis repository from GitHub before running protoc, as you’ll need annotations.proto in your include path, to define the HTTP mapping.

$ git clone https://github.com/googleapis/googleapis
$ GOOGLEAPIS_DIR=<your-local-googleapis-folder>

Then run protoc to generate the descriptor set. For example using the test bookstore.proto provided in the Envoy repository:

$ protoc -I${GOOGLEAPIS_DIR} -I. --include_imports --include_source_info \
    --descriptor_set_out=proto.pb test/proto/bookstore.proto

If you have more than one proto source files, you can pass all of them in one command.

Sample Envoy configuration

Here’s a sample Envoy configuration that proxies to a RESTful JSON server running on localhost:50051. Port 51051 proxies HTTP requests and uses the gRPC-JSON reverse transcoder filter to provide the gRPC mapping. I.e., you can make either gRPC or RESTful JSON requests to localhost:51051.

grpc-json-reverse-transcoder-filter.yaml
 1    - filters:
 2      - name: envoy.filters.network.http_connection_manager
 3        typed_config:
 4          "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
 5          stat_prefix: ingress_http
 6          access_log:
 7          - name: envoy.access_loggers.stdout
 8            typed_config:
 9              "@type": type.googleapis.com/envoy.extensions.access_loggers.stream.v3.StdoutAccessLog
10          http_filters:
11          - name: envoy.filters.http.grpc_json_reverse_transcoder
12            typed_config:
13              "@type": type.googleapis.com/envoy.extensions.filters.http.grpc_json_reverse_transcoder.v3.GrpcJsonReverseTranscoder
14              descriptor_path: protos/helloworld.pb
15          - name: envoy.filters.http.router
16            typed_config:
17              "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
18          route_config:
19            name: local_route
20            virtual_hosts:
21            - name: local_service
22              domains: ["*"]
23              routes:
24              - match:
25                  prefix: "/"
26                route:
27                  cluster: rest_backend