gRPC and the open source Ambassador API Gateway

gRPC is a high performance RPC protocol built on HTTP/2. We're seeing more and more companies move their APIs from HTTP/JSON to gRPC. gRPC offers numerous benefits over HTTP/JSON:

• Performance. gRPC uses HTTP/2, with support for streaming, multiplexing, and more (see the difference in action). In addition, gRPC has native support for protobuf, which is much faster at serialization / deserialization than JSON.
• Streaming. Despite its name, gRPC also supports streaming, which opens up a much wider range of use cases.
• Code generation of endpoints. gRPC uses code generation from API definitions (.proto files) to stub out your endpoints.

gRPC does have a few downsides, the biggest of which is probably that it's much newer than HTTP/REST, and as such, the maturity of tools and libraries around gRPC isn't anywhere close to HTTP.

One of these gaps is in API Gateways. Many API Gateways don't support gRPC. Fortunately, Ambassador does support gRPC, thanks to the fact that it uses Envoy as its core proxying engine.

API Gateways and gRPC

An API Gateway implements cross-cutting functionality such as authentication, logging, rate limiting, and load balancing. By using an API Gateway with your gRPC APIs, you are able to deploy this functionality outside of your core gRPC service(s). Moreover, Ambassador is able to provide this functionality for both your HTTP and gRPC services.

Ambassador and gRPC

Deploying a gRPC service with Ambassador is straightforward. After installing Ambassador, create an Ambassador mapping for your gRPC service. An example mapping would look like the following:

--------
apiVersion: ambassador/v0
kind: Mapping
name: grpc_mapping
grpc: true
prefix: /helloworld.Greeter/
rewrite: /helloworld.Greeter/
service: grpc-greet

Note that gRPC services are not routed like HTTP services. Instead, gRPC requests include the package and service name. This information is used to route the request to the appropriate service. We set the prefix and rewritefields accordingly based on the .proto file. Also, note that we set grpc: trueto tell Ambassador that the service speaks gRPC.

Deploying a gRPC service

We can deploy a simple Hello, World gRPC service to illustrate all this functionality. Copy-and-paste the full YAML below into a file called helloworld.yaml:

--------
apiVersion: v1
kind: Service
metadata:
  labels:
    service: grpc-greet
  name: grpc-greet
  annotations:
    getambassador.io/config: |
      ---
      apiVersion: ambassador/v0
      kind: Mapping
      name: grpc_mapping
      grpc: true
      prefix: /helloworld.Greeter/
      rewrite: /helloworld.Greeter/
      service: grpc-greet
spec:
  type: ClusterIP
  ports:
  - port: 80
    name: grpc-greet
    targetPort: grpc-api
  selector:
    service: grpc-greet
--------
apiVersion: extensions/v1beta1
kind: Deployment
metadata:
  name: grpc-greet
spec:
  replicas: 1
  template:
    metadata:
      labels:
        service: grpc-greet
    spec:
      containers:
      - name: grpc-greet
        image: enm10k/grpc-hello-world
        ports:
        - name: grpc-api
          containerPort: 9999
        env:
          - name: PORT
            value: "9999"
        command:
          - greeter_server
      restartPolicy: Always

Then, run kubectl apply -f helloworld.yaml.

The Hello World client

In order to test that Ambassador and the service are working properly, we'll need to run a gRPC client. First, get the external IP address of Ambassador. You can do this with kubectl get svc ambassador.

We'll use a Docker image that already contains the appropriate Hello World gRPC client. Type, where $AMBASSADOR_IP is set to the external IP address above, and $AMBASSADOR_PORT is set to 80 (for HTTP-based Ambassador) or 443 (for a TLS-configured Ambassador).

docker run -e ADDRESS=${AMBASSADOR_IP}:${AMBASSADOR_PORT} enm10k/grpc-hello-world greeter_client

You should see something like the following:

$ docker run -e ADDRESS=35.29.51.15:80 enm10k/grpc-hello-world greeter_client
2018/02/02 20:34:35 Greeting: Hello world

Summary

Ambassador makes it easy to publish gRPC services to your consumers, thanks to Envoy's robust gRPC support. By publishing your services through Ambassador, you're able to add authentication, rate limiting, and other functionality to your gRPC services.

If you're interested in using Ambassador with gRPC, join our Gitter chat or visit https://www.getambassador.io.