grpc_pass
The grpc_pass directive is used to pass gRPC requests to a gRPC backend server.
Description
The grpc_pass directive is specifically designed for routing gRPC requests within NGINX. It defines a backend server to which the gRPC requests are forwarded. The directive uses a URL as its argument, which can specify either an upstream server group defined by the upstream directive or a direct server address. When NGINX receives a gRPC request, it translates this request into the appropriate format and forwards it to the specified backend, handling the binary protocol necessary for gRPC communication.
In the context of NGINX configuration, the grpc_pass directive is used in a location block, making it essential for defining the section of the URI that should be mapped to a particular backend service. The proper handling of response headers, connection management, and the binary encoding/decoding mechanism are automatically managed by NGINX, allowing developers to focus on application logic rather than the intricacies of gRPC communication. It's important to ensure that the upstream server supports gRPC and is appropriately configured to handle requests forwarded from NGINX.
Because gRPC uses HTTP/2, the grpc_pass directive inherently requires an NGINX build that includes support for HTTP/2. This means the server needs to be adequately configured to listen for HTTP/2 connections, which, when coupled with grpc_pass, will enable full support for gRPC traffic.
Config Example
location /gRPC {
grpc_pass grpc://localhost:50051;
}Ensure that NGINX has been compiled with HTTP/2 support to correctly process gRPC using grpc_pass.
Do not use grpc_pass in conjunction with directives that modify the HTTP protocol, such as proxy_set_header that are meant for HTTP/1.x, as they could lead to protocol mismatches.
When specifying the backend URL, make sure to start with 'grpc://' or 'grpcs://' to indicate the correct protocol. After defining the grpc_pass directive, other configurations such as timeouts might also need to be set accordingly.