gRPC

gRPC is a remote procedure call framework that allows a client application to invoke an API function on a server as if that function were defined in the client’s own code. It uses Protocol Buffers to serialize messages, which allows clients and servers to exchange messages even when the two are written using different programming languages. gRPC offers bidirectional streaming of messages, meaning that an interaction between the client and server can be initiated from either side and once a connection is established, calls can be streamed continuously, similar to the WebSocket protocol.

The load balancer can act as a Layer 7 proxy for gRPC traffic because gRPC uses HTTP/2 as its transport protocol. This gives you access to fetch methods for inspecting the messages as they pass through the load balancer.

Enable gRPC over HTTP/2 Jump to heading #

1. To enable HTTP/2 between clients and the load balancer, configure the bind line in a frontend section as an ssl endpoint. The proto parameter announces that the load balancer supports HTTP/2 (h2):

   haproxy
   frontend grpc_service
     mode http
     bind :3001 proto h2
     default_backend grpc_servers

   haproxy
   frontend grpc_service
     mode http
     bind :3001 proto h2
     default_backend grpc_servers

2. Configure TLS connections to the servers in the backend section and specify the HTTP/2 protocol:

   haproxy
   backend grpc_servers
     mode http
     balance roundrobin
     server s1 192.168.0.10:3000 check proto h2
     server s2 192.168.0.10:3000 check proto h2

   haproxy
   backend grpc_servers
     mode http
     balance roundrobin
     server s1 192.168.0.10:3000 check proto h2
     server s2 192.168.0.10:3000 check proto h2

Example gRPC application Jump to heading #

In this example, you use a gRPC service called RollDiceService that returns a random number between 1 and 6 and a gRPC client that calls the service.

1. Download the client and server binaries.

2. On your load balancer server, start the server binary so that it listens on port 3000:

   nix
   SERVER_ADDRESS=:3000 ./server

   nix
   SERVER_ADDRESS=:3000 ./server

   output
   text
   2020/12/18 17:36:12 Listening on address :3000

   output
   text
   2020/12/18 17:36:12 Listening on address :3000

3. Update your configuration to have a frontend and backend that receives gRPC traffic and forwards it to the server you just started. Add proto h2 to the bind and server lines to use HTTP/2 as the protocol:

   haproxy
   frontend grpc_service
     mode http
     bind :3001 proto h2
     default_backend grpc_servers
   backend grpc_servers
     mode http
     server s1 127.0.0.1:3000 check proto h2

   haproxy
   frontend grpc_service
     mode http
     bind :3001 proto h2
     default_backend grpc_servers
   backend grpc_servers
     mode http
     server s1 127.0.0.1:3000 check proto h2

4. Either on the load balancer server or another Linux machine on the network, start the client binary to connect to the gRPC service via the load balancer at port 3001. This will show the output of the client calling the RollDice function on the service:

   nix
   SERVER_ADDRESS=localhost:3001 NUMBER_OF_DICE=2 ./client

   nix
   SERVER_ADDRESS=localhost:3001 NUMBER_OF_DICE=2 ./client

   output
   text
   2020/12/18 18:08:09 Rolling 2 dice...
   2020/12/18 18:08:09 roll: 4
   2020/12/18 18:08:09 roll: 1
   2020/12/18 18:08:11 Rolling 2 dice...
   2020/12/18 18:08:11 roll: 2
   2020/12/18 18:08:11 roll: 6

   output
   text
   2020/12/18 18:08:09 Rolling 2 dice...
   2020/12/18 18:08:09 roll: 4
   2020/12/18 18:08:09 roll: 1
   2020/12/18 18:08:11 Rolling 2 dice...
   2020/12/18 18:08:11 roll: 2
   2020/12/18 18:08:11 roll: 6

5. Follow the access log to see the requests flow through the load balancer:

   output
   text
   127.0.0.1:51780 [18/Dec/2020:18:08:21.722] grpc_service grpc_servers/s1 0/0/0/1/+1 200 +99 - - ---- 1/1/1/0/0 0/0 "POST http:   localhost:3001/RollDiceService/RollDice HTTP/2.0"
   127.0.0.1:51780 [18/Dec/2020:18:08:23.725] grpc_service grpc_servers/s1 0/0/0/1/+1 200 +99 - - ---- 1/1/1/0/0 0/0 "POST http:   localhost:3001/RollDiceService/RollDice HTTP/2.0"

   output
   text
   127.0.0.1:51780 [18/Dec/2020:18:08:21.722] grpc_service grpc_servers/s1 0/0/0/1/+1 200 +99 - - ---- 1/1/1/0/0 0/0 "POST http:   localhost:3001/RollDiceService/RollDice HTTP/2.0"
   127.0.0.1:51780 [18/Dec/2020:18:08:23.725] grpc_service grpc_servers/s1 0/0/0/1/+1 200 +99 - - ---- 1/1/1/0/0 0/0 "POST http:   localhost:3001/RollDiceService/RollDice HTTP/2.0"

The ungrpc converter Jump to heading #

gRPC uses Protocol Buffers to serialize messages. Use the ungrpc converter function to extract information from a gRPC Protocol Buffers message. It takes the ID of the Protocol Buffers field in a message. In the following example, the Protocol Buffers message has a field named numberOfDice that has an ID of 1:

text
message RollDiceRequest {
  int32 numberOfDice = 1;
}

text
message RollDiceRequest {
  int32 numberOfDice = 1;
}

In your configuration, specify this ID and the data type to extract the value. Here, we print the numberOfDice value to the end of the access log:

haproxy
frontend grpc_service
  mode http
  bind :3001 proto h2
  default_backend grpc_servers
  
  # Store the numberOfDice value in the sess.numberofdice variable
  http-request set-var(sess.numberofdice) req.body,ungrpc(1,int32)
  
  # add the variable to the end of the standard HTTP log format
  log-format "%ci:%cp [%tr] %ft %b/%s %TR/%Tw/%Tc/%Tr/%Ta %ST %B %CC %CS %tsc %ac/%fc/%bc/%sc/%rc %sq/%bq %hr %hs %{+Q}r Number of dice: %[var(sess.numberofdice)]"

haproxy
frontend grpc_service
  mode http
  bind :3001 proto h2
  default_backend grpc_servers
  
  # Store the numberOfDice value in the sess.numberofdice variable
  http-request set-var(sess.numberofdice) req.body,ungrpc(1,int32)
  
  # add the variable to the end of the standard HTTP log format
  log-format "%ci:%cp [%tr] %ft %b/%s %TR/%Tw/%Tc/%Tr/%Ta %ST %B %CC %CS %tsc %ac/%fc/%bc/%sc/%rc %sq/%bq %hr %hs %{+Q}r Number of dice: %[var(sess.numberofdice)]"

Your access log will now include the field’s value:

output
text
127.0.0.1:51780 [18/Dec/2020:18:08:21.722] grpc_service grpc_servers/s1 0/0/0/1/+1 200 +99 - - ---- 1/1/1/0/0 0/0 "POST http:localhost:3001/RollDiceService/RollDice HTTP/2.0" Number of dice: 2
127.0.0.1:51780 [18/Dec/2020:18:08:23.725] grpc_service grpc_servers/s1 0/0/0/1/+1 200 +99 - - ---- 1/1/1/0/0 0/0 "POST http:localhost:3001/RollDiceService/RollDice HTTP/2.0" Number of dice: 2

output
text
127.0.0.1:51780 [18/Dec/2020:18:08:21.722] grpc_service grpc_servers/s1 0/0/0/1/+1 200 +99 - - ---- 1/1/1/0/0 0/0 "POST http:localhost:3001/RollDiceService/RollDice HTTP/2.0" Number of dice: 2
127.0.0.1:51780 [18/Dec/2020:18:08:23.725] grpc_service grpc_servers/s1 0/0/0/1/+1 200 +99 - - ---- 1/1/1/0/0 0/0 "POST http:localhost:3001/RollDiceService/RollDice HTTP/2.0" Number of dice: 2