gRPC proxying in Nginx - Commands & Configuration

Introduction

Sometimes you want to let NGINX handle gRPC requests and forward them to a backend server. This helps you manage traffic, add security, and balance load without changing your gRPC app.

When you want to expose a gRPC service securely over HTTPS using NGINX as a gateway.

When you need to load balance multiple gRPC backend servers behind one public endpoint.

When you want to add logging or rate limiting to gRPC calls without changing the service code.

When you want to terminate TLS at NGINX and forward plain gRPC traffic to backend servers.

When you want to combine gRPC and regular HTTP traffic on the same NGINX server.

Config File - nginx.conf

nginx.conf

worker_processes  1;

events {
    worker_connections  1024;
}

http {
    # Enable HTTP/2 for gRPC proxying
    server {
        listen  50051 ssl http2;

        # TLS configuration for secure gRPC
        ssl_certificate     /etc/nginx/certs/server.crt;
        ssl_certificate_key /etc/nginx/certs/server.key;

        # gRPC backend server
        location / {
            grpc_pass grpc://localhost:60051;
            error_page 502 = /errorgrpc;
        }

        location = /errorgrpc {
            internal;
            default_type application/grpc;
            add_header grpc-status 14;
            add_header grpc-message "Unavailable";
            return 204;
        }
    }
}

This configuration sets up NGINX to listen on port 50051 with HTTP/2 and SSL enabled, which is required for secure gRPC.

It uses TLS certificates for secure connections.

The location / block proxies all gRPC requests to a backend server running on localhost port 60051.

The error_page block handles backend errors gracefully by returning a proper gRPC error status.

Commands

Check the NGINX configuration file syntax to make sure there are no errors before starting.

Terminal

nginx -t

Expected Output

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok

nginx: configuration file /etc/nginx/nginx.conf test is successful

Restart NGINX to apply the new configuration for gRPC proxying.

Terminal

systemctl restart nginx

Expected Output

No output (command runs silently)

Test the gRPC proxy by sending a request through NGINX to the backend service on port 50051.

Terminal

grpcurl -proto yourservice.proto -d '{"name":"test"}' -insecure localhost:50051 YourService/YourMethod

Expected Output

{"message":"Hello test"}

→

-proto - Specifies the protobuf file describing the service.

→

-d - Sends JSON data as the request payload.

→

-insecure - Allows insecure connection without TLS verification for testing.

Key Concept

If you remember nothing else from this pattern, remember: NGINX must use HTTP/2 and grpc_pass to forward gRPC traffic correctly.

Common Mistakes

Not enabling HTTP/2 on the listen directive.

gRPC requires HTTP/2, so without it, NGINX cannot proxy gRPC requests properly.

Add 'http2' to the listen directive, for example: 'listen 50051 http2;'

Using 'proxy_pass' instead of 'grpc_pass' for gRPC traffic.

'proxy_pass' is for HTTP/1.x and will not handle gRPC framing correctly.

Use 'grpc_pass' to forward gRPC requests to the backend.

Not configuring TLS certificates when using secure gRPC.

gRPC clients expect TLS for secure connections; missing certificates cause connection failures.

Configure 'ssl_certificate' and 'ssl_certificate_key' with valid files.

Summary

Configure NGINX to listen with HTTP/2 and TLS for secure gRPC proxying.

Use 'grpc_pass' to forward gRPC requests to the backend server.

Test the setup with a gRPC client tool like grpcurl to verify proxying works.