gNMI Subsystem

The following diagram illustrates key components of the gNMI and netconfd-pro integration.

../_images/ypgnmi_integration.png

As illustrated above gNMI clients can be written in any languages that are supported for gNMI clients. The client part is out of the scope of this document and the current gNMI protocol integration does not include the client part.

  • The clients communicate to the target (netconfd-pro) with the help of the ypgnmi-app application and send gRPC request to the application.

  • The ypgnmi-app application is written in GO language and talk to the netconfd-pro server via socket with XML encoding and acts as a YControl subsystem.

  • The main role of this application is to translate clients requests to XML and contact netconfd-pro server and send the replies back to the gNMI clients.

  • The ypgnmi-app application is a YControl subsystem that communicates to the netconfd-pro server and also it is a gNMI server that communicates to the gNMI clients.

  • It is responsible for encoding conversion between gNMI gRPC to XML that are sent to the netconfd-pro server and vice versa.

The messages processing between gNMI client to the netconfd-pro server can be split into the following components:

  • gNMI clients to the ypgnmi-app application processing - includes message parsing and conversion of the messages to the XML message

  • The ypgnmi-app application to the netconfd-pro server messages processing. YControl messages exchange encoded in XML

  • The netconfd-pro server internal processing – includes subsystem registration, subsystem messages handling and parsing, conversion to RESTCONF RCB for the request processing.

    • YANG-PATCH in case of gNMI SetRequest

    • RESTCONF GET in case of gNMI GetRequest and Subscribe with mode ONCE

gNMI Client to netconfd-pro Processing

The following diagram illustrates the messages processing path from gNMI clients to the netconfd-pro server and to the database for configuration and retrieval.

../_images/gnmi_netconfd.png

ypgnmi-app Processing

The ypgnmi-app application implements multiple goroutines to manage the replies and the clients. All of the managers are goroutines. They run in parallel and asynchronously.

  • Client Manager goroutine: Responsible for all the gNMI clients connections. After the client contacts the gNMI server, this goroutine registers the client, stores its information and runs all the authentication processing. It verifies the certificates and triggers the connection to be shutdown.

  • Reply Manager goroutine: This manager is responsible for any already parsed messages from the netconfd-pro server or gNMI client, it stores any not processed messages that are ready to be processed. It is responsible for finding the corresponding clients that wait for the response and trigger the response procedure.

  • Message Parser goroutine: It is responsible for all the messages parsing. It parses messages from clients encoded in the protobuf and converts them into XML encoded messages to be sent to the netconfd-pro server and vice versa.

  • Message Manager goroutine: This manager is responsible for storing any ready to be processed messages that are going to the netconfd-pro server and that are coming back from the server.

The core of the ypgnmi-app is the gNMI server that is built on top of gRPC server. It contains gNMI server code that is responsible for the following:

  • gNMI client to the netconfd-pro server communication

  • Handle GET/SET/Subscribe/Capability callbacks. Send/get messages from the netconfd-pro server and respond to the clients.

  • Register gNMI server

  • Register gRPC server for the protobuf message handling

  • Run main Serve loop that handles all the client/server communication

The ypgnmi-app application implements the HTTP/2 server over TLS in Go standard package golang.org/x/net/http2. This package provides authentication, connection, listen, etc handlers that fully fulfill all the requirements for the ypgnmi-app application.

The ypgnmi-app application has the following startup steps for the gNMI server component:

  • Initialize all the prerequisites and parse all the CLI parameters

  • Based on the netconfd-pro server modules capability create gNMI target

  • Open TCP socket to listen for clients requests

  • Serve any incoming gNMI messages from gNMI clients and re-transmit them to the netconfd-pro server if needed with the help of all the goroutine managers.

The ypgnmi-app acts as a YControl subsystem. It continuously listens to the netconfd-pro server and keeps the AF_LOCAL or TCP socket open to continue communication whenever it is needed. The communication is terminated only if the ypgnmi-app application is terminated or the netconfd-pro server terminates.

All the message definitions described in the yumaworks-yp-gnmi.yang YANG module are similar to the original gNMI .proto message definitions which make the conversion easier and faster.

The ypgnmi-app application has the following startup steps to initialize connection with the netconfd-pro server:

  • Initialize all the prerequisites and parse all the CLI parameters

  • Open socket and send <ncx-connect> request to the server with

    • transport = netconf-aflocal

    • protocol = yp-gnmi

  • Register yp-gnmi service

    • Send <register-request> to the server

    • Register the 'yp-gnmi' subsystem and initialize all corresponding code in the netconfd-pro server to be ready to handle 'yp-gnmi' service requests

  • Create a data model structure that will be used for gNMI client/server communication

    • Send <config-request> to the server

    • Feed the gNMI ModelData with all supported modules

  • Keep listening socket until terminated

ypgnmi-app Message Format

The ypgnmi-app application uses several messages to interact with the netconfd-pro server.

These messages are defined in the yumaworks-yp-gnmi.yang YANG module. The ypgnmi-app payload is defined as a YANG container that augments the YControl “message-payload” container.

The following diagram illustrates the YControl messages overview:

../_images/ypgnmi_messages.png

ypgnmi-app Registration Message Flow

During the startup phase, the server will initialize the yp-gnmi subsystem callback functions and handlers (similar way as for db-api module does).

The connection with the server is getting started with <ncx-connect> message that adds the YControl subsystem with the “yp-gnmi” subsystem ID to the server.

YControl protocol connection parameters:

  • transport: netconf-aflocal

  • protocol: yp-gnmi

  • <port-num> not used

Additional parameters:

  • subsys-id: yp-gnmi

The Registration message flow looks as follows:

  • ypgnmi-app to Server: config-request The service requests the netconfd-pro server its configuration in 1 message.

  • Server to ypgnmi-app: config-response The server responds to the config request with a list of modules that need to be loaded to gNMI server DataModel

  • ypgnmi-app to Server: register-request The ypgnmi-app service registers callbacks supported by the subsystem.

  • Server to ypgnmi-app: ok The server responds to the register request with an <ok> or an <error> message

netconfd-pro Processing for gNMI

The following diagram illustrates how the ypgnmi-app application requests are getting processed in the netconfd-pro server.

../_images/gnmi_internal_message.png

The message processing steps:

  • Parse an incoming <ycontrol> message from a subsystem

  • Handle an incoming <ycontrol> message from a subsystem and dispatch this message to the service handler

  • Run callback template for YControl yp-gnmi services: message handler

  • Initializer the RESTCONF specific dispatcher for the yp-gnmi request

    • Dispatch RESTCONF GET request in case of gNMI GetRequest

    • Dispatch YANG-PATCH processing in case of gNMI SetRequest

  • Construct the Response based on the RESTCONF dispatcher return values

  • Send the reply to the yp-gnmi service