> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/itential-gateway/4/grpc-framework/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# gRPC framework

> Overview of gRPC framework support in Itential Gateway, including installation, configuration, device management, and TLS setup.

Beginning with Itential Platform 6, Itential Gateway 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](https://grpc.io/docs/).

## Install gRPC

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

```bash
pip install grpcio==1.53.0
pip install pygnmi
```

## Verify gRPC is enabled

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

![](/_fern-img/03a43186baff024e38dd759c569fe2a95c4f9654727a79b08fe844ecd6926ff5.webp)

## 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.

![](/_fern-img/f9f98db9002493845feb745a76e4f4c59e77fd2cdb09ff6f29aded120f46bdde.webp)

### 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.

![](/_fern-img/95d967bcef96b22f15c749fb461194b9060b6b9b19adc4005df43961888fbacc.webp)

#### set

The `gnmi_set` mechanism is used to execute a command.

![](/_fern-img/081f32199f0ecb20513180505e8a9f152bfc12c721183b2f85a38cfd9c1b438a.webp)

### GNOI execute

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

![](/_fern-img/2a59f662adddf7b3bfa0c09e14621da1fc94d51c2e8886256b43158e0e1e1df0.webp)

## 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.

![](/_fern-img/14a613c272fee2695c3ab2a8e9019a5187127da35c40132312c2ed385d808f09.webp)

## gRPC device variables

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

| 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       |

## Execution file history output

> **Info**
>
> New gRPC communication parameter: effective in Platform 6 and later.

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.

```json
{
  "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}
  }
}
```

![](/_fern-img/ac5269de6b5f1aff28c823b0aab5ae16cbd9799a1788605ca0fd1aa7727a1171.webp)

### 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.

> **Info**
>
> * Set the value for `grpc.max_send_message_length` as an integer in MB.
> * A value less than or equal to `0` indicates no limit (unlimited message size).

## 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.

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

## 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**

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

> Overview of gRPC framework support in Itential Gateway, including installation, configuration, device management, and TLS setup.