gRPC

Overview

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

For this example, you need to:

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

To make gRPC requests, you need a client that can invoke gRPC requests. You can use grpcurl as the client. Ensure that you have it installed on your local system.

Deploy a gRPC test application

echo "---
apiVersion: v1
kind: Service
metadata:
  name: grpcbin
  labels:
    app: grpcbin
spec:
  ports:
  - name: plaintext
    port: 9000
    targetPort: 9000
  - 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: kong/grpcbin
        name: grpcbin
        ports:
        - containerPort: 9000
        - containerPort: 9001
" | kubectl apply -f -

The results should look like this:

deployment.apps/grpcbin created
service/grpcbin created

Create a GRPCRoute

gRPC over HTTPS

All services are assumed to be either HTTP or HTTPS by default. We need to update the service to specify gRPC as the protocol by adding a konghq.com/protocol annotation.

The annotation grpcs informs Kong that this service is a gRPC (with TLS) service and not a HTTP service.

kubectl annotate service grpcbin 'konghq.com/protocol=grpcs'

The results should look like this:

service/grpcbin annotated

Create a certificate

1. Create a test certificate for the example.com hostname.

   OpenSSL 1.1.1

   OpenSSL 0.9.8

   openssl req -subj '/CN=example.com' -new -newkey rsa:2048 -sha256 \
     -days 365 -nodes -x509 -keyout server.key -out server.crt \
     -addext "subjectAltName = DNS:example.com" \
     -addext "keyUsage = digitalSignature" \
     -addext "extendedKeyUsage = serverAuth" 2> /dev/null;
     openssl x509 -in server.crt -subject -noout

   openssl req -subj '/CN=example.com' -new -newkey rsa:2048 -sha256 \
     -days 365 -nodes -x509 -keyout server.key -out server.crt \
     -extensions EXT -config <( \
      printf "[dn]\nCN=example.com\n[req]\ndistinguished_name = dn\n[EXT]\nsubjectAltName=DNS:example.com\nkeyUsage=digitalSignature\nextendedKeyUsage=serverAuth") 2>/dev/null;
     openssl x509 -in server.crt -subject -noout

   The results should look like this:

   OpenSSL 1.1.1

   OpenSSL 0.9.8

   subject=CN = example.com

   subject=CN = example.com

   Older OpenSSL versions, including the version provided with OS X Monterey, require using the alternative version of this command.

2. Create a Secret containing the certificate.

    kubectl create secret tls example.com --cert=./server.crt --key=./server.key
   

   The results should look like this:

    secret/example.com created
   

Route gRPC traffic

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

kubectl patch --type=json gateway kong -p='[

    {
        "op":"add",
        "path":"/spec/listeners/-",
        "value":{
            "name":"grpc",
            "port":443,
            "protocol":"HTTPS",
            "hostname":"example.com",
            "tls": {
                "certificateRefs":[{
                    "group":"",
                    "kind":"Secret",
                    "name":"example.com"
                 }]
            }
        }
    }
]'

gateway.gateway.networking.k8s.io/kong patched

echo 'apiVersion: gateway.networking.k8s.io/v1alpha2
kind: GRPCRoute
metadata:
  name: grpcbin
spec:
  parentRefs:
  - name: kong
  hostnames:
  - "example.com"
  rules:
  - backendRefs:
    - name: grpcbin
      port: 9001
' | kubectl apply -f -

grpcroute.gateway.networking.k8s.io/grpcbin created

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

ingress.networking.k8s.io/grpcbin created

Test the configuration

Use grpcurl to send a gRPC request through the proxy:

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

The results should look like this:

{
  "reply": "hello Kong"
}

gRPC over HTTP

All services are assumed to be either HTTP or HTTPS by default. We need to update the service to specify gRPC as the protocol by adding a konghq.com/protocol annotation.

The annotation grpc informs Kong that this service is a gRPC (with TLS) service and not a HTTP service.

kubectl annotate service grpcbin 'konghq.com/protocol=grpc'

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

For gRPC over HTTP (plaintext without TLS), configuration of Kong Gateway needs to be adjusted. By default Kong Gateway accepts HTTP/2 traffic with TLS on port 443. And HTTP/1.1 traffic on port 80. To accept HTTP/2 (which is required by gRPC standard) traffic without TLS on port 80, the configuration has to be adjusted.

kubectl set env deployment/kong-gateway -n kong 'KONG_PROXY_LISTEN=0.0.0.0:8000 http2, 0.0.0.0:8443 http2 ssl'

Caveat: Currently, Kong Gateway doesn’t offer simultaneous support of HTTP/1.1 and HTTP/2 without TLS on a single TCP socket. Hence it’s not possible to connect with HTTP/1.1 protocol, requests will be rejected. For HTTP/2 with TLS everything works seamlessly (connections are handled transparently). You may configure an alternative HTTP/2 port (e.g. 8080) if you require HTTP/1.1 traffic on port 80.

Route gRPC traffic

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

ingress.networking.k8s.io/grpcbin created

Test the configuration

Use grpcurl to send a gRPC request through the proxy:

grpcurl -plaintext -d '{"greeting": "Kong"}' -authority example.com $PROXY_IP:80 hello.HelloService.SayHello

The results should look like this:

{
  "reply": "hello Kong"
}