Nano Services

NSO services are deployed sequentially. Each service aquires a lock, so services will be queued if multiple services are provisioned at once. For this reason, each service should run very fast. You don’t want a service to reach out to an external system via an API call that takes many seconds to return, for example.

A solution to this issue is to use nano services, which use reactive fastman (RFM). In a nano service, you have multiple stages. If a stage is being processed, the system does not have a lock and can continue processing other stages or services. Once that stage is complete, NSO re-evaluates the service and proceeds to the next step. This adds a lot of complexity, but offers a method to do complex tasks such as creating a service that spins up a VM and must wait minutes for it to come online. Without nano services, NSO would be stuck for minutes unable to process any other new service requests.

When using nano services, the stages are defined in “states.” Each state can have a post action which is used for changes that have “side effects.” A side effect means that something has changed outside of NSO, which NSO cannot automatically reverse. An example would be an IP address allocation action from IPAM. NSO cannot inherinetly know about this change and automatically reverse it via the CDB and fastman process. This is a good use-case for an action which should go in a post action. Post actions are outside the scope of fastman and are not executed when using commit dry-run.

States can have preconditions, which are defined using XPATH expressions. In order to transition to that state, the precondition must evaluate to true. A kicker is automatically created for states with unfulfilled preconditions. So if the service runs, and then finds that the next state has a condition which is false, a kicker is created to watch for the condition to become true. Once it does, the kicker re-deploys the service.

An example of a nano service with a state that has a precondition is below. The pre-condition specifies the XPATH to monitor. The nano-callback means that python code is executed once you are running this stage. Every component needs an init state and ready state. The operator-configured loopback-configured state is where the custom options are added. This is wrapped in a plan-outline which controls the overall nano service.

The plan outline belongs to a behavior-tree, which links the plan outline to the service model. These can be convoluted with loops and multiple components.

Converting a python-and-xml package to a nano service

Add identities for the component and service plan to the YANG module:

  identity loopback {
    base ncs:plan-component-type;
  }

  identity loopback-configured {
    base ncs:plan-state;
  }

Add the plan outpline:

  ncs:plan-outline loopback-plan {
    description "Loopback plan";

    ncs:component-type "loopback:loopback" {
      ncs:state "ncs:init";
      ncs:state "loopback:loopback-configured" {
        ncs:create {
          ncs:pre-condition {
            ncs:monitor "/prefix-allocations[name=$SERVICE/name]/ip-prefix";
          }
          ncs:nano-callback;
        }
      }
      ncs:state "ncs:ready";
    }
  }

Add the behavior tree. Make sure the name of the behavior-tree matches the servicepoint.

  ncs:service-behavior-tree loopback-service {
    description "Loopback behavior tree";
    ncs:plan-outline-ref "loopback:loopback-plan";
    ncs:selector {      
      ncs:create-component "'loopback'" {
        ncs:component-type-ref "loopback:loopback";
      }
    }
  }

Add uses ncs:nano-plan-data; to the list.

    list loopback {
        key name;

        uses ncs:service-data;
        uses ncs:nano-plan-data;
        ncs:servicepoint "loopback-service";

        leaf name {
            tailf:cli-allow-range;
            tailf:info "Service instance name";
            type string;
        }

In the python code, change the Service references to NanoService and use cb_nano_create instead of cb_create. Also change self.register_service to self.register_nano_service. Additionally there are several more paramenters to include in these functions.

import ncs
import ipaddress
from ncs.application import NanoService


class ServiceCallbacks(NanoService):
    @NanoService.create
    def cb_nano_create(self, tctx, root, service, plan, component, state, proplist, component_proplist):
        self.log.info('NanoService create(service=', service._path, ')')

        ip_prefix = root.prefix_allocations[service.name].ip_prefix
        self.log.debug(f'Value of ip-prefix leaf is {ip_prefix}')
        net = ipaddress.IPv4Network(ip_prefix)
        ip_address = next(net.hosts())

        vars = ncs.template.Variables()
        vars.add('IP_ADDRESS', ip_address)
        template = ncs.template.Template(service)
        template.apply('loopback-template', vars)

        
# ---------------------------------------------
# COMPONENT THREAD THAT WILL BE STARTED BY NCS.
# ---------------------------------------------
class Loopback(ncs.application.Application):
    def setup(self):
        # The application class sets up logging for us. It is accessible
        # through 'self.log' and is a ncs.log.Log instance.
        self.log.info('Loopback RUNNING')

        # Service callbacks require a registration for a 'service point',
        # as specified in the corresponding data model.
        #
        self.register_nano_service('loopback', 'loopback:loopback', 'loopback:loopback-configured', ServiceCallbacks)