Configuring gRPC connections to remote gRPC servers

A gRPC configuration defines the connection to a remote gRPC server for use in a stylesheet with the dp:url-open extension element.

About this task

Tip: The equivalent entry point in the CLI is the global grpc command.

To define the connection to a remote gRPC server, specify the proto file that defines the gRPC service. A Protocol Buffers definition (proto) file is a text file with the .proto extension. This file defines the data structure to serialize with Protocol Buffers. The configuration can define multiple endpoints where the RPCs are sent based on the defined load balance policy, which uses the round_robin policy by default.

By default failed connections are retried with the following behavior.
  • A 1-second duration between the first and second attempts.
  • A minimum of a 20-second duration between subsequent attempts.
  • A maximum of a 120-second duration between subsequent attempts.

By default, the maximum message size that the channel supports is 4 MB.

Procedure

  1. In the search field, enter grpc.
  2. From the search results, click gRPC.
  3. Click Add.

Define the general configuration.

  1. Define the basic properties - Name, administrative state, and comments.
  2. In the Protocol Buffers definition file field, specify the proto file that defines the gRPC service.
  3. With the Endpoints property, define the endpoints for the gRPC servers. You can define multiple gRPC servers to load balance.
    1. Click Add.
    2. In the Host field, specify the hostname or IP address of the gRPC server.
    3. In the Port field, specify the port that the gRPC server monitors for incoming RPC requests.
    4. Click Apply to add the entry to the list.
    5. Optional: Repeat this step to define another gRPC server.
  4. From the TLS client list, select the TLS client profile to secure connections with the gRPC server.
  5. From the Load-balancing policy list, select the load-balancing policy to use when multiple endpoints are provided.
    pick_first
    This policy attempts to connect to each endpoint in the defined order and uses the first one that is reachable for all RPCs.
    round_robin
    This policy attempts to connect to all endpoints and rotates each RPC through the connected endpoints. This setting is the default value.

Define network settings.

  1. Set the Enable retry property to control whether to enable the retry function. When enabled, transparent retries failed RPC sends, which is the default behavior.
  2. From the Compression algorithm list, select the compression algorithm for RPC requests that are sent to the remote server.
    deflate
    Compress with the algorithm that RFC 1951 describes. The format is LZ77 with Huffman encoding (Deutsch with an Adler checksum).
    gzip
    Compress with the algorithm that RFC 1952 describes. The format is LZ77 with a 32-bit checksum. (Deutsch without an Adler checksum).
    None
    No compression. This setting is the default value.
  3. In the Max receive message size field, specify the maximum size in bytes for a message that the channel can receive. The default value is 1048576.
  4. In the Max send message size field, specify the maximum size in bytes for a message that the channel can send. The default value is 1048576.
  5. In the Max connection idle timeout field, specify the maximum duration in milliseconds that the client channel can have no RPCs. After this duration elapses, the connection is closed. The default value is 300000.
  6. In the Client idle timeout field, specify the duration in milliseconds after the last RPC completes. After this duration elapses, the channel enters the IDLE state. The minimum value is 1000. The default value is 300000.
  7. In the Keep alive timer field, specify the duration in milliseconds between requests that validate whether the transport is alive. The ping requests are between the client and server. The default value is 300000.
  8. Optional: Modify the reconnection behavior, which applies after the initial connection to an endpoint fails.
    1. In the Initial backoff field, specify the duration in milliseconds between the first and second attempts. The default value is 1000.
    2. In the Min backoff field, specify the minimum duration in milliseconds between subsequent attempts. The default value is 20000.
    3. In the Max backoff field, specify the maximum duration in milliseconds between subsequent attempts. The default value is 120000.

Define parser and printer settings.

  1. Set the Ignore unknown fields property to control whether to ignore unknown fields when parsing from JSON to proto format. The default is to ignore unknown fields.
  2. Set the Add whitespace property to control whether to add whitespace to pretty-print the proto format as JSON. The default is to pretty-print.
  3. Set the Print enum as integer property to control whether to print the value for an enum type with its integer value. The default is to print the value for an enum type with its string value.
  4. Set the Preserve proto field names property to control whether to preserve the proto field names. The default is to preserve field names.
  5. Click Apply to save changes to the running configuration.
  6. Click Save to save changes to the persisted configuration.