Implementing gRPC Traffic Management and gRPC-Web Translation via Kong Gateway

The architectural paradigm of modern distributed systems relies heavily on the efficiency of inter-process communication. While RESTful services, operating over HTTP/1.1, have long been the standard for web-based communication, the rise of microservices has necessitated a transition toward higher-performance protocols. gRPC (Google Remote Procedure Call) has emerged as the premier choice for these environments, leveraging HTTP/2 to facilitate low-latency, high-throughput, and bidirectional streaming capabilities. However, a significant architectural friction point arises when these high-performance internal services need to be exposed to external clients, particularly web browsers that cannot natively implement the full gRPC protocol stack.

Kong Gateway serves as the critical intermediary in this ecosystem. As a highly scalable, cloud-native API gateway, Kong facilitates the secure exposure of internal services located behind firewalls or private networks. In environments where cloud-native managed services are unavailable or insufficient—such as on-premises, self-hosted, or hybrid-cloud deployments—Kong provides a robust, programmable layer for managing traffic. By acting as a proxy, Kong allows developers to maintain the performance benefits of gRPC for internal service-to-service communication while simultaneously providing translation layers, such as gRPC-Web, to support browser-based JavaScript applications. This implementation involves complex configurations of services, routes, and plugins, requiring a precise understanding of both the Kong Admin API and the underlying gRPC protocol definitions.

Architectural Role of Kong Gateway in gRPC Orchestration

The deployment of Kong Gateway in front of gRPC services establishes a centralized entry point for all incoming traffic. In a typical production architecture, multiple gRPC services may be listening on various internal ports. Kong is positioned at the perimeter, intercepting requests and directing them to the appropriate upstream service.

The implementation of this architecture provides several strategic advantages:

• Perimeter Security: Kong acts as a shield, allowing internal gRPC services to remain hidden within a private network. Only the Kong Gateway is exposed to the public internet, reducing the attack surface of the microservices.
• Protocol Transformation: Kong can handle the complexities of HTTP/2 and ALTS (Application Layer Transport Security), allowing clients to connect via standard, secure channels.
• Centralized Management: By using Kong, administrators can apply unified policies such as rate limiting, authentication, and logging across all gRPC and RESTful endpoints through a single control plane.
• Load Balancing: Kong can distribute incoming gRPC requests across multiple instances of a backend service, ensuring high availability and optimal resource utilization.

In advanced setups, such as those utilizing wildcards for Fully Qualified Domain Names (FQDN) like *.dongnguyen.link, Kong handles the SSL/TLS termination, ensuring that external clients connect securely while the internal communication remains optimized for speed.

Core Configuration of gRPC Services via Kong Admin API

Configuring a gRPC service within Kong requires a two-step process: first, registering the upstream service itself, and second, defining the routes that dictate how traffic reaches that service. This is typically performed through the Kong Admin API, which defaults to http://localhost:8001.

Service Registration

To register a gRPC service, a POST request must be sent to the /services endpoint. This request defines the identity and the physical location of the upstream gRPC server. It is critical to specify the protocol as grpc to inform Kong that it must handle HTTP/2-based traffic.

Assuming a gRPC service is currently running on http://localhost:50051, the registration command is as follows:

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

When deploying within a containerized environment using docker-compose, the host parameter must be modified. Instead of localhost, the developer must use the service name defined in the docker-compose.yml file. For instance, if the service definition is:

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

The registration command must use host=grpc-server. Failure to use the correct service name in a Docker network will result in a resolution error, as localhost inside the Kong container refers to the Kong container itself, not the sibling grpc-server container.

Route Configuration

Once the service is registered, a route must be created to map incoming requests to that service. This route defines the paths and protocols that Kong will listen for. To expose the previously created grpc-server service, a POST request is sent to the /services/{service_name}/routes endpoint.

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

This configuration tells Kong that any traffic arriving on the / path using the grpc protocol should be proxied to the grpc-server upstream.

Implementing the gRPC-Web Plugin for Browser Compatibility

While gRPC is ideal for backend communication, JavaScript applications running in a web browser cannot utilize the standard gRPC protocol due to browser limitations regarding low-level HTTP/2 frame access. The kong-plugin-grpc-web is a specialized solution designed to bridge this gap by translating gRPC-Web requests into standard gRPC calls.

Installation and Dependencies

The plugin is distributed via LuaRocks and requires a specific environment configuration. The installation is performed using the following command:

bash luarocks install kong-plugin-grpc-web

The stability and functionality of this plugin depend on several Lua-based dependencies:

• lua >= 5.1: The core execution engine.
• lua-protobuf ~> 0.3: Essential for handling the serialization and deserialization of Protocol Buffer messages.
• lua_pack == 1.0.5: Used for package management within the Lua environment.

The plugin has a documented history of use, with version 0.2.0 being a primary stable release used widely for translating requests for JS browser apps using the gRPC-Web library.

Protobuf Definition Management

For the gRPC-Web plugin to function, Kong must have access to the .proto file definitions. This allows the gateway to understand the structure of the messages being passed through the proxy. If Kong is running within a Docker container, the .proto file must be physically present within the container's filesystem.

To copy a definition file into a running Kong container, use the docker cp command:

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

Alternatively, the file can be manually placed in the /usr/local/kong directory of the deployment server.

Plugin Application Strategies

The application of the grpc-web plugin can be executed through three distinct methods: the Kong Admin API, Kubernetes Custom Resources (CRDs), or declarative configuration files (kong.yaml).

1. Kong Admin API Method

For real-time configuration without restarting the gateway, use a POST request to the plugin endpoint of a specific service.

bash curl -i -X POST http://localhost:8001/services/{serviceName|Id}/plugins/ \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data '{ "name": "grpc-web", "config": { "proto": "/usr/local/kong/helloworld.proto" } }'

2. Kubernetes Configuration (CRDs)

In a Kubernetes environment, the plugin is managed via KongPlugin and KongClusterPlugin resources. This allows for automated deployment via kubectl.

To create a KongPlugin for a specific namespace:

bash echo " apiVersion: configuration.konghq.com/v1 kind: KongPlugin metadata: name: grpc-web namespace: kong annotations: kubernetes.io/ingress.class: kong konghq.com/tags: '' config: proto: /usr/local/kong/helloworld.proto plugin: grpc-web " | kubectl apply -f -

After creating the plugin, it must be attached to a service or an ingress resource via annotations:

bash kubectl annotate -n kong service SERVICE_NAME konghq.com/plugins=grpc-web kubectl annotate -n kong httproute konghq.com/plugins=grpc-web kubectl annotate -n kong ingress konghq.com/plugins=grpc-web

For a global application that affects all services in the cluster, use the KongClusterPlugin resource:

bash echo " apiVersion: configuration.konghq.com/v1 kind: KongClusterPlugin metadata: name: grpc-web namespace: kong annotations: kubernetes.io/ingress.class: kong konghq.com/tags: '' config: proto: /usr/local/kong/helloworld.proto plugin: grpc-web " | kubectl apply -f -

3. Declarative Configuration (decK/kong.yaml)

For GitOps workflows, the plugin can be defined within a kong.yaml file. This is highly effective for managing complex configurations across multiple environments.

yaml _format_version: "3.0" plugins: - name: grpc-web service: serviceName|Id config: proto: /usrarr/local/kong/helloworld.proto

In this configuration, the service field can target a specific service by name or ID, allowing for granular control over which endpoints are subjected to the gRPC-Web translation.

Terraform Integration for Konnect

In enterprise environments using Kong Konnect, infrastructure as code (IaC) is utilized to manage plugins. Terraform allows for the programmatic creation of konnect_gateway_plugin_grpc_web resources.

The following Terraform block demonstrates how to configure a provider and a plugin resource:

```hcl
terraform {
required_providers {
konnect = {
source = "kong/konnect"
}
}
}

provider "konnect" {
personalaccesstoken = "$KONNECTTOKEN"
serverurl = "https://us.api.konghq.com/"
}

resource "konnectgatewayplugingrpcweb" "mygrpcweb" {
enabled = true
config = {
proto = "path/to/hello.proto"
}
tags = []
controlplaneid = konnectgatewaycontrolplane.mykonnect_cp.id

service = {
id = konnectgatewayservice.my_service.id
}

route = {
id = konnectgatewayroute.my_route.id
}
}
```

This approach ensures that the plugin configuration is versioned and reproducible, which is vital for maintaining large-scale Konnect deployments.

Verification and Testing

Once the configuration is deployed, it is imperative to validate that the gRPC traffic is being correctly proxied and that the gRPC-Web translation is operational. For testing the raw gRPC connection (bypassing the Web translation), grpcurl is the industry-standard tool.

To test an endpoint, use the following command structure, ensuring you target the Kong proxy port (defaulting to 8000 for HTTP traffic):

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

The -v flag provides verbose output, which is essential for debugging headers and metadata during the handshake. The -plaintext flag is used when SSL/TLS is not yet configured, while the -max-msg-sz parameter ensures that larger protobuf payloads do not trigger buffer overflows or truncation errors during transmission through the gateway.

Technical Comparison of Configuration Scopes

The following table summarizes the different scopes available when applying the gRPC-Web plugin within Kong, which is critical for determining the blast radius of configuration changes.

Conclusion: The Strategic Importance of gRPC Gateway Management

The integration of gRPC and Kong Gateway represents a sophisticated approach to modern API management. By leveraging Kong's ability to proxy gRPC traffic and the specialized grpc-web plugin, organizations can resolve the fundamental incompatibility between browser-based clients and high-performance gRPC backends. This architecture does more than just facilitate connectivity; it provides a structured, secure, and scalable framework for managing the lifecycle of microservices.

The complexity of this setup—involving Lua dependencies, Protobuf file synchronization, and multi-layered configuration scopes (Service, Route, Consumer, and Cluster)—requires a disciplined DevOps approach. Whether using Terraform for Konnect-based infrastructure or kubectl for Kubernetes-native deployments, the goal remains the same: to maintain the extreme performance of gRPC for internal operations while ensuring the seamless accessibility of services for the wider web ecosystem. As edge computing and more complex streaming requirements continue to evolve, the role of Kong as a protocol-agnostic, intelligent proxy will only become more central to the stability of the global digital infrastructure.

Sources

1. Ruddra - gRPC via Kong
2. LuaRocks - kong-plugin-grpc-web
3. Kong Developer - Using Protobuf Definitions
4. ShiftAsia - Proxy gRPC Traffic with Kong Gateway