Implementing gRPC and gRPC-Web via Kong Gateway Architectures

The architectural necessity of bridging modern, high-performance communication protocols with the accessibility requirements of web-based clients represents one of the most significant challenges in distributed systems design. As organizations move toward microservices-heavy environments, gRPC has emerged as the standard for internal, high-bandwidth, and low-latency inter-process communication. Built upon the HTTP/2 protocol, gRPC offers superior performance for streaming and complex data structures compared to traditional RESTful services. However, the technical constraints of web browsers—specifically the inability of standard JavaScript environments to directly manage the low-level HTTP/2 frame manipulation required by pure gRPC—create a functional gap. This gap is bridged through the implementation of the gRPC-Web protocol, and Kong Gateway serves as the critical intermediary, acting as a proxy that translates incoming gRPC-Web requests from browser-based applications into standard gRPC calls for upstream services.

In a robust production environment, Kong Gateway functions as the entry point for external traffic, shielding internal service meshes behind a firewall or private network. While cloud-native solutions exist, KongHQ provides a premier self-hosted alternative for environments that require strict control over the networking stack, such as on-premise data centers or hybrid cloud deployments. By leveraging Kong, engineers can expose internal g-RPC services to third-party clients or public-facing web applications without exposing the underlying microservices directly to the internet. This setup involves not only the configuration of the gateway itself but also the management of protocol translation, the uploading of Protocol Buffer (Protobuf) definitions, and the orchestration of routes and services within the Kong ecosystem.

Core gRPC Architecture and Kong Integration

The deployment of gRPC through Kong Gateway necessitates a clear understanding of the request lifecycle. In a typical architecture, multiple gRPC services operate on distinct ports within a private network. Kong Gateway is positioned at the edge, listening for incoming traffic—often via HTTP/2—and forwarding it to the appropriate upstream service.

The fundamental advantage of utilizing gRPC for inter-service communication is its reliance on HTTP/2, which enables features like multiplexing and server-side streaming. When these services need to be accessible to clients that do not support the full gRPC spec, such as React, Vue, or Angular applications, the Kong grpc-web plugin becomes essential. This plugin allows the gateway to intercept gRPC-Web encoded requests and transform them into the standard gRPC format that the upstream services expect.

To establish a working baseline, the Kong Admin API must be accessible. Assuming a standard deployment where the Admin API is located at http://localhost:8001, the initial step involves registering the upstream gRPC service.

The following command demonstrates how to register a service via the Admin API:

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

In this configuration, the protocol is explicitly set to grpc. For developers utilizing docker-compose for orchestration, the host parameter must be adjusted to reflect the internal Docker service name. For instance, if a service is defined as follows:

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

The registration command must target the service name:

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

Once the service is registered, a route must be created to define how incoming traffic reaches this service. This is achieved by mapping specific paths to the service.

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

The kong-plugin-grpc-web Implementation

The kong-plugin-grpc-web is a specialized Lua-based plugin designed to facilitate access for JavaScript browser applications. This plugin is the engine that enables the translation between the gRPC-Web protocol and the native gRPC protocol.

Plugin Provenance and Dependencies

The plugin is distributed via LuaRocks, the package manager for the Lua programming language. For developers or DevOps engineers managing Kong's internal Lua environment, the installation is performed using the following command:

bash luarocks install kong-plugin-grpc-web

To ensure stability and prevent runtime errors during the translation of protobuf messages, the environment must meet specific version requirements. The plugin's dependency tree is critical for the successful decoding of serialized data.

The historical download statistics for this plugin indicate its widespread adoption within the Kong community, with version 0.2.0 being a primary stable release utilized by over 51,000 users.

Protobuf Definition Management

A critical requirement for the grpc-web plugin is the provision of the .proto file. The plugin must understand the structure of the messages it is translating; without the Protobuf definition, the gateway cannot correctly map the incoming web request to the upstream gRPC method.

If Kong is running within a Docker container, the .proto file must be moved from the host machine into the container's file system so the plugin can access it.

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

Alternatively, the file can be manually uploaded to the /usr/local/kong directory on the deployment server. This file serves as the "source of truth" for the plugin configuration.

Configuration Strategies Across Environments

Kong can be configured using several different methodologies depending on the deployment scale, ranging from direct Admin API calls to Kubernetes Custom Resource Definitions (CRDs) and Terraform for Infrastructure as Code (IaC).

Kubernetes Configuration via CRDs

In a Kubernetes-orchestrated environment, Kong manages plugins through KongPlugin and KongClusterPlugin resources. This allows for declarative configuration management that integrates seamlessly with GitOps workflows.

To deploy a KongClusterPlugin that is globally available across the cluster, one can use kubectl to apply a configuration that points to the specific .proto path.

bash echo " apiVersion: configuration.konghq.com/v1 kind: KongClusterPlugin metadata: name: grpc-web namespace: kong annotations: kubernetes.io/ingress.class: kong konghq.com/tags: '' labels: global: 'true' config: proto: path/to/hello.proto plugin: grpc-web " | kubectl apply -f -

For more granular control, a KongPlugin can be applied to a specific namespace or attached to a specific service or route. When applying a KongPlugin to a service, the following command is utilized:

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

If the configuration is targeted at a specific route, the annotation is applied to the httproute or ingress resource:

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

Declarative Configuration (kong.yaml)

For users utilizing Kong in a DB-less mode, all plugin configurations must be defined within the kong.yaml file. This file follows a strict format versioning system.

The following snippet demonstrates how to configure the grpc-web plugin for a specific service:

yaml _format_encryption: "3.0" plugins: - name: grpc-web service: serviceName|Id config: proto: path/to/hello.proto

The serviceName|Id placeholder must be replaced with the actual identifier of the target service. Similarly, if the plugin is applied to a specific consumer, the configuration would be:

yaml _format_version: "3.0" plugins: - name: grpc-web consumer: consumerName|Id config: proto: path/to/hello.proto

Infrastructure as Code with Terraform and Konnect

In enterprise environments utilizing Kong Konnect, managing plugins through Terraform is the industry standard. This ensures that plugin configurations are reproducible and version-controlled.

The Terraform provider for Konnect must be configured with a Personal Access Token (PAT) and the appropriate server URL.

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

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

To create a konnect_gateway_plugin_grpc_web resource, the configuration must reference the control_plane_id and the specific .proto path.

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

# To attach to a specific route
route = {
id = konnectgatewayroute.my_route.id
}

# To attach to a specific service
service = {
id = konnectgatewayservice.my_service.id
}
}
```

Validation and Testing Procedures

Once the gateway, service, and plugin are configured, the final step is to validate that the gRPC-Web translation and the upstream gRPC communication are functioning correctly. This can be performed using grpcurl, a command-line tool that allows for interacting with gRPC servers.

The following command tests an endpoint by sending a JSON payload to a specific service method. This test assumes the Kong Gateway is listening on port 8000 for incoming traffic.

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

Key parameters for this validation include:
- -v: Enables verbose output to inspect the headers and metadata of the request/response.
- -d: Passes the JSON-encoded payload that mirrors the structure defined in the .proto file.
- -plaintext: Disables TLS for testing in a local environment (though production should use TLS/ALTS).
- -max-msg-sz: Sets a high maximum message size to accommodate larger protobuf payloads.

The success of this command is indicated by a proper response from the upstream gRPC server, confirming that the Kong Gateway has successfully parsed the request, translated the protocol, and proxied the traffic to the backend.

Architectural Analysis and Conclusion

The integration of gRPC and gRPC-Web via Kong Gateway represents a sophisticated solution to the fragmentation of network protocols. By placing Kong at the edge, engineers create a translation layer that preserves the high-performance characteristics of gRPC for internal microservices while maintaining the universal accessibility of HTTP/1.1/2-compatible web clients.

The complexity of this implementation lies in the management of the Protobuf definitions. The dependency of the grpc-web plugin on accurate .proto files means that any discrepancy between the gateway's configuration and the actual service definition will result in serialization errors. Furthermore, the transition from a local docker-compose environment to a managed Konnect environment requires a shift from imperative curl commands to declarative Terraform and Kubernetes configurations.

Ultimately, the success of this architecture depends on a rigorous deployment pipeline. This includes the automated synchronization of .proto files across Docker containers and Kubernetes pods, the strict enforcement of Lua dependency versions, and the implementation of robust monitoring via the Kong Admin API to ensure that the translation layer is not introducing undue latency. When executed correctly, this setup provides a scalable, secure, and highly performant gateway capable of supporting the next generation of web-based, real-time distributed applications.

Sources

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