Citrix ADC 13.0

gRPC reverse bridging

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

How reverse bridging works

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

gRPC end-to-end configuration functional diagram

  1. Client sends a gRPC request on HTTP/2 connection with gRPC headers in HTTP/2 frames and proto-buf payload.
  2. Based on policy evaluation, the load balancing virtual server (with gRPC service bound to it) translates and forwards the request over HTTP/1.1 connection to backend server.
  3. On receiving the HTTP/1.1 response, if there is no grpc-status code in the response, ADC derives a grpc status-case from the HTTP response code.
  4. The appliance then inserts the gRPC headers into HTTP/2 trailer before forwarding the response to the client.

Configure gRPC reverse bridging by using the CLI

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

  • Add HTTP profile 1 with HTTP/2 and HTTP/2 direct enabled for load balancing virtual server
  • Add HTTP profile 2 with HTTP/2 disabled for back-end server
  • Add load balancing virtual server of type SSL/HTTP and set to HTTP profile 1
  • Add service for gRPC endpoint and set to HTTP profile 2
  • Bind Service for gRPC endpoint to load balancing virtual server
  • Map HTTP-status code to gRPC status code if the response does not have a grpc status code

Add HTTP profile 1 with HTTP/2 and HTTP/2 direct enabled for load balancing virtual server

To begin the reverse bridging configuration, you must add two HTTP profiles. One profile for enabling HTTP/2 for gRPC client requests and another profile for disabling HTTP/2 for non-gRPC server response.

At the command prompt, type:

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

Example:

add ns httpProfile profile1 –http2 ENABLED -http2Direct ENABLED

Add HTTP profile 2 with HTTP/2 disabled for back-end server

To disable HTTP/2 support on the HTTP profile for back-end server response by using the Citrix ADC command line.

At the command prompt, type: add ns httpProfile <name> - http2 ( ENABLED | DISABLED ) [-http2Direct ( ENABLED | DISABLED )]

Example:

add ns httpProfile profile2 –http2 DISABLED http2Direct DISABLED

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

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 profile1

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 to HTTP profile 2

To add a service with gRPC endpoint and set HTTP profile 2 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.11 HTTP 80 -httpProfileName profile2

Bind service for gRPC endpoint to load balancing virtual server

To bind a gRPC service to load balancing virtual server by using the Citrix ADC command interface.

At the command interface, type:

bind lb vserver <name> <serviceName>

Example:

bind lb vserver lb-grpc svc-grpc

Map HTTP response code to gRPC status code

If the server does not generate a gRPC status code, the Citrix ADC appliance generates a suitable gRPC status code based on the HTTP response received. The status codes are listed in the below mapping table.

HTTP Response status-code gRPC status code
200 OK
400 INTERNAL = 13
403 PERMISSION_DENIED = 7
401 UNAUTHENTICATED = 16
429, 502, 503, 504 UNAVAILABLE = 14
404 UNIMPLEMENTED = 12

Configure gRPC reverse bridging by using the GUI

Add HTTP profile 1 with HTTP/2 and HTTP/2 direct enabled for load balancing virtual server

  1. Navigate to System > Profiles and click HTTP Profiles.
  2. Enable HTTP/2 option in a HTTP profile 1.

gRPC reverse bridging add http profile with http2 parameter

Add HTTP profile 2 with HTTP/2 disabled for back-end server

  1. Navigate to System > Profiles and click HTTP Profiles.
  2. Enable HTTP/2 option in a HTTP profile 2.
  3. Click OK.

gRPC reverse bridging global backend HTTP/2

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

  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 reverse bridging global backend HTTP/2 enable load balancing

Add service with gRPC endpoint and set to HTTP profile 2

  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 reverse 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 reverse bridging bind service for gRPC endpoint

For detail GUI procedures, see Load Balancing topic.

gRPC reverse bridging