There are a lot of advantages to using gRPC instead of HTTP/JSON when building new APIs, like HTTP/2, streaming, cross-language support, server push, etc. The hardest part tends to be legacy services that expect HTTP/JSON. This is why gRPC-JSON transcoding is so attractive: we can implement gRPC servers but expose them to legacy services with a HTTP/JSON interface. Typically, we would use the gRPC Gateway or a product like Google Cloud Endpoints to handle gRPC-JSON transcoding for us, but Envoy implements transcoding too!

Envoy implements gRPC transcoding as a filter. At Tetrate, we use Istio as the control plane for our Envoy sidecars, and Istio allows for custom Envoy configuration via its EnvoyFilter CRD. To take advantage of this, we created a small tool, gen-transcoder, which scans gRPC proto descriptors to automatically generate accurate Envoy filter configs. It also supports features like filtering the services or packages in the descriptor that are exposed as HTTP/JSON by Envoy. gen-transcoderß is built to be friendly with CI/CD workflows too. At Tetrate, we use it to automate the delivery of gRPC-JSON transcoder configs as part of our normal service deployment.

Using gen-transcoder is a simple 2-step process:

Step 1: Generate proto descriptors during proto compilation

 protoc \
	-I path/to/google/protobufs \
	-I path/to/your/protos \
	--descriptor_set_out=path/to/output/dir/YOUR_SERVICE_NAME.proto-descriptor \
	--include_imports \
	--go_out=plugins=grpc:. \

Step 2: Use gen-transcoder to generate Istio Envoy proxy configuration

 gen-transcoder \
	--port 9080 \
	--service foo \
	--packages \
	--services='Service.*' \

As part of this, we have included a few sample proto services, compiled into a single proto descriptor that you can use in the following way.

 gen-transcoder \
	--port 9080 \
	--service echo \
	--packages proto \
	--services 'Echo.*' \
	--descriptor \

This emits an EnvoyFilter specifically for service proto.EchoService in package proto.

We’d love you to try the tool yourself. You can download the source here. See for further details.

As a warning, Istio’s EnvoyFilter must be used with care, though! If a bad filter config is pushed Envoy will reject configuration updates and stop serving – an outage we at Tetrate experienced before writing this tool.