gRPC bridging

When a client sends a request over HTTP/1.1 protocol, the Citrix ADC appliance supports bridging of gRPC requests over HTTP/1.1 protocol which is in compliance with gRPC server over HTTP/2 protocol. Similarly, in reverse bridging, the appliance receives client gRPC request over HTTP/2 protocol and performs reverse bridging for gRPC requests in compliance with gRPC server of HTTP/1.1 protocol.

How gRPC bridging works

In this scenario, the Citrix ADC appliance seamlessly bridges gRPC content received on an HTTP/1.1 connection and forwards it to the back-end gRPC server over HTTP/2.

gRPC end-to-end configuration functional diagram

The following diagram shows how components interact with each other in a gRPC bridging configuration.

  1. When a gRPC request is sent, the Citrix ADC appliance checks if the connection is HTTP/1.1 and the content type is application/grpc. The HTTP/1.1 requests translate to the following pseudo headers.
  2. On receiving a gRPC request on HTTP/1.1. connection as indicated by the Content-Type header, the ADC appliance transforms the request into gRPC over HTTP/2 as given below:
    :method: Method-name in HTTP/1.1 request
    :path: Path is HTTP/1.1 request
    content-type: application/grpc
  1. Based on policy evaluation, the load balancing virtual server (with gRPC service bound to it) terminates the request or forwards it over HTTP/2 frames to the back-end gRPC server.
  2. On receiving the response on a HTTP/2 connection from gRPC server, the appliance buffers until it receives the HTTP/2 trailer and then checks for the gRPC-status code. If it is non-zero gRPC error status, the appliance looks for the mapping HTTP Status code and send suitable HTTP/1.1 error response.

Configure gRPC bridging by using the CLI

To configure gRPC bridging, you must complete the following steps:

  1. Add HTTP profile with HTTP/2 and HTTP/2 direct enabled
  2. Enable global back-end HTTP/2 support in HTTP parameter
  3. Add load balancing virtual server of type SSL/HTTP and set HTTP profile
  4. Add Service for gRPC endpoint and set HTTP profile
  5. Bind gRPC end point service to load balancing virtual server
  6. Map gRPC status code to HTTP response for non-zero gRPC status

Add HTTP profile with HTTP/2 and HTTP/2 direct enabled

To begin the configuration, you must enable the HTTP/2 feature in HTTP profile. If the client sends HTTP 1.1 requests, the appliance bridges the request and forward it to the back-end server.

At the command prompt, type:

add ns httpProfile <name> - http2 ( ENABLED | DISABLED ) [-http2Direct ( ENABLED | DISABLED )]

Example:

add ns httpProfile http2gRPC -http2Direct ENABLED -http2 ENABLED

Enable global back end HTTP/2 support in HTTP parameter

To enable HTTP/2 support globally on the server side by using the Citrix ADC command line.

At the command prompt, type:

set ns httpParam -http2ServerSide( ON | OFF )

Example:

set ns httpParam -http2ServerSide ON

Add load balancing virtual server of type SSL/HTTP and set HTTP profile

To add a load balancing virtual server by using the Citrix ADC command interface

At the command prompt, type:

add lb vserver <name> <service type> [(<IP address>@ <port>)] [-httpProfileName <string>]

Example:

add lb vserver lb-grpc HTTP 10.10.10.10 80 -httpProfileName http2gRPC

Note:

If you are using a load balancing virtual server of type SSL, then you must bind the server certificate. See Bind server certificate topic for more information.

Add Service for gRPC endpoint and set HTTP profile

To add a gRPC service with HTTP profile by using the Citrix ADC command interface.

At the command prompt, type:

add service <name> (<IP> | <serverName> ) <serviceType> <port> [-httpProfileName <string>]

Example:

add service svc-grpc 10.10.10.10 HTTP 80 -httpProfileName http2gRPC

Bind gRPC end point service to load balancing virtual server

To bind a gRPC end point service to the load balancing virtual server by using the CLI.

At the command interface, type:

bind lb vserver <name> <serviceName>

Example:

bind lb vserver lb-grpc svc-grpc

Map gRPC status code to HTTP status-code in HTTP/1.1 response

In gRPC bridging scenario, the gRPC service responds to the request with a gRPC status-code. The appliance maps the gRPC status code to a corresponding HTTP response code and reason phrase. The mapping is done based on the table provided below. The Citrix ADC appliance when sending the HTTP/1.1 response to the client will send the HTTP status code and the reason phrase.

gRPC status-code HTTP response status-code HTTP response reason-phrase
OK = 0 200 OK
CANCELLED = 1 499 *
UNKNOWN = 2 500 Internal Server Error
INVALID_ARGUMENT = 3 400 Bad Request
DEADLINE_EXCEEDED = 4 504 Gateway Timeout
NOT_FOUND = 5 404 *
ALREADY_EXISTS = 6 409 Conflict
PERMISSION_DENIED = 7 403 Forbidden
UNAUTHENTICATED = 16 401 Unauthorized
RESOURCE_EXHAUSTED = 8 429 *
FAILED_PRECONDITION = 9 400 Bad Request
ABORTED = 10 409 Conflict
OUT_OF_RANGE = 11 400 Bad Request
UNIMPLEMENTED = 12 501 Not Implemented
INTERNAL = 13 500 Internal Server Error
UNAVAILABLE = 14 503 Service Unavailable
DATA_LOSS = 15 500 Internal Server Error

Configure gRPC bridging by using the GUI

Complete the following steps to configure gRPC bridging by using the Citrix ADC GUI.

Add HTTP profile with HTTP/2 and HTTP/2 direct enabled

  1. Navigate to System > Profiles and click HTTP Profiles.
  2. Select HTTP/2 in the HTTP profile.

gRPC bridging add HTTP profile with http2 parameter

Enable global back-end HTTP/2 support in HTTP parameter

  1. Navigate to System > Settings > HTTP Parameters.
  2. In the Configure HTTP Parameter page, select HTTP/2 on Server Side option.
  3. Click OK.

gRPC bridging global back-end HTTP/2

Add load balancing virtual server of type SSL/HTTP and set HTTP profile

  1. Navigate to Traffic Management > Load Balancing > Virtual Servers.
  2. Click Add to create a load balancing virtual server for gRPC traffic.
  3. In Load Balancing Virtual Server page, click Profiles.
  4. In the Profiles section, select the profile type as HTTP.
  5. Click OK and then Done.

gRPC bridging global back-end HTTP/2 enable load balancing

Add Service for gRPC endpoint and set HTTP profile

  1. Navigate to Traffic Management > Load Balancing > Services.
  2. Click Add to create an application server for gRPC traffic.
  3. In Load Balancing Service page, go to Profile section.
  4. Under Profiles, add HTTP profile for gRPC endpoint.
  5. Click OK and then Done.

gRPC bridging add service for grpc endpoint

Bind Service for gRPC endpoint to load balancing virtual server

  1. Navigate to Traffic Management > Load Balancing > Virtual Servers.
  2. Click Add to create a load balancing virtual server for gRPC traffic.
  3. In Load Balancing Virtual Server page, click Service and Service Groups section.
  4. In the Load Balancing Virtual Server Service Binding page, select the gRPC service to bind.
  5. Click Close and then Done.

gRPC bridging bind service for gRPC endpoint

For detail GUI procedures, see Load Balancing topic.