gRPC proxying in Nginx - Step-by-Step Execution

Process Flow - gRPC proxying

Client sends gRPC request

↓

Nginx receives request

↓

Nginx checks grpc_pass config

↓

Nginx forwards request to gRPC backend

↓

Backend processes request

↓

Backend sends gRPC response

↓

Nginx forwards response to client

↓

Client receives response

This flow shows how Nginx receives a gRPC request, forwards it to the backend server using grpc_pass, and then sends the backend's response back to the client.

Execution Sample

Nginx

server {
    listen 50051 http2;
    location / {
        grpc_pass grpc://localhost:60051;
    }
}

Nginx listens on port 50051 for gRPC requests and proxies them to a backend gRPC server on localhost port 60051.

Process Table

Step	Action	Nginx State	Backend State	Client State
1	Client sends gRPC request to Nginx on port 50051	Waiting for request	Idle	Request sent
2	Nginx receives gRPC request	Received request	Idle	Request sent
3	Nginx checks grpc_pass directive	Preparing to proxy	Idle	Request sent
4	Nginx forwards request to backend at localhost:60051	Request forwarded	Received request	Request sent
5	Backend processes gRPC request	Request forwarded	Processing request	Request sent
6	Backend sends gRPC response to Nginx	Waiting response	Response sent	Request sent
7	Nginx receives response and forwards to client	Response forwarded	Response sent	Response received
8	Client receives gRPC response	Idle	Idle	Response received

💡 Client receives response, completing the gRPC proxy cycle.

Status Tracker

Variable	Start	After Step 2	After Step 4	After Step 6	Final
Nginx State	Waiting for request	Received request	Request forwarded	Waiting response	Idle
Backend State	Idle	Idle	Received request	Response sent	Idle
Client State	Request not sent	Request sent	Request sent	Request sent	Response received

Key Moments - 3 Insights

Why does Nginx need the 'http2' parameter in the listen directive?

Because gRPC uses HTTP/2 protocol, Nginx must listen with 'http2' enabled to properly receive and proxy gRPC requests, as shown in step 1 and 2 of the execution_table.

What happens if the grpc_pass directive points to the wrong backend address?

Nginx will fail to forward the request properly, causing the client to not receive a valid response. This would be evident as Nginx state stuck at 'Preparing to proxy' or 'Request forwarded' without backend processing in steps 3-5.

Does Nginx modify the gRPC request or response during proxying?

No, Nginx acts as a transparent proxy forwarding the gRPC messages unchanged, as seen by the direct forwarding actions in steps 4 and 7.

Visual Quiz - 3 Questions

Look at the execution table, what is the Nginx state at step 5?

A Request forwarded

B Waiting for request

C Response forwarded

D Idle

💡 Hint

Check the 'Nginx State' column at step 5 in the execution_table.

At which step does the backend send the gRPC response to Nginx?

A Step 4

B Step 6

C Step 7

D Step 8

💡 Hint

Look for the action mentioning backend sending response in the execution_table.

If the client never sends a request, what would be Nginx's state after step 1?

A Received request

B Idle

C Waiting for request

D Request forwarded

💡 Hint

Refer to the initial Nginx state before receiving any request in variable_tracker.

Concept Snapshot

Nginx gRPC proxying setup:
- Listen with 'http2' for gRPC support
- Use 'grpc_pass' to forward requests to backend
- Nginx forwards requests and responses transparently
- Backend processes gRPC calls normally
- Client communicates via Nginx proxy without changes

Full Transcript

This visual execution shows how Nginx proxies gRPC requests. The client sends a gRPC request to Nginx listening on port 50051 with HTTP/2 enabled. Nginx receives the request and uses the grpc_pass directive to forward it to the backend gRPC server at localhost port 60051. The backend processes the request and sends a response back to Nginx. Nginx then forwards this response to the client. The states of Nginx, backend, and client change step-by-step to reflect this flow. Key points include the need for HTTP/2 in Nginx, correct backend address in grpc_pass, and that Nginx acts as a transparent proxy without modifying messages.