Citrix ADC

gRPC with the responder policy

The gRPC with responder policy configuration explains how a Citrix ADC appliance provides different responses to gRPC requests over the HTTP/2 protocol. When users request a website home page, you might want to provide a different home page depending on where each user is located or the browser the user is using.

The following diagram shows the components that interact.

gRPC with a responder policy

  1. Enable the responder feature on the appliance.
  2. Configure the responder action to generate a custom response, redirect a request to a different webpage, or reset a connection.
  3. Configure the responder policy for determining the gRPC requests (traffic) on which an action has to be taken.
  4. Bind the responder policy to the load balancing virtual server to examine if the traffic matches the policy expression.
  5. By using a responder policy, you can perform the following based on the gRPC status code.

Configure gRPC call termination with the responder policy by using the CLI

To configure gRPC call termination with the responder policy, you must complete the following steps:

  1. Enable the responder feature
  2. Add a responder action
  3. Add a responder policy and associate responder action
  4. Bind the responder policy to load balancing virtual server

Enable the responder feature

To use the responder feature, you must first enable it.

At the command prompt, type:

enable ns responder

Add the responder action

After enabling the feature, you must configure the responder action for handling the gRPC response based on the status code returned by the back-end server.

At the command prompt, type:

add responder action <name> <type>

Example:

add responder action grpc-act respondwith "HTTP/1.1 200 OK\r\nServer: NS-Responder\r\nContent-Type:application/grpc\r\ngrpc-status: 12\r\ngrpc-message: Not Implemented\r\n\r\n" + "Method: " + HTTP.REQ.URL+ "is not implemented."

Adding responder policy

After you configure a responder action, you must next configure a responder policy to select the gRPC request to which the Citrix ADC appliance must respond.

At the command prompt, type:

add responder policy <name> <expression> <action> [<undefaction>]-appFlowaction <actionName> Example:

add responder policy grpc-resp-pol1 HTTP.REQ.URL.NE(“/helloworld.Greeter/SayHello”) grpc-act

Bind responder policy to load balancing virtual server

To put a policy into effect, you must bind it to the load balancing virtual server with the gRPC service.

At the command prompt, type:

bind responder global <policyName> <priority> [<gotoPriorityExpression> [-type <type>] [-invoke (<labelType> <labelName>)]

Example:

bind lb vserver lb-grpc svc-grpc -policyName grpc-resp-pol1 –priority 100

For more information about the responder policy, see Responder Policy topic.

Policy expressions for matching gRPC protocol buffer fields

The Citrix ADC appliance supports the following policy expressions in the gRPC configuration:

  • gRPC protocol buffer field access. The arbitrary gRPC API call matches the message field number with the new policy expressions. In a PI configuration, the matches are done using only the ‘field numbers’ and ‘API path’.

  • gRPC header filtering. The “HttpProfile” parameters for gRPC is used to adjust the default behavior of gRPC parsing (including gRPC policy expressions). The following parameters are applicable to gRPC policy expressions:

    • gRPCLengthDelimitation. It is enabled by default and expects the protocol buffers to be presented with a length delimited message.

    • gRPCHoldLimit. The default value is 131072. It is the maximum protocol buffer message size in bytes. It is also the maximum string length and the maximum ‘byte’ field length as well.

Configure gRPC advance policy expressions by using the CLI

At the command prompt, type:

set ns httpProfile <name> -http2 ( ENABLED | DISABLED ) -gRPCLengthDelimitation ( ENABLED | DISABLED ) -gRPCHoldLimit <int>

Example:

set ns httpProfile http2gRPC -http2 ENABLED -gRPCLengthDelimitation ENABLED -gRPCHoldLimit 131072

Configure gRPC header filtering parameters by using the GUI

  1. Navigate to System > Profiles and click HTTP Profiles.

  2. On the Create HTTP Profile page, scroll down to HTTP/3 section, select gRPC Length Delimitation.

    gRPC length delimitation

The following policy expression example shows a value in message 5, submessage 4, and field 3. It is a 32-bit int equal to 2.

http.req.body(1000).grpc.message(5).message(4).int32(3).eq(2)

The following policy expressions are added for matching gRPC protocol buffer message fields by number:

  • message
  • double
  • float
  • int32
  • int64
  • uint32
  • uint64
  • sint64
  • sint32
  • fixed32
  • fixed64
  • sfixed32
  • sfixed64
  • bool
  • string
  • enum
  • bytes

API path matching

The API path matching is used to match the correct gRPC API call when more than one API is used. Match the API path, which can be found in the ‘: path’ pseudo header in the HTTP request.

Example:

http.req.header(":path").eq("acme.inventory.v1/ListBooks")
gRPC with the responder policy