NETCONF NED Builder

Introduction

Before a NETCONF capable device can be managed by NSO a corresponding NETCONF NED needs to be loaded. While no code needs to be written for such NED, it needs to contain YANG data models for this kind of devices.

While in some cases the YANG models may be provided by the device's vendor, devices that implement RFC 6022 YANG Module for NETCONF Monitoring are able to provide their YANG models using the functionality described in this RFC.

The NETCONF NED builder functionality helps the NSO developer to onboard new kind of devices by fetching the YANG models from a reference device of this kind and building a NETCONF NED of them.

Overview of the NETCONF NED builder workflow

The following steps need to be performed in order to build a new NED using NETCONF NED builder functionality:

Configure the reference device in NSO under /devices/device list. Use the base netconf ned-id for this device as there is no ned-id specific to this kind of devices defined in NSO yet.
Create a new NETCONF NED builder project. In order to access the NETCONF NED builder data model devtools session parameter should be set to true using devtools true (C-style) / set devtools true (J-style) command in the CLI. The project's family-name typically consists of the vendor and the name of the OS the device is running (for example, cisco-iosxr) and the major-version is the NED version which may or may not reflect the actual device's OS version. The idea is that the NED major version only needs to be changed if backwards incompatible changes has been introduced in the device's YANG model compared to the previous NED version. The rules for backwards compatibility between YANG modules are described in RFC 6020 YANG section 10 Updating a Module.
Running the fetch-module-list initiates NETCONF connection to the device and collects the list of YANG modules supported by the device which is stored in the module list under the NETCONF NED builder project.
Once the list of modules has been collected the developer needs to decide which YANG modules need to be included in the NED and indicate these modules by using select action on these modules in the module list. By default all the modules are deselected. Once a module is selected it will be downloaded from the device in the background.
Once the modules are selected and successfully downloaded the developer may initiate a NED build using build-ned action. See the section called “Building the NED”.
A successfully built NED may be exported in form of a tar-file using the export-ned action. The tar file name is constructed according to the naming convention (ncs-<ncs-version>-<ned-family>-nc-<ned-version>.tar.gz) and the user chooses the directory the file needs to be created in. The user must have write access to the directory.
An alternative to letting NSO build the NED is to create a development version of the NED using make-development-ned action. This is useful if, for example, there is an intention to maintain this version of the NED with the upcoming minor (backwards compatible) YANG model revisions, if the NED needs to support creating a NETSIM device, or if the YANG models provided by the device need to be manually edited due to errors in compilation. A development version of the NED is not built, but instead contains the Makefile with the rules to build the NED. Essentially, it is the same package that would be created using the ncs-make-package tool with --netconf-ned flag.
It is important to note that deleting the NETCONF NED builder project also deletes the list of modules along with the selection data all of the downloaded YANG modules and working copy of the NED. Only the exported NED tarball or development NED are kept. The selection data may also be saved in form of a selection profile as described in the section called “Selecting the modules”.

Selecting the modules

Principles of selecting the modules

Selecting the modules for inclusion in the NED is a crucial step in the process of building the NED. The recommendation is to select only the modules necessary to perform the tasks within the given NSO installation to reduce memory consumption and size of sync-from, improve upgrade times.

For example, if the aim of the NSO installation is exclusively to manage BGP on the device and necessary configuration is defined in a separate module, then only this module needs to be selected. If there are several services running within the NSO installation, then it might be necessary to include more data models in the single NED for a given kind of devices. However if the NSO installation is used, for example, to take full backups of the devices' configuration, then all modules need to be included the NED.

Selecting a module will also by default select the module's dependencies (namely, modules that are known to deviate this module in the device's implementation and modules imported by the selected modules). To disable this behaviour a no-dependencies flag may be used, but it should be noted that with dependencies missing the NED will fail to build. Deselecting a module, on the other hand, does not automatically deselect modules depending on it.

Selecting modules using CLI

Using select action on the module list entry will set a selection flag on it.

# don't forget to enable devtools
ncs# devtools true
ncs# netconf-ned-builder project cisco-iosxr 6.6 module \
     Cisco-IOS-XR-ifmgr-cfg 2017-09-07 select
ncs#

Once the module is selected the download starts automatically in the background.

ncs# show netconf-ned-builder project cisco-iosxr 6.6 \
     module Cisco-IOS-XR-ifmgr-cfg 2017-09-07
module Cisco-IOS-XR-ifmgr-cfg 2017-09-07
 namespace http://cisco.com/ns/yang/Cisco-IOS-XR-ifmgr-cfg
 import Cisco-IOS-XR-types
 location  [ NETCONF ]
 status    selected,downloaded
ncs#

We also see that the NETCONF NED Builder identified module Cisco-IOS-XR-types as being imported by Cisco-IOS-XR-ifmgr-cfg and it has been also selected.

ncs# show netconf-ned-builder project cisco-iosxr 6.6 \
     module Cisco-IOS-XR-types
module Cisco-IOS-XR-types 2018-06-29
 namespace http://cisco.com/ns/yang/cisco-xr-types
 location  [ NETCONF ]
 status    selected,downloaded
ncs#

CLI wildcards may be used to select multiple modules

ncs# netconf-ned-builder project cisco-iosxr 6.6 \
     module Cisco-IOS-XR-* * select
ncs#

Selection profiles

One may want to reuse a selection of modules, for example if the same modules should be selected for the new major version of the NED as for the previous one. For this purpose NETCONF NED builder supports selection profiles.

Selection profile is configuration data. It may be created in two ways:

By exporting current selection from existing project using save-selection action on the project list entry.
By manually creating a profile in configuration mode. As any other configuration it may be also, for example, be exported to XML file and loaded later.

A profile is applied to a certain project using apply action on the profile list entry.

ncs# netconf-ned-builder profile xr-profile apply \
     family-name cisco-iosxr major-version 6.6
result applied
selected [ <modules that have been selected> ]
ncs#

It is important to note that while select action selects modules with dependencies, a profile is assumed to be an exhaustive selection of modules and hence the dependencies are ignored. This is also indicated by no-dependencies status flag on the selected modules.

Deselecting modules

Modules that have been selected but are not needed anymore may be deselected using deselect action. It should be noted that this action only deselects the target module and does not automatically deselect modules that are dependent on it nor its dependencies (so, select and deselect actions are asymmetrical in this regard).

Modules that had been downloaded prior to being deselected are not removed from the NETCONF NED Builder cache, but they will not be included into the NED package upon building or making a development package. At the same time, a deselected module is not removed from a package that has already been built.

Building the NED

The NED build is triggered using build-ned action on the project list entry.

ncs# netconf-ned-builder project cisco-iosxr 6.6 build-ned

ncs# show netconf-ned-builder project cisco-iosxr 6.6 build-status
build-status success
ncs#

If there was no error reported, then the build has been successful. There might be some warnings issued by the compiler that will be saved in build-warning leaf under module list entries. If the action returned an error mentioning that it was not possible to compile the NED bundle, then in addition to warnings there will be some errors that are saved in build-error leaf under module list entries.

ncs# netconf-ned-builder project cisco-iosxr 6.6 build-ned
Error: Failed to compile NED bundle
ncs# show netconf-ned-builder project cisco-iosxr 6.6 build-status
build-status error
ncs# show netconf-ned-builder project cisco-iosxr 6.6 \
     module build-error
module openconfig-telemetry 2016-02-04
 build-error at line 700: <error message>
ncs#

Possible ways to resolve this error would be to

deselect the module if it is not critical for NSO operations towards this kind of devices
use make-development-ned action to create a development version of NED and fix the issue in the YANG module

In addition to processed compiler output that is saved per module list entry it may be necessary to see the full compiler output. It is saved in the compiler-output leaf under the project list entry. The leaf is hidden by hide-group debug and may be accessed on the CLI using unhide debug command if the hide-group is configured in ncs.conf.