You are browsing documentation for an outdated version. See the latest documentation here.

Exposing a gRPC service

Installation

Please follow the deployment documentation to install the Kong Ingress Controller onto your Kubernetes cluster.

Prerequisite

To make gRPC requests, you need a client that can invoke gRPC requests. In this guide, we use grpcurl. Ensure that you have it installed on your local system.

Test connectivity to Kong

This guide assumes that the PROXY_IP environment variable is set to contain the IP address or URL pointing to Kong. If you haven’t done so, follow one of the deployment guides to configure the PROXY_IP environment variable.

If everything is set up correctly, Kong returns HTTP 404 Not Found since the system does not know yet how to proxy the request.

curl -i $PROXY_IP
HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8
Connection: keep-alive
Content-Length: 48
Server: kong/1.2.1

{"message":"no Route matched with those values"}

Run gRPC

Add a gRPC deployment and service:

 kubectl apply -f https://raw.githubusercontent.com/Kong/kubernetes-ingress-controller/v2.11.0/deploy/manifests/sample-apps/grpc.yaml
 service/grpcbin created
 deployment.apps/grpcbin created

Create a demo gRPC ingress rule:

 echo "apiVersion: networking.k8s.io/v1
 kind: Ingress
 metadata:
   name: demo
   annotations:
     kubernetes.io/ingress.class: kong
 spec:
   rules:
   - http:
       paths:
       - path: /
         backend:
           serviceName: grpcbin
           servicePort: 9001" | kubectl apply -f -
 ingress.extensions/demo created

Next, we need to update the Ingress rule to specify gRPC as the protocol. By default, all routes are assumed to be either HTTP or HTTPS. This annotation informs Kong that this route is a gRPC(s) route and not a plain HTTP route:
```
 kubectl patch ingress demo -p '{"metadata":{"annotations":{"konghq.com/protocols":"grpc,grpcs"}}}'
```
We also update the upstream protocol to be grpcs. Similar to routes, Kong assumes that services are HTTP-based by default. With this annotation, we configure Kong to use gRPCs protocol when it talks to the upstream service:
```
 kubectl patch svc grpcbin -p '{"metadata":{"annotations":{"konghq.com/protocol":"grpcs"}}}'
```

You should be able to run a request over gRPC:

 grpcurl -v -d '{"greeting": "Kong Hello world!"}' -insecure $PROXY_IP:443 hello.HelloService.SayHello