../_images/logo.png

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.

Subscribe Restriction

When a client wishes to receive updates relating to the state of data instances on a target, it creates a subscription via the Subscribe RPC. A subscription consists of one or more paths, with a specified subscription mode. The mode of each subscription determines the triggers for updates for data sent from the target to the client.

All requests for new subscriptions are encapsulated within a SubscribeRequest message - which itself has a mode which describes the longevity of the subscription. A client may create a subscription which has a dedicated stream to return one-off data ('ONCE'); a subscription that utilizes a stream to periodically request a set of data ('POLL'); or a long-lived subscription that streams data according to the triggers specified within the individual subscription's mode ('STREAM').

The Phase I of the gNMI protocol integration supports only 'ONCE' Subscription mode. All other modes may be supported in the future.