YumaPro SDK Architectural Components

../_images/Server_Architecture_gNMI_02-01-2022.png

gNMI Introduction

This document describes the gNMI (gRPC Network Management Interface) integration within the netconfd-pro server and ypgnmi-app application. The model-driven configuration and retrieval of operational data using the gNMI CAPABILITIES, GET and SET gRPCs. gNMI version 0.4.0 is supported.

Throughout this specification the following terminology is used:

Telemetry
- refers to streaming data relating to underlying characteristics of the device - either operational state or configuration
Configuration
- elements within the data schema which are read/write and can be manipulated by the client
Target
- the device within the protocol which acts as the owner of the data that is being manipulated or reported on. Typically this will be a netconfd-pro server that communicate with the client with help of ypgnmi-app application
Client
- the device or system using the protocol and the service described in this document to query/modify data on the target, or act as a collector for streamed data. Typically this will be a network management system. The client will contact the ypgnmi-app application to query/modify data on the target

gNMI Features

The main gNMI service functionality contains the following requests (gRPC):

Capabilities used by the client and target as an initial handshake to exchange capability information
Get used to retrieve snapshots of the data on the target by the client
Set used by the client to modify the state of the target
Subscribe used to control subscriptions to data on the target by the client

Future revisions of the gNMI specification MAY result in additional services being introduced, and hence an implementation MUST NOT make assumptions that limit to a single service definition.

The ypgnmi-app application is capable of handling these requests and transferring them to the netconfd-pro server for further processing, as well as handle replies from the netconfd-pro server and transmit them back to the gNMI clients.

gNMI Protocol Restrictions

The Phase I of the gNMI protocol integration has several gNMI protocol limitations and does not fully implement the whole set of gNMI protocol features.

Node Values Restrictions for Structured Data Types

The value of a data node (or subtree) is encoded in a 'TypedValue' message as a one of field to allow selection of the data type by setting exactly one of the member fields. The possible data types include:

Scalar types
Additional types used in some schema languages
Structured data types (e.g., to encode objects or subtrees)

When structured data is sent by the client or the target in an Update message, it MUST be serialized according to one of the supported by gNMI protocol encodings listed in the Encoding enumeration. The table below lists the gNMI protocol supported encodings and their corresponding TypedValue fields. The Phase I of the gNMI protocol integration implements only the Structured data types and the JSON IETF encoding. Other encodings types may be implemented in the feature.

The target never utilizes the Encoding enumeration to declare to the client the type of encoding utilized, so the client must infer the encoding from the populated TypedValue field.

Name	Description	TypedValue	Encoding
JSON	A JSON encoded string	json_val	0
Bytes	An arbitrary sequence of bytes	bytes_val	1
Proto	A Protobuf encoded message using protobuf.any	any_val	2
ASCII	An ASCII encoded string representing text formatted according to a target-defined convention	ascii_val	3
JSON_IETF	A JSON encoded string using JSON encoding compatible with [RFC 7951]	json_ietf_val	4

The Phase I of the gNMI protocol integration implements JSON_IETF encoding. The client MUST support the JSON encoding as a minimum to successfully utilize the target’s replies.

E.g. using the following example data tree:

root +
     |
     +-- a +
           |
           +-- b[name=b1] +
                          |
                          +-- c +
                                |
                                +-- d (string)
                                +-- e (uint32)

The following serializations would be used:

For /a/b[name=b1]/c:

update: <
  path: <
    elem: <
      name: "a"
    >
    elem: <
      name: "b"
      key: <
        key: "name"
        value: "b1"
      >
    >
    elem: <
      name: "c"
    >
  >
  val: <
    json_ietf_val: `{ "d": "AStringValue", "e": 10042 }`
  >
>

For /a:

update: <
  path: <
    elem: <
      name: "a'
    >
  >
  val: <
    json_ietf_val: `{ "b": [
                      {
                        "name": "b1",
                        "c": {
                        "d": "AStringValue",
                          "e": 10042
                        }
                       }
                   ]
            }`
  >
>

GetRequest Message Wildcards Restriction

A Path is a set of paths for which the client is requesting a data snapshot from the target. The path specified MAY utilize wildcards. The Phase I of the gNMI protocol integration supports only fully-specified paths. The wildcards in GetRequests may be supported in the feature.

gNMI Introduction

gNMI Features

gNMI Protocol Restrictions

Node Values Restrictions for Structured Data Types

GetRequest Message Wildcards Restriction

Subscribe Restriction