Exposing a gRPC application using the Traefik ingress controller

gRPC is often designed for service-to-service traffic inside a cluster, but there are plenty of reasons to reach one from outside it. You might have external clients, a partner integration, or another cluster in a different cloud that needs to call your service directly.

gRPC is a high-performance RPC framework from Google that runs over HTTP/2 and encodes its messages with Protocol Buffers. That HTTP/2 transport is exactly why you cannot just point an ordinary ingress rule at a gRPC service and expect it to work. The proxy in front of it has to speak HTTP/2 to the backend, and most controllers assume plain HTTP/1.1 unless you tell them otherwise.

This tutorial exposes a gRPC service through Traefik, a fast and lightweight ingress controller you can run on Civo Kubernetes. Traefik can speak HTTP/2 cleartext (h2c) to a gRPC backend, and it can terminate TLS at the edge.

Prerequisites

• A Civo account
• The Civo CLI installed and authenticated (civo apikey save <name> <key>)
• kubectl and helm installed and on your PATH
• grpcurl installed, to call the service once it is exposed
• Familiarity with Kubernetes Deployments, Services, and Ingress

Launching a cluster using the Civo CLI

Create a two-node cluster to work in:

1civo k3s create --create-firewall --nodes 2 --size g4s.kube.medium \
2  --save --switch --wait grpc-demo

The --save --switch flags merge the new cluster into your kubeconfig and make it the current context. Confirm the nodes are ready:

1kubectl get nodes
2NAME                                              STATUS   ROLES    AGE   VERSION
3k3s-grpc-demo-xxxx-node-pool-yyyy-aaaaa            Ready    <none>   2m    v1.35.0+k3s1
4k3s-grpc-demo-xxxx-node-pool-yyyy-bbbbb            Ready    <none>   2m    v1.35.0+k3s1

Installing Traefik

Install Traefik with Helm and ask for a Civo Load Balancer so it gets a public IP:

1helm repo add traefik https://traefik.github.io/charts
2helm repo update
3
4
5helm install traefik traefik/traefik \
6  --namespace traefik --create-namespace \
7  --set service.type=LoadBalancer \
8  --wait

Wait for Civo to attach a public IP to the Traefik Service:

1kubectl -n traefik get svc traefik
2NAME      TYPE           CLUSTER-IP    EXTERNAL-IP     PORT(S)                      AGE
3traefik   LoadBalancer   10.43.14.41   212.2.240.191   80:30853/TCP,443:30211/TCP   2m

Deploying a gRPC application

We'll use grpcbin, a small public gRPC server that exposes a handful of test methods and, importantly, has server reflection turned on. Reflection lets grpcurl discover the available methods without you having to supply the .proto files by hand, which makes verifying the setup much easier.

Deploy it, exposing the plaintext gRPC port 9000:

1kubectl apply -f - <<'EOF'
2apiVersion: apps/v1
3kind: Deployment
4metadata:
5  name: grpcbin
6spec:
7  replicas: 2
8  selector:
9    matchLabels:
10      app: grpcbin
11  template:
12    metadata:
13      labels:
14        app: grpcbin
15    spec:
16      containers:
17        - name: grpcbin
18          image: moul/grpcbin
19          ports:
20            - containerPort: 9000
21---
22apiVersion: v1
23kind: Service
24metadata:
25  name: grpcbin
26spec:
27  selector:
28    app: grpcbin
29  ports:
30    - name: grpc
31      port: 9000
32      targetPort: 9000
33EOF
34

Check that both replicas are running:

1---
2apiVersion: apps/v1
3kind: Deployment
4metadata:
5  name: randrpc-server-deployment
6spec:
7  replicas: 2
8  selector:
9    matchLabels:
10      app: randrpc-server
11  template:
12    metadata:
13      labels:
14        app: randrpc-server
15    spec:
16      containers:
17      - name: randrpc-server
18        image: ghcr.io/s1ntaxe770r/randrpc-server:v1.5
19        ports:
20        - containerPort: 7070
21---
22apiVersion: v1
23kind: Service
24metadata:
25  name: randrpc-server-svc
26spec:
27  selector:
28    app: randrpc-server
29  port:
30  - port: 80
31    targetPort: 7070
32    type: ClusterIP

Two grpcbin replicas, ready to answer gRPC calls.

Exposing the service over TLS

Civo gives your ingress a public IP through a Civo Load Balancer. We'll build a nip.io hostname from that IP so you don't need to own a domain. Grab the IP that Traefik is serving on:

1LB_IP=$(kubectl -n traefik get svc traefik \
2  -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
3HOST=grpc.${LB_IP}.nip.io
4echo "Using HOST=$HOST"

Now create an IngressRoute on the secure entrypoint. The one field that makes this a gRPC route rather than an ordinary HTTP one is scheme: h2c on the service, which tells Traefik to speak HTTP/2 cleartext to the backend. The empty tls: {} block tells Traefik to terminate TLS on this route, using its built-in certificate for now:

1kubectl apply -f - <<EOF
2apiVersion: traefik.io/v1alpha1
3kind: IngressRoute
4metadata:
5  name: grpcbin
6spec:
7  entryPoints:
8    - websecure
9  routes:
10    - match: Host(\`${HOST}\`)
11      kind: Rule
12      services:
13        - name: grpcbin
14          port: 9000
15          scheme: h2c
16  tls: {}
17EOF

Calling the gRPC service

Traefik is now terminating TLS with its own built-in certificate, which is not signed by a public authority, so we pass grpcurl the -insecure flag to skip certificate verification for this test. (The next section covers swapping in a trusted certificate so you can drop the flag.)

With reflection enabled on grpcbin, grpcurl can list the services the server exposes. Point it at your hostname on port 443:

1grpcurl -insecure ${HOST}:443 list
2addsvc.Add
3grpc.gateway.examples.examplepb.ABitOfEverythingService
4grpc.reflection.v1alpha.ServerReflection
5grpcbin.GRPCBin
6hello.HelloService

Now call one of the methods. The hello.HelloService/SayHello method takes a greeting and echoes it back:

1grpcurl -insecure -d '{"greeting": "Civo"}' ${HOST}:443 hello.HelloService.SayHello
2{
3  "reply": "hello Civo"
4}

Reflection lists every service on the backend, and SayHello returns through Traefik over TLS and h2c.

Your request travelled from the client, over HTTP/2 with TLS to Traefik, and on to the gRPC backend as h2c, exactly the path a real external client would take.

Serving a trusted certificate with Let's Encrypt

The -insecure flag is fine for a quick test, but real clients expect a certificate signed by a public authority. When you have a domain of your own, Traefik can fetch one from Let's Encrypt automatically.

First, add a certificate resolver to the Traefik install. This tells Traefik to prove domain ownership over a TLS handshake on port 443 (the TLS-ALPN challenge), which needs nothing beyond the Load Balancer you already have:

1helm upgrade traefik traefik/traefik \
2  --namespace traefik --reuse-values \
3  --set persistence.enabled=true \
4  --set persistence.size=128Mi \
5  --set podSecurityContext.fsGroup=65532 \
6  --set certificatesResolvers.le.acme.email=you@example.com \
7  --set certificatesResolvers.le.acme.storage=/data/acme.json \
8  --set certificatesResolvers.le.acme.tlsChallenge=true \
9  --wait

The persistence and fsGroup settings matter: Traefik stores the certificate in a file at /data/acme.json, and it runs as a non-root user against a read-only root filesystem, so it needs a writable volume it owns. Without the fsGroup, Traefik cannot write acme.json and the resolver is skipped.

Point an A record for your domain (for example grpc.example.com) at the Load Balancer's IP, then reference the resolver from the route:

1HOST=grpc.example.com
2kubectl apply -f - <<EOF
3apiVersion: traefik.io/v1alpha1
4kind: IngressRoute
5metadata:
6  name: grpcbin
7spec:
8  entryPoints:
9    - websecure
10  routes:
11    - match: Host(\`${HOST}\`)
12      kind: Rule
13      services:
14        - name: grpcbin
15          port: 9000
16          scheme: h2c
17  tls:
18    certResolver: le
19EOF

Traefik requests the certificate the first time the hostname is hit. Give it up to a minute, then call the service without -insecure:

1grpcurl ${HOST}:443 list

On nip.io hostnames: Let's Encrypt validation can fail against shared wildcard-DNS services like nip.io, so the trusted-certificate path is worth doing on a domain you control. For a quick nip.io demo, stay with Traefik's built-in certificate and grpcurl -insecure as shown above.

Cleaning up

Delete the cluster when you are done so it stops billing:

1civo k3s remove grpc-demo

Conclusion

You have exposed a gRPC service to the outside world through Traefik and terminated TLS at the edge, without installing a service mesh or cert-manager. The core of it was one IngressRoute with an h2c backend scheme, and swapping the built-in certificate for a Let's Encrypt one is a matter of adding a resolver when you have a domain to point at it.

From here you might look at A/B testing between two service versions with Traefik, or at adding authentication middleware in front of your gRPC route.