gRPC Framework

Beginning with the Platform 6 release, Automation Gateway will work with gRPC for connecting devices. gRPC is a cross-platform, open source framework for implementing RPC (Remote Procedure Call) APIs in any environment. As a framework, gRPC offers pluggable support for load balancing, tracing, health checking and authentication with a lower processing complexity. For more information, refer to the gRPC documentation site.

Install gRPC

To get started, install pip in the virtual environment. Restart Automation Gateway.

pip install grpcio==1.53.0
pip install pygnmi

Verify gRPC is Enabled

Go to Configuration in Automation Gateway using the left side navigation and click gRPC to verify the setting has been enabled. Select the checkbox and click the Save  icon.

Figure 1: Enable GRPC

Configure gRPC

Open Automation Gateway and navigate to gRPC in the left navigation. GPRC will contain tabbed subheadings (menus) for:

• Inventory
• GNMI Execute
• GNOI Execute

Inventory

The Inventory list contains devices created to run and use gRPC. The device will appear in the left side navigation bar. Clicking on the device will display parameters (i.e., host, port, username, etc.) and values specific to the device. Click the pencil icon to edit the parameters.

Figure 2: Inventory

GNMI Execute

Use GNMI Execute to configure get and set for gRPC.

get

The gnmi_get mechanism is used to pull-in or acquire data.

Figure 3: GRPC gnmi_get

set

The gnmi_set mechanism is used to execute a command.

Figure 4: GRPC gnmi_set

GNOI Execute

GNOI Execute is used for operational commands on a device such as ping, trace route, and reboot.

Figure 5: GNOI Execute

Creating or Adding a Device in gRPC

To create a device in gRPC, click the + sign in the top toolbar above the left side navigation. A Create dialog opens. Use the dropdown to select gRPC Device. Input a device name and configure the variables needed to create the device. Once all the device variables are set, click the Create button.

Figure 6: Configure Device

gRPC Device Variables

Variable datatypes can be found in the OpenAPI v3 specification found in the help section UI of Automation Gateway.

A list of GRPC device variables are referenced in the table below.

Execution File History Output

Users now have the ability to set a custom maximum send message length using grpc.max_send_message_length for gRPC devices. This provides greater flexibility and control over the gRPC communication parameters, allowing users to override the default value if needed.

Configuration

Users can set grpc.max_send_message_length when creating gRPC devices. If this parameter is not set, the system will fall back to the default value defined in the properties.yml file

How to Set Maximum Send Message Length

When creating or configuring a gRPC device, you can specify the grpc.max_send_message_length in the grpc_options. This value should be specified in MB. Here is an example of how to set this parameter:

{

"name": "gRPC_device",

"variables": {

"host": " 10.102.200.824",

"password": "admin",

"username": "admin",

"insecure": true,

"port": 57777,

"grpc_options": {"grpc.max_send_message_length": 3}

}

Figure 7 Edit Device Variables: grpc.max_send_message_length

Default Behavior

If the grpc.max_send_message_length is not explicitly set by the user, the system will use the default value defined in the properties.yml file. This ensures that users who do not need to customize this parameter can rely on predefined safe and optimal default settings.

Sending a JSON POST to Create a gRPC Device

A JSON POST can be sent to /api/v2.0/inventories/grpc/default/devicesto create a device.

Example post request:

{
  "name": "iosxr-cloud",
  "variables": {
    "host": "sandbox-iosxr-1.cisco.com",
    "password": "C1sco12345",
    "username": "admin",
    "insecure": true,
    "port": 57777
  }
}

Using TLS with gRPC Devices

Before connecting securely to gRPC devices, an appropriately configured system PKI infrastructure is required (trusted root certificates and client certificates). Please consult your system administrator to ensure these requirements are in place before proceeding with a secure GRPC device setup. To use secure TLS certificates when using GRPC, configure the device and set insecure to false.

A simple device example (JSON POST) that will skip server verification is shown below.

JSON POST Example

TLS Secured gRPC Device without Server Certificate Validation

{
  "name": "iosxr-cloud",
  "variables": {
    "host": "sandbox-iosxr-1.cisco.com",
    "password": "C1sco12345",
    "username": "admin",
    "insecure": false,
    "skip_verify": true,
    "port": 57777
  }
}