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

Exposing a gRPC service

Overview

This guide walks through deploying a simple Service that listens for gRPC connections and exposes this service outside of the cluster using Kong Gateway.

For this example, you will:

Deploy a gRPC test application.
Route gRPC traffic to it using Ingress or GRPCRoute.

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.

Prerequisites: Install Kong Ingress Controller in your Kubernetes cluster and connect to Kong.

Prerequisites

Install Kong

You can install Kong in your Kubernetes cluster using Helm.

Add the Kong Helm charts:

 helm repo add kong https://charts.konghq.com
 helm repo update

Install Kong Ingress Controller and Kong Gateway with Helm:

 helm install kong kong/ingress -n kong --create-namespace 

Test connectivity to Kong

Kubernetes exposes the proxy through a Kubernetes service. Run the following commands to store the load balancer IP address in a variable named PROXY_IP:

Populate $PROXY_IP for future commands:

 export PROXY_IP=$(kubectl get svc --namespace kong kong-gateway-proxy -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
 echo $PROXY_IP

Ensure that you can call the proxy IP:

 curl -i $PROXY_IP

The results should look like this:

 HTTP/1.1 404 Not Found
 Content-Type: application/json; charset=utf-8
 Connection: keep-alive
 Content-Length: 48
 X-Kong-Response-Latency: 0
 Server: kong/3.0.0
  
 {"message":"no Route matched with those values"}

Deploy a gRPC test application

By default, Kong considers all services to be HTTP-based. You need to configure Kong to use gRPCs protocol when it talks to the upstream service using the konghq.com/protocol annotation.

echo "---
apiVersion: v1
kind: Service
metadata:
  name: grpcbin
  labels:
    app: grpcbin
  annotations:
    konghq.com/protocol: grpcs
spec:
  ports:
  - name: tls
    port: 9001
    targetPort: 9001
  selector:
    app: grpcbin
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: grpcbin
spec:
  replicas: 1
  selector:
    matchLabels:
      app: grpcbin
  template:
    metadata:
      labels:
        app: grpcbin
    spec:
      containers:
      - image: moul/grpcbin
        name: grpcbin
        ports:
        - containerPort: 9001
" | kubectl apply -f -        

Response:

deployment.apps/grpcbin created
service/grpcbin created

Route GRPC traffic

Now that the test application is running, you can create GRPC routing configuration that proxies traffic to the application.

All routes are assumed to be either HTTP or HTTPS by default. You need to update the Ingress rule to specify gRPC as the protocol by adding a konghq.com/protocols annotation.

This annotation informs Kong that this route is a gRPC route and not a plain HTTP route

echo "apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: demo
  annotations:
    konghq.com/protocols: grpcs
spec:
  ingressClassName: kong
  rules:
  - http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service: 
            name: grpcbin
            port: 
              number: 9001" | kubectl apply -f -

The results should look like this:

ingress.networking.k8s.io/demo created

Test the configuration

Use grpcurl to send a gRPC request through the proxy:

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

The results should look like this:

{
  "reply": "hello Kong"
}