Exposing gRPC Services via Kong Without Plugins

We assume you already have a working KongHQ setup and running gRPC services. Otherwise we recommend looking at these following resources:

1. Dev.to: Setup Kong with Docker
2. GitHub: gRPC services example
3. Dev.to: Docker with gRPC

API Gateways like KongHQ are essential for exposing internal services outside a firewall, private network, or internally. While many cloud solutions exist, not all can run in a non-cloud environment. KongHQ stands out for self-hosted setups.

For high-bandwidth data transfer, gRPC, based on HTTP/2, outperforms RESTful services for streaming and inter-process communication. However, securely exposing gRPC externally may sound complex, but KongHQ simplified this process, even though its documentation might not explicitly highlight how to expose gRPC services directly, which can be done efficiently.

Register gRPC Services to Kong

Let us assume the Kong’s Admin API is at http://localhost:8001 address, then we should be able to use the services API by making a POST request to http://localhost:8001/services URI. Also, assuming that our gRPC service is running at http://localhost:50051, we should be able to register the service via:

curl -X POST localhost:8001/services \
          --data name=grpc-service \
          --data protocol=grpc \
          --data host=localhost \
          --data port=50051

If you are using docker-compose, then use the service name as the host. For example, if the docker-compose service looks like this:

grpc-server:
  build:
    context: .
    dockerfile: ./Dockerfile
  container_name: grpc_server_01
  depends_on: - kong

then the it should be host=grpc-server when making the POST request in previous cURL example.

Then we need to expose the route of that service using the following POST request:

curl -X POST localhost:8001/services/grpc_server/routes \
          --data protocols=grpc \
          --data name=grpc-service \
          --data paths[]=/

Upload .proto Files to Kong

Next step for us is to upload the .proto file to Kong. If you are using Docker for running Kong, then use the following command:

docker cp helloworld.proto kong_01:/usr/local/kong

Or upload to /usr/local/kong folder of the deployment server for Kong.

Testing the gRPC Endpoint

Assuming that Kong is listening to port 8000 for taking incoming HTTP traffic from Consumers, and forwards it to upstream Services. More information can be found on how it works in proxy listen documentation.

Let us test the new endpoint for gRPC using grpcurl:

.\grpcurl -v -d '{"id": 1234, "tags": ["foo","bar"]}' \
              -plaintext -max-msg-sz 5775947392 \
              localhost:8000 my.custom.server.Service/Method

It should return appropriate response from the gRPC server.

Conclusion

This article focuses on how to expose gRPC service from Kong without any plugins. Feel free to ask questions in the comment section below if you need any clarification.

Last updated: Jul 13, 2024