Applications in NSO

You have seen two different ways in which you can make a configuration change on a network device. With the first, you make changes directly on the NSO copy of the device configuration. The Device Manager picks up the changes and propagates them to the affected devices.

The purpose of the Device Manager is to manage different devices in a uniform way. The Device Manager uses the Network Element Drivers (NEDs) to abstract away the different protocols and APIs towards the devices. The NED contains a YANG data model for a supported device. So, each device type requires an appropriate NED package that allows the Device Manager to handle all devices in the same, YANG-model-based way.

The second way to make configuration changes is through services. Here, the Service Manager adds a layer on top of the Device Manager to process the service request and enlists the help of service-aware applications to generate the device changes. The following figure illustrates the difference between the two approaches.

Figure 4. Device and Service Manager

Still, the Device Manager and the Service Manager are tightly integrated into one transactional engine, using the CDB to store data. Another thing the two managers have in common is packages. Like Device Manager uses NED packages to support specific devices, Service Manager relies on service packages to provide an application-specific mapping for each service type.

But a network application can consist of more than just a configuration recipe, or it may only monitor the network and not provision any configuration at all. So, a package in NSO can implement a generic application that executes custom code for specific NSO events.

NSO allows augmenting the base functionality of the system by delegating certain functions to applications. As the communication must happen on demand, NSO implements a system of callbacks. Usually, the application code registers the required callbacks on start-up, then NSO can invoke each callback as needed. A prime example is a Python service, which registers the cb_create() function as a service callback that NSO uses to construct the actual configuration.

Figure 5. Service callback

In a Python service skeleton, callback registration happens inside a class Main, found in main.py:

class Main(ncs.application.Application):
    def setup(self):
        # Service callbacks require a registration for a 'service point',
        # as specified in the corresponding data model.
        #
        self.register_service('my-svc-servicepoint', ServiceCallbacks)

In this code, the register_service() method registers the ServiceCallbacks class to receive callbacks for a service. The first argument defines which service that is. In theory, a single class could even handle service callbacks for multiple services but that is not a common practice.

On the other hand, it is also possible that no code registered a callback for a given service. This is quite often a result of misspelling or a bug in the code that causes application code to crash. In these situations, NSO presents an error if you try to use the service:

Error: no registration found for callpoint my-svc-servicepoint/service_create of type=external

This error refers to a concept of a service point. Service points are declared in the service YANG model and allow NSO to distinguish ordinary data from services. They instruct NSO to invoke FASTMAP and the service callbacks when a service instance is being provisioned. That means the service skeleton YANG file also contains a service point definition, such as the following:

list my-svc {
  description "This is an RFS skeleton service";

  uses ncs:service-data;
  ncs:servicepoint my-svc-servicepoint;
}

Service point therefore links the definition in the model with custom code. Some methods in the code will have names starting with “cb_”, for instance the cb_create() method, letting you know quickly that they are an implementation of a callback.

NSO implements additional callbacks for each service point, that may be required in some specific circumstances. Most of these callbacks perform work outside of the automatic change tracking, so you need to consider that before using them. The the section called “ Advanced Mapping Techniques ” contains more details.

As well as services, other extensibility options in NSO also rely on callbacks and call points, a generalized version of a service point. Two notable examples are validation callbacks, to implement additional validation logic to that supported by YANG, and custom actions. The the section called “DP API” provides a comprehensive list and an overview of when to use each.

In summary, you implement custom behavior in NSO by providing the following three parts:

This way, an application in NSO can implement all the required functionality for a given use-case (configuration management and otherwise) by registering the right callbacks.

The most common way to implement non-configuration automation in NSO is using actions. An action represents a task or an operation that a user of the system can invoke on demand, such as downloading a file, resetting a device, or performing some test.

Like configuration, actions must also be defined in the YANG model. Each action is described by the action YANG statement that specifies what are its inputs and outputs, if any. Inputs allow a user of the action to provide additional information to the action invocation, while outputs provide information to the caller. Actions are a form of a Remote Procedure Call (RPC) and have historically evolved from NETCONF RPCs. It's therefore unsurprising that with NSO you implement both in a similar manner.

Let's look at an example action definition:

action my-test {
  tailf:actionpoint my-test-action;
  input {
    leaf test-string {
      type string;
    }
  }
  output {
    leaf has-nso {
      type boolean;
    }
  }
}

The first thing to notice in the code is that, just like services use a service point, actions use an action point. It is denoted by the tailf:actionpoint statement and tells NSO to execute a callback registered to this name. As discussed, the callback mechanism allows you to provide custom action implementation.

Correspondingly, your code needs to register a callback to this action point, by calling the register_action(), as demonstrated here:

def setup(self):
    self.register_action('my-test-action', MyTestAction)

The MyTestAction class, referenced in the call, is responsible for implementing the actual action logic and should inherit from the ncs.dp.Action base class. The base class will take care of calling the cb_action() class method when users initiate the action. The cb_action() is where you put your own code. The following code shows a trivial implementation of an action, that checks whether its input contains the string “NSO”:

class MyTestAction(Action):
    @Action.action
    def cb_action(self, uinfo, name, kp, input, output, trans):
        self.log.info('Action invoked: ', name)
        output.has_nso = 'NSO' in input.test_string

The input and output arguments contain input and output data, respectively, which matches the definition in the action YANG model. The example shows the value of a simple Python in string check that is assigned to an output value.

The name argument has the name of the called action (such as “my-test”), to help you distinguish which action was called in the case where you would register the same class for multiple actions. Similarly, an action may be defined on a list item and the kp argument contains the full keypath (a tuple) to an instance where it was called.

Finally, the uinfo contains information on the user invoking the action and the trans argument represents a transaction, that you can use to access data other than input. This transaction is read-only, as configuration changes should normally be done through services instead. Still, the action may need some data from NSO, such as an IP address of a device, which you can access by using trans with the ncs.maagic.get_root() function and navigate to the relevant information.

Further details and the format of the arguments can be found in the NSO Python API reference.

The last thing to note in the above action code definition is the use of the decorator @Action.action. Its purpose is to set up the function arguments correctly, so variables such as input and output behave like other Python Maagic objects. This is no different from services, where decorators are required for the same reason.

Services, actions, and other features all rely on callback registration. In Python code, the class responsible for registration derives from the ncs.application.Application. This allows NSO to manage the application code as appropriate, such as starting and stopping in response to NSO events. These events include package load or unload and NSO start or stop events.

While the Python package skeleton names the derived class Main, you can choose a different name if you also update the package-meta-data.xml file accordingly. This file defines a component with the name of the Python class to use:

<ncs-package xmlns="http://tail-f.com/ns/ncs-packages">
  < ... output omitted ... >

  <component>
    <name>main</name>
    <application>
      <python-class-name>dns_config.main.Main</python-class-name>
    </application>
  </component>
</ncs-package>

When starting the package, NSO reads the class name from package-meta-data.xml, starts the Python interpreter, and instantiates a class instance. The base Application class takes care of establishing communication with the NSO process and calling the setup and teardown methods. The two methods are a good place to do application-specific initialization and cleanup, along with any callback registrations you require.

The communication between the application process and NSO happens through a dedicated control socket, as described in the admin guide the section called “IPC ports” in NSO 5.7 Administration Guide . This setup prevents a faulty application to bring down the whole system along with it and enables NSO to support different application environments. In fact, NSO can manage applications written in Java or Erlang in addition to those in Python. If you replace the python-class-name element of a component with java-class-name in the package-meta-data.xml file, NSO will instead try to run the specified Java class in the managed Java VM. If you wanted to, you could implement all of the same services and actions in Java, too.

Regardless of the programming language you use, the high-level approach to automation with NSO does not change, registering and implementing callbacks as part of your network application. Of course, the actual function calls (the API) and other specifics differ for each language. The NSO Python VM, The NSO Java VM, and Embedded Erlang applications, cover the details. Even so, the concepts of actions, services, and YANG modeling remain the same. As you have seen, everything in NSO is ultimately tied to the YANG model, making YANG knowledge such a valuable skill for any NSO developer.