YANG Modules for Service AssuranceHuaweibenoit.claise@huawei.comHuaweijean.quilbeuf@huawei.comNTTSiriusdreef 70-72HoofddorpWT2132Netherlandspaolo@ntt.netTIM S.p.Avia G. Reiss Romoli, 27410148 TorinoItalypaolo2.fasano@telecomitalia.itCisco Systems, Inc.Milpitas (California)United Statestarumuga@cisco.com
OPS
OPSAWG
This document proposes YANG modules for the Service Assurance for Intent-based Networking Architecture.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED",
"MAY", and "OPTIONAL" in this document are to be interpreted as
described in BCP 14
when, and only when, they appear in all capitals, as shown here.
The terms used in this document are defined in
The "Service Assurance for Intent-based Networking Architecture" draft-ietf-opsawg-service-assurance-architecture, specifies the architecture and all of its components for service assurance. This document complements the architecture by providing open interfaces between components. More specifically, the goal is to provide YANG modules for the purpose of service assurance in a format that is:
machine readablevendor independentaugmentable
The main YANG module, ietf-service-assurance, defines objects for assuring network services based on their decomposition into so-called subservices. The subservices are hierarchically organised by dependencies. The subservices, along with the dependencies, constitute an assurance graph. This module should be supported by an agent, able to interact with the devices in order to produce a health status and symptoms for each subservice in the assurance graph.
This module is intended for the following use cases:
Assurance graph configuration:
Subservices: configure a set of subservices to assure, by specifying their types and parameters.
Dependencies: configure the dependencies between the subservices, along with their type.
Assurance telemetry: export the health status of the subservices, along with the observed symptoms.
The second YANG module, ietf-service-assurance-device, extends the ietf-service-assurance module to add support for the subservice DeviceHealthy. Additional subservice types might be added the same way.
The third YANG module, ietf-service-assurance-device, is another example that extends the ietf-service-assurance-device module. This extension adds support for the subservice InterfaceHealthy.
The fourth YANG module, example-service-assurance-device-acme, extends the ietf-service-assurance-device module as an example to add support for the subservice DeviceHealthy, with specifics for the fictional ACME Corporation. Additional vendor-specific parameters might be added the same way.
Finally, the modules ietf-service-assurance-ip-connectivity and ietf-service-assurance-is-is are provided to completely model the example from the SAIN architecture draft .
The following tree diagram
provides an overview of the ietf-service-assurance data model.
The ietf-service-assurance YANG model assumes an identified number of subservices, to be assured independently. A subservice is a feature or a subpart of the network system that a given service instance might depend on. Example of subservices include:
DeviceHealthy: whether a device is healthy, and if not, what are the symptoms. Potential symptoms are "CPU overloaded", "Out of RAM", or "Out of TCAM".
ConnectivityHealthy: given two IP addresses owned by two devices, what is the quality of the connection between them. Potential symptoms are "No route available" or "ECMP Imbalance".
The first example is a subservice representing a subpart of the network system, while the second is a subservice representing a feature of the network, In both cases, these subservices might depend on other subservices, for instance, the connectivity might depend on a subservice representing the routing mechanism and on a subservice representing ECMP.
The status of each subservice contains a list of symptoms. Each symptom is specified by a unique id and contains a health-score-weight (the impact to the health score incurred by this symptom), a label (text describing what the symptom is), and dates and times at which the symptom was detected and stopped being detected. While the unique id is sufficient as an unique key list, the start-date-time second key help sorting and retrieving relevant symptoms.
The assurance of a given service instance can be obtained by composing the assurance of the subservices that it depends on, via the dependency relations.
A subservice declaration MUST provide:
A type: identity inheriting of the base identity for subservice,
An id: string uniquely identifying the subservice among those with the same identity,
One or more parameters, which should be specified in an augmenting model, as described in the next sections.
The type and id uniquely identify a given subservice. They are used to indicate the dependencies. Dependencies have types as well. Two types are specified in the model:
Impacting: such a dependency indicates an impact on the health of the dependent,Informational: such a dependency might explain why the dependent has issues but does not impact its health.
To illustrate the difference between "impacting" and "informational", consider the subservice InterfaceHealthy, representing a network interface. If the device to which the network interface belongs goes down, the network interface will transition to a down state as well. Therefore, the dependency of InterfaceHealthy towards DeviceHealthy is "impacting". On the other hand, as a the dependency towards the ECMPLoad subservice, which checks that the load between ECMP remains ce remains stable throughout time, is only "informational". Indeed, services might be perfectly healthy even if the load distribution between ECMP changed. However, such an instability might be a relevant symptom for diagnosing the root cause of a problem.
Service instances MUST be modeled as a particular type of subservice with two parameters, a type and an instance name. The type is the name of the service defined in the network orchestrator, for instance "point-to-point-l2vpn". The instance name is the name assigned to the particular instance that we are assuring, for instance the name of the customer using that instance.
The "under-maintenance" and "maintenance-contact" flags inhibit the emission of symptoms for that subservice and subservices that depend on them. See Section 3.7 of for a more detailed discussion.
By specifying service instances and their dependencies in terms of subservices, one defines the whole assurance to apply for them. An assurance agent supporting this model should then produce telemetry in return with, for each subservice: a health-status indicating how healthy the subservice is and when the subservice is not healthy, a list of symptoms explaining why the subservice is not healthy.
<CODE BEGINS> file "ietf-service-assurance@2022-01-04.yang"<CODE ENDS>
The following tree diagram
provides an overview of the ietf-service-assurance-device data model.
The following tree diagram
provides an overview of the ietf-service-assurance and ietf-service-assurance-device data models.
As the number of subservices will grow over time, the YANG module is designed to be extensible. A new subservice type requires the precise specifications of its type and expected parameters. Let us illustrate the example of the new DeviceHealthy subservice type. As the name implies, it monitors and reports the device health, along with some symptoms in case of degradation.
For our DeviceHealthy subservice definition, the new identity device-idty is specified, as an inheritance from the base identity for subservices. This indicates to the assurance agent that we are now assuring the health of a device.
The typical parameter for the configuration of the DeviceHealthy subservice is the name of the device that we want to assure. By augmenting the parameter choice from ietf-service-assurance YANG module for the case of the device-idty subservice type, this new parameter is specified.
<CODE BEGINS> file "ietf-service-assurance-device@2021-06-28.yang"<CODE ENDS>
The following tree diagram
provides an overview of the ietf-service-assurance-interface data model.
The following tree diagram
provides an overview of the ietf-service-assurance, ietf-service-assurance-device, and
ietf-service-assurance-interface data models.
For our InterfaceHealthy subservice definition, the new interface-idty is specified, as an inheritance from the base identity for subservices. This indicates to the assurance agent that we are now assuring the health of an interface.
The typical parameters for the configuration of the InterfaceHealthy subservice are the name of the device and, on that specific device, a specific interface. By augmenting the parameter choice from ietf-service-assurance YANG module for the case of the interface-idty subservice type, those two new parameter are specified.
<CODE BEGINS> file "ietf-service-assurance-interface@2021-06-28.yang"<CODE ENDS>
The following tree diagram
provides an overview of the example-service-assurance-device-acme data model.
The following tree diagram
provides an overview of the ietf-service-assurance, ietf-service-assurance-device, and example-service-assurance-device-acme data models.
Under some circumstances, vendor-specific subservice types might be required. As an example of this vendor-specific implementation, this section shows how to augment the ietf-service-assurance-device module to add support for the subservice DeviceHealthy, specific to the ACME Corporation. The new parameter is acme-specific-parameter.
The following tree diagram provides an overview of the ietf-service-assurance-ip-connectivity data model.
To specify the connectivity that we are interested in, we specify
two IP addresses and two devices. The subservice assures that the connectivity between IP address 1 on device 1 and IP address 2 on device 2 is healthy.
The following tree diagram provides an overview of the ietf-service-assurance-is-is data model.
The parameter of this subservice is the name of the IS-IS instance to assure.
The following tree diagram
provides an overview of the ietf-service-assurance, ietf-service-assurance-device, example-service-assurance-device-acme, ietf-service-assurance-ip-connectivity and ietf-service-assurance-is-is data models.
<CODE BEGINS> file "ietf-service-assurance-ip-connectivity@2021-06-28.yang"<CODE ENDS><CODE BEGINS> file "ietf-service-assurance-is-is@2021-06-28.yang"<CODE ENDS>
The base YANG module defined in only defines a single type of subservices that represent service instances.
As explained above, this model is meant to be augmented so that a variety of subservices can be used in the assurance graph.
In this section, we propose some guidelines in order to build theses extensions.
First, the specific subservice must be given an adequate unique short name that will be used to form longer names (e.g. module name, prefix ...) appearing in the YANG module.
The short name identifies the type of subpart of feature that the subservice will represent, for instance if the subservice will assure the health of a network interafce then "interface" is an adequate short name.
If the subservice will assure the IS-IS routing protocol, then "is-is" is an adequate short name.
The short name must be in kebab-case.
In this section, by subservice YANG module, we mean "YANG module that extends ieft-service-assurance in order to define a specific subservice".
For subservice YANG modules vetted by the IETF, the module name should be "ieft-service-assurance-" followed by the short name.
For instance, "ietf-service-assurance-interface" or "ietf-service-assurance-is-is".
For subservice YANG module that are directly provided by vendors, we propose that they use the company in the prefix.
For example, the prefix for the company "acme" would be "acme-assurance-" and the YANG modules would be "acme-assurance-interface", "acme-assurance-is-is", etc.
For subservice YANG modules vetted by the IETF, the module namespace should be "urn:ietf:params:xml:ns:yang:ietf-service-assurance-" followed by the short name.
For instance, "urn:ietf:params:xml:ns:yang:ietf-service-assurance-interface" or "urn:ietf:params:xml:ns:yang:ietf-service-assurance-is-is".
For subservice YANG module that are directly provided by vendors, a similar pattern can be used with the prefix being a namespace controlled by the vendor.
For subservice YANG modules vetted by the IETF, the module prefix should be "service-assurance-" followed by the short name.
For instance, "service-assurance-interface" or "service-assurance-is-is".
For subservice YANG module that are directly provided by vendors, the same pattern can be used provided it does not conflict with an imported prefix.
Each auqment specific to a subservice must define an identity representing the type of subpart or features of the network system that are assured by the subservice.
As required in the "ietf-service-assurance" module (see ), that identity must be based on the "subservice-idty" identity.
For subservice YANG modules vetted by the IETF, the subservice specific identity should be the short name of the subservice followed by "-idty".
For instance, "interface-idty" or "is-is-identity".
For subservice YANG module that are directly provided by vendors, the same pattern can be used.
For subservice YANG modules vetted by the IETF, the parameters specific to the subservice should be placed in a container named "parameters".
That container must be used to augment the "parameter" choice from the module "ietf-service-assurance" (see and that augment must be guarded so that it is effective only for subservice instance whose type is the subservice specific identity from .
For subservice YANG module that are directly provided by vendors, the same pattern can be used.
The YANG module specified in this document defines a schema for data
that is designed to be accessed via network management protocols such
as NETCONF or RESTCONF . The lowest NETCONF layer is the secure transport layer, and the mandatory-to-implement secure transport is Secure Shell (SSH) . The lowest RESTCONF layer is HTTPS, and the mandatory-to-implement secure transport is TLS .
The Network Configuration Access Control Model (NACM)
provides the means to restrict access for particular NETCONF or
RESTCONF users to a preconfigured subset of all available NETCONF or
RESTCONF protocol operations and content.
There are a number of data nodes defined in this YANG module that are writable/
creatable/deletable (i.e., config true, which is the default). These data nodes may be considered sensitive or vulnerable in some network environments. Write operations (e.g., edit-config) to these data nodes without proper protection can have a negative effect on network operations. These are the subtrees and data nodes and their sensitivity/vulnerability:
/subservices/subservice/type/subservices/subservice/id/subservices/subservice/under-maintenance/subservices/subservice/maintenance-contactThis document registers two URIs in the IETF XML
registry . Following the format in
, the following registrations are
requested:This document registers three YANG modules in the
YANG Module Names registry .
Following the format in , the
the following registrations are requested:-Nonedraft-claise-opsawg-service-assurance-architectureHuaweiHuaweiTelefonica I+DBell CanadaCisco Systems, Inc.
This section contains examples of YANG instances that conform to the YANG modules.
The validity of these data instances has been checked using yangson.
Yangson requires a YANG library to define the complete model against which the data instance must be validated.
We provide in the JSON library file, named "ietf-service-assurance-library.json", that we used for validation.
We provide below the contents of the file "example_configuration_instance.json" which contains the configuration data that models the Figure 2 of .
The instance can be validated with yangson by using the invocation "yangson -v example_configuration_instance.json ietf-service-assurance-library.json", assuming all the files (YANG and JSON) defined in this draft reside in the current folder.
<CODE BEGINS> file "example_configuration_instance.json"<CODE ENDS>
This section provides the JSON encoding of the YANG library listing all modules defined in this draft and their dependencies.
This library can be used to validate data instances using yangson, as explained in the previous section.
<CODE BEGINS> file "ietf-service-assurance-library.json"<CODE ENDS>v00 - v01
Added needed subservice to model example from architecture draftAdded guideline section for naming modelsAdded data instance examples and validation procedureAdded the "parameters" container in the interface YANG module to correct a bug.The authors would like to thank Jan Lindblad for his help during the design of these YANG modules. The authors would like to thank Stephane Litkowski and Charles Eckel for their reviews.