Problem

You want to take advantage of HTTP/2.

Solution

Turn on HTTP/2 on your NGINX server:

server {
    listen 443 ssl http2 default_server;
 
    ssl_certificate    server.crt;
    ssl_certificate_key server.key;
    ...
}

Discussion

To turn on HTTP/2, you simply need to add the http2 parameter to the listen directive. The catch, however, is that although the protocol does not require the connection to be wrapped in SSL/TLS, some implementations of HTTP/2 clients support only HTTP/2 over an encrypted connection. Another caveat is that the HTTP/2 specification listed a number of TLS 1.2 cipher suites as blacklisted and therefore will fail the handshake. The ciphers NGINX uses by default are not on the blacklist. To test that your setup is correct you can install a plugin for Chrome and Firefox browsers that indicates when a site is using HTTP/2, or on the command line with the nghttp utility.

Also See

HTTP/2 RFC Blacklisted Ciphers
Chrome HTTP2 and SPDY Indicator Plugin
Firefox HTTP2 Indicator Add-on

Problem

You need to terminate, inspect, route, or load balance gRPC method calls.

Solution

Use NGINX to proxy gRPC connections.

server {
    listen 80 http2;

    location / {
        grpc_pass grpc://backend.local:50051;
    } 
}

In this configuration NGINX is listening on port 80 for unencrypted HTTP/2 traffic, and proxying that traffic to a machine named backend.local on port 50051. The grpc_pass directive instructs NGINX to treat the commuication as a gRPC call. The grpc:// in front of our backend server location is not neccessary; however, it does directly indicate that the backend communication is not encrypted.

To utilize TLS encryption between the client and NGINX, and terminate that encryption before passing the calls to the application server, turn on SSL and HTTP/2, as you did in the first section:

server {
    listen 443 ssl http2 default_server;
 
    ssl_certificate    server.crt;
    ssl_certificate_key server.key;
    location / {
        grpc_pass grpc://backend.local:50051;
    } 
}

This configuration terminates TLS at NGINX and passes the gRPC communication to the application over unencrypted HTTP/2.

To configure NGINX to encrypt the gRPC communication to the application server, providing end-to-end encrypted traffic, simply modify the grpc_pass directive to specify grpcs:// before the server information (note the addition of the s denoting secure communication):

        grpc_pass grpcs://backend.local:50051;

You also can use NGINX to route calls to different backend services based on the gRPC URI, which includes the package, service, and method. To do so, utilize the location directive.

location /mypackage.service1 {
    grpc_pass grpc://backend.local:50051;
}
location /mypackage.service2 {
    grpc_pass grpc://backend.local:50052;
}
location / {
    root /usr/share/nginx/html;
    index index.html index.htm;
}

This configuration example uses the location directive to route incoming HTTP/2 traffic between two separate gRPC services, as well as a location to serve static content. Method calls for the mypackage.service1 service are directed to the backend.local server on port 50051, and calls for mypackage.service2 are directed to port 50052. The location / catches any other HTTP request and serves static content. This demonstrates how NGINX is able to serve gRPC and non-gRPC under the same HTTP/2 endpoint and route accordingly.

Load balancing gRPC calls is also similar to non-gRPC HTTP traffic:

upstream grpcservers {
    server backend1.local:50051;
    server backend2.local:50051;
}
server {
    listen 443 ssl http2 default_server;
 
    ssl_certificate    server.crt;
    ssl_certificate_key server.key;
    location / {
        grpc_pass grpc://grpcservers;
    } 
}

The upstream block works the exact same way for gRPC as it does for other HTTP traffic. The only difference is that the upstream is referenced by grpc_pass.

Discussion

NGINX is able to receive, proxy, load balance, route, and terminate encryption for gRPC calls. The gRPC module enables NGINX to set, alter, or drop gRPC call headers, set timeouts for requests, and set upstream SSL/TLS specifications. As gRPC communicates over the HTTP/2 protocol, you can configure NGINX to accept gRPC and non-gRPC web traffic on the same endpoint.

Problem

You need to preemptively push content to the client.

Solution

Use the HTTP/2 server push feature of NGINX.

server {
    listen 443 ssl http2 default_server;
 
    ssl_certificate    server.crt;
    ssl_certificate_key server.key;
    root /usr/share/nginx/html;

    location = /demo.html {
        http2_push /style.css;
        http2_push /image1.jpg;
    }
}

Discussion

To use HTTP/2 server push, your server must be configured for HTTP/2, as is done in “Access Based on IP Address”. From there, you can instruct NGINX to push specific files preemptively with the http2_push directive. This directive takes one parameter, the full URI path of the file to push to the client.

NGINX can also automatically push resources to clients if proxied applications include an HTTP response header named Link. This header is able to instruct NGINX to preload the resources specified. To enable this feature, add http2_push_preload on; to the NGINX configuration.