You are browsing unreleased documentation. See the latest documentation here.

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 TLS

All services are assumed to be either HTTP or HTTPS by default. We need to update the service to specify gRPC over TLS 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/v1
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 without TLS

All services are assumed to be either HTTP or HTTPS by default. We can update the service to specify gRPC as the protocol by adding a konghq.com/protocol annotation. If you do not perform this step, it will also default to using gRPC as the default protocol.

The annotation grpc informs Kong that this service is a gRPC (without 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 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: Kong Gateway 3.6.x and earlier 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. Since Kong Gateway 3.6.x, Kong Gateway is able to support listening HTTP/2 without TLS(h2c) and HTTP/1.1 on the same port, so you can use port 80 for both HTTP/1.1 and HTTP/2 without TLS.

Route gRPC traffic

echo 'apiVersion: gateway.networking.k8s.io/v1
kind: GRPCRoute
metadata:
  name: grpcbin
spec:
  parentRefs:
  - name: kong
  hostnames:
  - "example.com"
  rules:
  - backendRefs:
    - name: grpcbin
      port: 9000
' | 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: 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"
}