gRPC framework

Beginning with Itential Platform 6, Itential Automation Gateway (IAG) works 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 lower processing complexity. For more information, refer to the gRPC documentation site.

Install gRPC

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

$
pip install grpcio==1.53.0
$
pip install pygnmi

Verify gRPC is enabled

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

Configure gRPC

Open Automation Gateway and navigate to gRPC in the left navigation. gRPC contains tabbed subheadings for:

• Inventory
• GNMI Execute
• GNOI Execute

Inventory

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

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.

set

The gnmi_set mechanism is used to execute a command.

GNOI execute

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

Create or add 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.

gRPC device variables

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

Execution file history output

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

Configuration

You can set grpc.max_send_message_length when creating gRPC devices. If this parameter is not set, the system falls 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 grpc.max_send_message_length in the grpc_options. This value should be specified in MB.

1
{
2
  "name": "gRPC_device",
3
  "variables": {
4
    "host": "10.102.200.824",
5
    "password": "admin",
6
    "username": "admin",
7
    "insecure": true,
8
    "port": 57777,
9
    "grpc_options": {"grpc.max_send_message_length": 3}
10
  }
11
}

Default behavior

If grpc.max_send_message_length is not explicitly set, the system uses 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 defaults.

Send a JSON POST to create a gRPC device

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

1
{
2
  "name": "iosxr-cloud",
3
  "variables": {
4
    "host": "sandbox-iosxr-1.cisco.com",
5
    "password": "C1sco12345",
6
    "username": "admin",
7
    "insecure": true,
8
    "port": 57777
9
  }
10
}

Use TLS with gRPC devices

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

JSON POST example

TLS secured gRPC device without server certificate validation

1
{
2
  "name": "iosxr-cloud",
3
  "variables": {
4
    "host": "sandbox-iosxr-1.cisco.com",
5
    "password": "C1sco12345",
6
    "username": "admin",
7
    "insecure": false,
8
    "skip_verify": true,
9
    "port": 57777
10
  }
11
}