gNMI Protocol

This feature describes the model-driven configuration and retrieval of operational data using the gRPC Network Management
Interface (gNMI) CAPABILITIES, Get and Set remote procedure calls (RPCs). gNMI version 0.4.0 is supported.

Restrictions for the gNMI Protocol

The following restrictions apply to the feature:

Subscribe RPC services are not supported.

JSON, BYTES, PROTO, and ASCI encoding options are not supported.

JSON IETF keys must contain a YANG-prefix where the namespace of the following elements differs from the parent. This means
that the routed-vlan derived from augmentation in openconfig-vlan.yang must be entered as oc-vlan:routed-vlan because it is different from the namespace of the parent nodes (parent nodes have the prefix, oc-if)

GetRequest:

Operational data filtering is not supported.

Use models are not supported. These are a set of model data messages indicating the schema definition modules that define
the data elements that must be returned in response to a Get RPC call.

GetResponse:

Alias is not supported. It is a string that provides an alias for a prefix specified within the notification message.

Delete is not supported. It is a set of paths that are to be removed from a data tree.

Information About the gNMI Protocol

About GNMI

gNMI is gRPC Network Management Interface developed by Google. gNMI provides the mechanism to install, manipulate, and delete
the configuration of network devices, and also to view operational data. The content provided through gNMI can be modeled
using YANG.

gRPC is a remote procedure call developed by Google for low-latency, scalable distributions with mobile clients communicating
to a cloud server. gRPC carries gNMI, and provides the means to formulate and transmit data and operation requests.

When a gNMI service failure occurs, the gNMI broker (GNMIB) will indicate an operational change of state from up to down,
and all RPCs will return a service unavailable message until the database is up and running. Upon recovery, the GNMIB will
indicate a change of operation state from down to up, and resume normal handling of RPCs.

JSON IETF Encoding for YANG Data Trees

The JSON type indicates that the value is encoded as a JSON string. JSON_IETF-encoded data must conform to the rules for JSON
serialisation described in RFC 7951. Both the client and target must support JSON encoding.

Instances of YANG data nodes (leafs, containers, leaf-lists, lists, anydata nodes, and anyxml nodes) are encoded as members
of a JSON object or name/value pairs. Encoding rules are identical for all types of data trees, such as configuration data,
state data, parameters of RPC operations, actions, and notifications.

Every data node instance is encoded as a name/value pair where the name is formed from the data node identifier. The value
depends on the category of the data node.

The "leaf" Data Node

A leaf node has a value, but no children, in a data tree. A leaf instance is encoded as a name/value pair. This value can
be a string, number, literal "true" or "false", or the special array "[null]", depending on the type of the leaf. In the case
that the data item at the specified path is a leaf node (which means it has no children, and an associated value) the value
of that leaf is encoded directly. (A bare JSON value is included; it does not require a JSON object.)

The following example shows a leaf node definition:

leaf foo {
type uint8;
}

The following is a valid JSON-encoded instance:

"foo": 123

gNMI GET Request

The gNMI Get RPC specifies how to retrieve one or more of the configuration attributes, state attributes, derived state attributes,
or all attributes associated with a supported mode from a date tree. A GetRequest is sent from a client to the target to retrieve
values from the data tree. A GetResponse is sent in response to a GetRequest.

gNMI SetRequest

The Set RPC specifies how to set one or more configurable attributes associated with a supported model. A SetRequest is sent
from a client to a target to update the values in the data tree.

SetRequests also support JSON keys must contain a YANG-prefix, in which the namespace of the following element differs from
parent.

For example, the routed-vlan element derived from augmentation in openconfig-vlan.yang must be entered as oc-vlan:routed-vlan, because it is different from the namespace of the parent node (The parent node prefix is oc-if.).

The total set of deletes, replace, and updates contained in any one SetRequest is treated as a single transaction. If any
subordinate element of the transaction fails; the entire transaction will be disallowed and rolled back. A SetResponse is
sent back for a SetRequest.

gNMI Wildcards

The gNMI protocol supports wildcards for Get paths. This is the ability to use a wildcards in a path to match multiple elements.
These wildcards indicate all elements in a given subtree in the schema.

An elem is an element, and it is a value between / characters in an xpath. An elem is also available in a gNMI path. For example, the position of a wildcard relative to elem names implies that the wildcard stands for an interface, and is interpreted as all interfaces.

There are two types of wildcards; implicit and explicit, and both are supported. Get paths support all types and combinations
of path wildcards.

Implicit wildcards: These expand a list of elements in an element tree. Implicit wildcard occurs when a key value is not provided
for elements of a list.

The following is a sample path implicit wildcard. This wildcard will return the descriptions of all interfaces on a device:

Standards and RFCs

Technical Assistance

Description

Link

The Cisco Support website provides extensive online resources,
including documentation and tools for troubleshooting and
resolving technical issues with Cisco products and technologies.

To receive security and technical information about your
products, you can subscribe to various services, such as the
Product Alert Tool (accessed from Field Notices), the Cisco
Technical Services Newsletter, and Really Simple Syndication
(RSS) Feeds.

Access to most tools on the Cisco Support website requires a
Cisco.com user ID and password.

Feature Information for the gNMI Protocol

The following table provides release information about the feature or features described in this module. This table lists
only the software release that introduced support for a given feature in a given software release train. Unless noted otherwise,
subsequent releases of that software release train also support that feature.

Use Cisco Feature Navigator to find information about platform support and Cisco software image support. To access Cisco
Feature Navigator, go to www.cisco.com/go/cfn. An account on Cisco.com is not required.

Table 5. Feature Information for the gNMI Protocol

Feature Name

Release

Feature Information

gNMI Protocol

Cisco IOS XE Fuji 16.8.1a

This feature describes the model-driven configuration and retrieval of operational data using the gNMI capabilities, GET and
SET RPCs.

This feature was implemented on the following platforms:

Cisco Catalyst 9300 Series Switches

Cisco Catalyst 9400 Series Switches

Cisco Catalyst 9500 Series Switches

Cisco IOS XE Gibraltar 16.10.1

gNMI namespaces and gNMI wildcards support were added to the following platforms: