- 26 Jun 2024
-
DarkLight
-
PDF
gRPC
- Updated on 26 Jun 2024
-
DarkLight
-
PDF
Beginning in the 2023.2 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.
Variable | Description | Required |
---|---|---|
host | The hostname or IP address of the gRPC device. | Yes |
port | The gRPC TCP port to use. | Yes |
username | gRPC username | Yes |
password | gRPC password | Yes |
insecure | Used to support (or not support) a non-TLS connection to the device. | Yes |
debug | Debug gRPC operations (advanced). | Yes |
path_cert | Path to the TLS root certificate store. | No |
path_key | Path to the gRPC client certificate key. | No |
path_root | Path to the TLS root certificate store. | No |
grpc_override | gRPC override parameters (advanced). | No |
skip_verify | Skip verification of the TLS server certificate that is presented. | No |
grpc_timeout | Timeout for gRPC connection and channel operations. | No |
grpc_options | Additional gRPC channel options (advanced). | No |
show_diff | Show gRPC GNMI differences (advanced, untested). | No |
token | gRPC access token (advanced). | No |
Sending 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.
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
}
}