Nginx configures the method of agent gRPC

Nginx 1.13.10 adds native support for gRPC. This article shows you how to configure gRPC for Nginx.

Install Nginx

Nginx version requirements: 1.13.10.

gRPC must use HTTP/2 to transmit data, support plaintext and TLS encryption data, and support streaming data interaction. This is to take advantage of the multiplexing and streaming characteristics of the HTTP/2 connection. So you need to install http/2 when installing and deploying nginx. Use the source code to install, you need to add http_ssl and http_v2 modules at compile time:

$ auto/configure --with-http_ssl_module --with-http_v2_module

Nginx publishes the gRPC service in clear text.

nginx USES the http server to listen for requests from gRPC.

Example:

http {
 server {
  listen 80 http2;

  access_log logs/access.log main;

  location / {
   # The 'grpc://' prefix is optional; unencrypted gRPC is the default  
   grpc_pass grpc://localhost:50051;
  }
 }
}

The directive grpc_pass is used to specify the gRPC server address of the agent. There are two types of prefix protocols:

grpc:// : interacts with gRPC server-side in clear text grpcs:// : interacts with gRPC server-side in TLS encryption

The gRPC server address prefix "grpc://" is negligible, and the default is plaintext interaction.

In this example, nginx publishes gRPC in plain text on port 80, where the agent's gRPC also interacts in plain text on the back end.

Note: Nginx does not support both http1 and http2 on plaintext ports. If you want to support these two http protocols, you need to set them to different ports.

Nginx exposes the gRPC service with TLS encryption

It is recommended to use Nginx in a build environment to publish gRPC encrypted. This scenario requires adding an encryption layer to Nginx.

Self-signed certificates are available in development/test environments, and you can refer to this concise tutorial on self-signed certificates.

Configuration example:

server {
 listen 1443 ssl http2;

 ssl_certificate ssl/cert.pem;
 ssl_certificate_key ssl/key.pem;

 location / {
   grpc_pass grpc://localhost:50051;
 }
}

In the example, the nginx layer adds ssl to the gRPC service externally, while the internal proxy interacts with the gRPC server in clear text.

The gRPC client also requires TLS encryption. If you are using an untrusted certificate such as a self-signed certificate, the client needs to disable certificate checking. When deployed to a production environment, the self-signed certificate needs to be replaced with a certificate issued by a trusted certificate authority, and the client needs to be configured to trust the certificate.

Proxy encrypted gRPC

If the gRPC of the Nginx internal proxy also needs to interact in an encrypted manner, then the plaintext proxy grpc:// needs to be replaced by grpcs://. This starts with the gRPC server publishing the service in an encrypted manner.

The nginx layer has been modified as follows:

grpc_pass grpcs://localhost:50051;

nginx routes gRPC requests

If the back end has multiple gRPC servers, each server provides a different gRPC service. In this case, one nginx can be used to receive client requests and then route to the specified gRPC server according to the different path distribution. Use location to distinguish:

location /helloworld.Greeter {
 grpc_pass grpc://192.168.20.11:50051;
}

location /helloworld.Dispatcher {
 grpc_pass grpc://192.168.20.21:50052;
}

location / {
 root html;
 index index.html index.htm;
}

Load balancing the gRPC request

In the back-end, there are multiple gRPC servers, all of which are connected to one gRPC service. In this case, upstream of nginx can be combined to load balance requests of gRPC.

upstream grpcservers {
 server 192.168.20.21:50051;
 server 192.168.20.22:50052;
}

server {
 listen 1443 ssl http2;

 ssl_certificate  ssl/certificate.pem;
 ssl_certificate_key ssl/key.pem;

 location /helloworld.Greeter {
  grpc_pass grpc://grpcservers;
  error_page 502 = /error502grpc;
 }

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

Where upstream specifies the server group that defines the 1gRPC service. The server group defined by upstream is used at the gRPC server address specified by grpc_pass.