rfc9418xml2.original.xml   rfc9418.xml 
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [ <!DOCTYPE rfc [
<!ENTITY nbsp "&#160;">
<!ENTITY zwsp "&#8203;">
<!ENTITY nbhy "&#8209;">
<!ENTITY wj "&#8288;">
]> ]>
<?xml-stylesheet type="text/xsl" href="rfc2629.xslt" ?>
<?rfc toc="yes"?> <rfc xmlns:xi="http://www.w3.org/2001/XInclude" submissionType="IETF" category="
<?rfc tocompact="yes"?> std" consensus="true" ipr="trust200902" docName="draft-ietf-opsawg-service-assur
<?rfc tocdepth="4"?> ance-yang-11" number="9418" obsoletes="" updates="" xml:lang="en" tocInclude="tr
<?rfc tocindent="yes"?> ue" tocDepth="4"
<?rfc symrefs="yes"?> symRefs="true" sortRefs="true" version="3">
<?rfc sortrefs="yes"?>
<?rfc comments="yes"?> <!-- xml2rfc v2v3 conversion 3.16.0 -->
<?rfc inline="yes"?>
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<rfc category="std" ipr="trust200902" docName="draft-ietf-opsawg-service-assuran
ce-yang-11">
<front> <front>
<title abbrev="YANG Modules for Service Assurance">YANG Modules for Service <title abbrev="A YANG Data Model for Service Assurance">A YANG Data Model fo
Assurance</title> r Service Assurance</title>
<seriesInfo name="RFC" value="9418"/>
<author fullname="Benoit Claise" initials="B" surname="Claise"> <author fullname="Benoit Claise" initials="B" surname="Claise">
<organization>Huawei</organization> <organization>Huawei</organization>
<address> <address>
<postal> <postal>
<street></street> <street/>
<city></city> <city/>
<country></country> <country/>
</postal> </postal>
<email>benoit.claise@huawei.com</email> <email>benoit.claise@huawei.com</email>
</address> </address>
</author> </author>
<author fullname="Jean Quilbeuf" initials="J" surname="Quilbeuf "> <author fullname="Jean Quilbeuf" initials="J" surname="Quilbeuf ">
<organization>Huawei</organization> <organization>Huawei</organization>
<address> <address>
<email>jean.quilbeuf@huawei.com</email> <email>jean.quilbeuf@huawei.com</email>
</address> </address>
</author> </author>
<author fullname="Paolo Lucente" initials="P." surname="Lucente"> <author fullname="Paolo Lucente" initials="P." surname="Lucente">
<organization>NTT</organization> <organization>NTT</organization>
<address> <address>
<postal> <postal>
<street>Siriusdreef 70-72</street> <street>Siriusdreef 70-72</street>
<city>Hoofddorp</city> <city>Hoofddorp</city>
<region>WT</region>
<code>2132</code> <code>2132</code>
<country>Netherlands</country> <country>Netherlands</country>
</postal> </postal>
<email>paolo@ntt.net</email> <email>paolo@ntt.net</email>
</address> </address>
</author> </author>
<author fullname="Paolo Fasano" initials="P" surname="Fasano"> <author fullname="Paolo Fasano" initials="P" surname="Fasano">
<organization>TIM S.p.A</organization> <organization>TIM S.p.A</organization>
<address> <address>
<postal> <postal>
<street>via G. Reiss Romoli, 274</street> <street>via G. Reiss Romoli, 274</street>
<city>10148 Torino</city> <city>Torino</city>
<code>10148</code>
<country>Italy</country> <country>Italy</country>
</postal> </postal>
<email>paolo2.fasano@telecomitalia.it</email> <email>paolo2.fasano@telecomitalia.it</email>
</address> </address>
</author> </author>
<author fullname="Thangam Arumugam" initials="T" surname="Arumugam"> <author fullname="Thangam Arumugam" initials="T" surname="Arumugam">
<organization>Cisco Systems, Inc.</organization> <organization>Consultant</organization>
<address> <address>
<postal> <postal>
<street></street> <street/>
<city>Milpitas (California)</city> <city>Milpitas</city>
<country>United States</country> <region>California</region>
<country>United States of America</country>
</postal> </postal>
<email>tarumuga@cisco.com</email> <email>thangavelu@yahoo.com</email>
</address> </address>
</author> </author>
<date/> <date year="2023" month="June" />
<area>OPS</area> <area>ops</area>
<workgroup>OPSAWG</workgroup> <workgroup>opsawg</workgroup>
<keyword>health</keyword>
<keyword>SAIN</keyword>
<keyword>subservice</keyword>
<keyword>symptom</keyword>
<keyword>telemetry</keyword>
<abstract> <abstract>
<t> <t>
This document specifies YANG modules for representing assurance graphs. This document specifies YANG modules for representing assurance graphs.
These graphs represent the assurance of a given service by decomposing i t into atomic assurance elements called subservices. These graphs represent the assurance of a given service by decomposing i t into atomic assurance elements called subservices.
A companion document, Service Assurance for Intent-based Networking Arch itecture, presents an architecture for implementing the assurance of such servic es. The companion document, "Service Assurance for Intent-Based Networking A rchitecture" (RFC 9417), presents an architecture for implementing the assurance of such services.
</t> </t>
<t> <t>
The YANG data models in this document conforms to the Network Management Datastore Architecture (NMDA) defined in RFC 8342. The YANG data models in this document conform to the Network Management Datastore Architecture (NMDA) defined in RFC 8342.
</t> </t>
</abstract> </abstract>
</front> </front>
<middle> <middle>
<section anchor="intro" title="Introduction"> <section anchor="intro" numbered="true" toc="default">
<name>Introduction</name>
<t> <t>
<xref target="I-D.ietf-opsawg-service-assurance-architecture"/> describe s an architecture and a set of involved components for service assurance, called Service Assurance for Intent-Based Networking (SAIN). <xref target="RFC9417" format="default"/> describes an architecture and a set of involved components for service assurance, called Service Assurance for Intent-based Networking (SAIN).
This document complements the architecture by specifying a data model fo r the interfaces between components. This document complements the architecture by specifying a data model fo r the interfaces between components.
More specifically, the document provides YANG modules for the purpose of service assurance in a format that is: More specifically, the document provides YANG modules for the purpose of service assurance in a format that is:
<list style="symbols">
<t>machine-readable</t>
<t>vendor independent</t>
<t>augmentable such that SAIN agents from Figure 1 of <xref target="I-
D.ietf-opsawg-service-assurance-architecture"/> can support and expose new subse
rvices to SAIN orchestrators and collectors.</t>
</list>
</t> </t>
<section title="Terminology" anchor="terminology"> <ul spacing="normal">
<t> <li>machine readable,</li>
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL <li>vendor independent, and</li>
NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", <li>augmentable such that SAIN agents from Figure 1 of <xref target="RFC
"MAY", and "OPTIONAL" in this document are to be interpreted as 9417" format="default"/> can support and expose new subservices to SAIN orchestr
described in BCP 14 <xref target="RFC2119"/> <xref target="RFC8174" ators and collectors.</li>
/> </ul>
when, and only when, they appear in all capitals, as shown here. <section anchor="terminology" numbered="true" toc="default">
</t> <name>Terminology</name>
<t> <t>
The terms used in this document are defined in <xref target="I-D.ie The key words "<bcp14>MUST</bcp14>", "<bcp14>MUST NOT</bcp14>", "<bcp14>REQU
tf-opsawg-service-assurance-architecture"/>. IRED</bcp14>", "<bcp14>SHALL</bcp14>", "<bcp14>SHALL
</t> NOT</bcp14>", "<bcp14>SHOULD</bcp14>", "<bcp14>SHOULD NOT</bcp14>", "<bcp14>
<t> RECOMMENDED</bcp14>", "<bcp14>NOT RECOMMENDED</bcp14>",
The meanings of the symbols in the tree diagrams are defined in <xre "<bcp14>MAY</bcp14>", and "<bcp14>OPTIONAL</bcp14>" in this document are to
f target="RFC8340"/>. be interpreted as
</t> described in BCP&nbsp;14 <xref target="RFC2119"/> <xref target="RFC8174"/>
</section> when, and only when, they appear in all capitals, as shown here.
</t>
<t>
The terms used in this document are defined in <xref target="RFC941
7" format="default"/>.
</t>
<t>
The meanings of the symbols in the tree diagrams are defined in <xre
f target="RFC8340" format="default"/>.
</t>
</section>
</section> </section>
<section anchor="capability_model" title="YANG Modules Overview"> <section anchor="capability_model" numbered="true" toc="default">
<name>YANG Modules Overview</name>
<t> <t>
The main YANG module, "ietf-service-assurance" (<xref target="main-modu le"/>), defines objects for assuring network services based on their decompositi on into so-called subservices. The main YANG module, "ietf-service-assurance" (<xref target="main-modu le" format="default"/>), defines objects for assuring network services based on their decomposition into so-called subservices.
The subservices are hierarchically organized by dependencies. The subservices are hierarchically organized by dependencies.
The subservices, along with the dependencies, constitute an assurance gr aph. The subservices, along with the dependencies, constitute an assurance gr aph.
This module should be supported by an agent, able to interact with the d evices in order to produce a health status and symptoms for each subservice in a n assurance graph. This module should be supported by an agent that is able to interact wit h the devices in order to produce the health statuses and symptoms for each subs ervice in an assurance graph.
This module is intended for the following use cases: This module is intended for the following use cases:
<list style="symbols"> </t>
<ul spacing="normal">
<li>
<t> <t>
Assurance graph configuration: Assurance graph configuration:
<list style="symbols">
<t>
Subservices: configure a set of subservices to assure, by specif
ying their types and parameters.
</t>
<t>
Dependencies: configure the dependencies between the subservices
, along with their type.
</t>
</list>
</t>
<t>
Assurance telemetry: export the assurance graph with health status a
nd symptoms for each node.
</t> </t>
</list> <ul spacing="normal">
The module is also intended to be exported by the SAIN collector which a <li>
ggregates the output of several SAIN agents to provide the global assurance grap Subservices: Configure a set of subservices to assure by specify
h. ing their types and parameters.
</li>
<li>
Dependencies: Configure the dependencies between the subservices
, along with their types.
</li>
</ul>
</li>
<li>
Assurance telemetry: Export the assurance graph with health statuses
and symptoms for each node.
</li>
</ul>
<t>
The module is also intended to be exported by the SAIN collector that ag
gregates the output of several SAIN agents to provide the global assurance graph
.
In that case, only the telemetry export use case is considered. In that case, only the telemetry export use case is considered.
</t> </t>
<t> <t>
The modules presented in this document conform to the Network Managemen t Datastore Architecture defined in <xref target="RFC8342"/>. The modules presented in this document conform to the Network Managemen t Datastore Architecture (NMDA) defined in <xref target="RFC8342" format="defaul t"/>.
</t> </t>
<t> <t>
The second YANG module, "ietf-service-assurance-device" (<xref target="d evice-module"/>), augments the "ietf-service-assurance" module by adding support for the device subservice. The second YANG module, "ietf-service-assurance-device" (<xref target="d evice-module" format="default"/>), augments the "ietf-service-assurance" module by adding support for the device subservice.
Additional subservice types might be added following a similar approach. Additional subservice types might be added following a similar approach.
</t> </t>
<t> <t>
The third YANG module, "ietf-service-assurance-interface" (<xref target= "interface-module"/>), augments the "ietf-service-assurance" module as well, by adding support for the interface subservice. The third YANG module, "ietf-service-assurance-interface" (<xref target= "interface-module" format="default"/>), augments the "ietf-service-assurance" mo dule as well by adding support for the interface subservice.
</t> </t>
<t> <t>
We provide additional examples in the appendix. We provide additional examples in the appendix.
The module "example-service-assurance-device-acme" (<xref target="acme-d evice-module"/>) augments the "ietf-service-assurance-device" module to customiz e it for devices of the fictional ACME Corporation. The module "example-service-assurance-device-acme" (<xref target="acme-d evice-module" format="default"/>) augments the "ietf-service-assurance-device" m odule to customize it for devices of the fictional Acme Corporation.
Additional vendor-specific parameters might be added following a similar approach. Additional vendor-specific parameters might be added following a similar approach.
We also provide the modules "example-service-assurance-ip-connectivity" and "example-service-assurance-is-is" (<xref target="ip-connectivity-is-is"/>) t o model the example in Figure 2 from Section 3.1 of <xref target="I-D.ietf-opsaw g-service-assurance-architecture"/>. We also provide the modules "example-service-assurance-ip-connectivity" and "example-service-assurance-is-is" (<xref target="ip-connectivity-is-is" form at="default"/>) to model the example in Figure 2 from <xref target="RFC9417" sec tion="3.1" sectionFormat="of" format="default"/>.
</t> </t>
</section> </section>
<section anchor="main-module" numbered="true" toc="default">
<section title="Base IETF Service Assurance YANG Module" anchor="main-module <name>Base IETF Service Assurance YANG Module</name>
"> <section anchor="ietf-service-assurance-concepts" numbered="true" toc="def
<section title="Concepts" anchor="ietf-service-assurance-concepts"> ault">
<name>Concepts</name>
<t> <t>
The "ietf-service-assurance" YANG module assumes a set of subservices, The "ietf-service-assurance" YANG module assumes a set of subservices
to be assured independently. to be assured independently.
A subservice is a feature or a subpart of the network system that a gi A subservice is a feature or a subpart of the network system that a gi
ven service instance depends on. Examples of subservice types include: ven service instance depends on. Examples of subservice types include the follow
<list style="symbols"> ing:
<t> </t>
device: whether a device is healthy, and if not, what are the symp <ul spacing="normal">
toms. <li>
Such a subservice might monitor the device resources such as CPU, device: Whether a device is healthy, and if not, what are the symp
RAM or Ternary Content-Addressable Memory (TCAM). toms?
Such a subservice might monitor the device resources, such as CPU,
RAM, or Ternary Content-Addressable Memory (TCAM).
Potential symptoms are "CPU overloaded", "Out of RAM", or "Out of TCAM". Potential symptoms are "CPU overloaded", "Out of RAM", or "Out of TCAM".
</t> </li>
<t> <li>
ip-connectivity: given two IP addresses bound to two devices, what ip-connectivity: Given two IP addresses bound to two devices, what
is the quality of the IP connectivity between them. is the quality of the IP connectivity between them?
Potential symptoms are "No route available" or "Equal Cost Multipl Potential symptoms are "No route available" or "Equal-Cost Multipa
e Paths (ECMP) Imbalance". ths (ECMPs) imbalance".
</t> </li>
</list> </ul>
<t>
An instance of the device subservice is representing a subpart of the network system, namely a specific device. An instance of the device subservice is representing a subpart of the network system, namely a specific device.
An instance of the ip-connectivity subservice representing a feature o An instance of the ip-connectivity subservice is representing a featur
f the network, namely the connectivity between two specific IP addresses on two e of the network, namely the connectivity between two specific IP addresses on t
devices. wo devices.
In both cases, these subservices might depend on other subservices, fo In both cases, these subservices might depend on other subservices, fo
r instance, the connectivity might depend on a subservice representing the routi r instance, the connectivity might depend on a subservice representing the routi
ng system and on a subservice representing ECMP. ng system and on a subservice representing ECMPs.
</t> </t>
<t> <t>
The two example subservices presented above need different sets of par ameters to fully characterize one of their instance. The two example subservices presented above need different sets of par ameters to fully characterize one of their instances.
An instance of the device subservice is fully characterized by a singl e parameter allowing to identify the device to monitor. An instance of the device subservice is fully characterized by a singl e parameter allowing to identify the device to monitor.
For ip-connectivity subservice, at least the device and IP address for both ends of the link are needed to fully characterize an instance. For the ip-connectivity subservice, at least the device and IP address for both ends of the link are needed to fully characterize an instance.
</t> </t>
<t> <t>
The base model presented in this section specifies a single type of su bservice, which represents service instances. The base model presented in this section specifies a single type of su bservice, which represents service instances.
Such nodes play a particular role in the assurance graph because they represent the starting point, or root, for the assurance graph of the correspond ing service instance. Such nodes play a particular role in the assurance graph because they represent the starting point, or root, for the assurance graph of the correspond ing service instance.
The parameters required to fully identify a service instance are the n ame of the service and the name of the service instance. The parameters required to fully identify a service instance are the n ame of the service and the name of the service instance.
To support other types of subservice such as 'device' or 'ip-connectiv ity', the "ietf-service-assurance" module is intended to be augmented. To support other types of subservices, such as device or ip-connectivi ty, the "ietf-service-assurance" module is intended to be augmented.
</t> </t>
<t> <t>
The dependencies are modelled as a list: each subservice contains a li st of references to its dependencies. The dependencies are modeled as a list, i.e., each subservice contains a list of references to its dependencies.
That list can be empty if the subservice instance does not have any de pendencies. That list can be empty if the subservice instance does not have any de pendencies.
</t> </t>
<t> <t>
By specifying service instances and their dependencies in terms of sub services, one defines a global assurance graph. By specifying service instances and their dependencies in terms of sub services, one defines a global assurance graph.
That assurance graph is the result of merging all the individual assur ance graphs for the assured service instances. That assurance graph is the result of merging all the individual assur ance graphs for the assured service instances.
Each subservice instance is expected to appear only one in the global Each subservice instance is expected to appear only once in the global
assurance graph even if several service instances depend on it. assurance graph even if several service instances depend on it.
For example, an instance of the device subservice is a dependency of e For example, an instance of the device subservice is a dependency of e
very service instance that rely on the corresponding device. very service instance that relies on the corresponding device.
The assurance graph of a specific service instance is the subgraph obt The assurance graph of a specific service instance is the subgraph obt
ained by traversing the global assurance graph through the dependencies starting ained by traversing the global assurance graph through the dependencies, startin
from the specific service instance. g from the specific service instance.
</t> </t>
<t> <t>
An assurance agent configured with such a graph is expected to produce An assurance agent configured with such a graph is expected to produce
, for each configured subservice: , for each configured subservice,
a health-status indicating how healthy the subservice is a health status that indicates how healthy the subservice is.
and when the subservice is not healthy, a list of symptoms explaining If the the subservice is not healthy, the agent is expected to
why the subservice is not healthy. produce a list of symptoms explaining why the subservice is not healthy.
</t> </t>
<!-- <t>
A symptom raised by an agent will need to be interpreted outside of th
e scope of the agent, as the result of several agents needs to be collected in o
rder to have a complete graph.
We use a pair of identifiers to fully identify a symptom: the agent id
entifier and the symptom identifier.
Each agent MUST have a unique id within the system.
Each symptom MUST have a unique id within the agent.
A list mapping agent-id and symptom-id to their description is include
d in the model and must provide the description for every symptom raised in the
assurance graph.
</t> -->
</section> </section>
<section title="Tree View" anchor="ietf-service-assurance-tree-view"> <section anchor="ietf-service-assurance-tree-view" numbered="true" toc="de
fault">
<name>Tree View</name>
<t> <t>
The following tree diagram <xref target="RFC8340"/> The following tree diagram <xref target="RFC8340" format="default"/>
provides an overview of the "ietf-service-assurance" module. provides an overview of the "ietf-service-assurance" module.
</t> </t>
<t> <sourcecode type="yangtree"><![CDATA[
<figure>
<artwork><![CDATA[
module: ietf-service-assurance module: ietf-service-assurance
+--ro assurance-graph-last-change yang:date-and-time +--ro assurance-graph-last-change yang:date-and-time
+--rw subservices +--rw subservices
| +--rw subservice* [type id] | +--rw subservice* [type id]
| +--rw type identityref | +--rw type identityref
| +--rw id string | +--rw id string
| +--ro last-change? yang:date-and-time | +--ro last-change? yang:date-and-time
| +--ro label? string | +--ro label? string
| +--rw under-maintenance! | +--rw under-maintenance!
| | +--rw contact string | | +--rw contact string
skipping to change at line 265 skipping to change at line 272
| +--ro id string | +--ro id string
| +--ro description string | +--ro description string
+--ro assured-services +--ro assured-services
+--ro assured-service* [service] +--ro assured-service* [service]
+--ro service leafref +--ro service leafref
+--ro instances* [name] +--ro instances* [name]
+--ro name leafref +--ro name leafref
+--ro subservices* [type id] +--ro subservices* [type id]
+--ro type -> /subservices/subservice/type +--ro type -> /subservices/subservice/type
+--ro id leafref +--ro id leafref
]]></sourcecode>
]]></artwork>
</figure>
</t>
<t> <t>
The date of last change "assurance-graph-last-change" is read only. The date of the last change in "assurance-graph-last-change" is read o
It must be updated each time the graph structure is changed by additio nly.
n or deletion of subservices, dependencies or modification of their configurable It must be updated each time the graph structure is changed by additio
attributes, including their maintenance status. n or deletion of subservices and dependencies or modifications of their configur
able attributes, including their maintenance statuses.
Such modifications correspond to a structural change in the graph. Such modifications correspond to a structural change in the graph.
The date of last change is useful for a client to quickly check if the The date of the last change is useful for a client to quickly check if
re is a need to update the graph structure. there is a need to update the graph structure.
A change in the health-score or symptoms associated to a service or su A change in the health score or symptoms associated to a service or su
bservice does not change the structure of the graph and thus has no effect on th bservice does not change the structure of the graph, and thus has no effect on t
e date of last change. he date of the last change.
</t> </t>
<t> <t>
The "subservice" list contains all the subservice instances currently The "subservices" list contains all the subservice instances currently
known by the server (i.e. SAIN agent or SAIN collector). known by the server (i.e., SAIN agent or SAIN collector).
A subservice declaration MUST provide: A subservice declaration <bcp14>MUST</bcp14> provide the following:
<list style="symbols"> </t>
<t> <ul spacing="normal">
A subservice type ("type"): reference to an identity that inherits
from "subservice-base", which is the base identity for any subservice type. <li>
</t> a subservice type ("type"): a reference to an identity that inheri
<t> ts from "subservice-base", which is the base identity for any subservice type
An id ("id"): string uniquely identifying the subservice among tho </li>
se with the same type, <li>
</t> an id ("id"): a string uniquely identifying the subservice among t
</list> hose with the same type
</li>
</ul>
<t>
The type and id uniquely identify a given subservice. The type and id uniquely identify a given subservice.
</t> </t>
<t> <t>
The "last-change" indicates when the dependencies or maintenance sta tus of this particular subservice were last modified. The "last-change" indicates when the dependencies or maintenance sta tus of this particular subservice were last modified.
</t> </t>
<t> <t>
The "label" is a human-readable description of the subservice. The "label" is a human-readable description of the subservice.
</t> </t>
<t> <t>
The presence of "under-maintenance" container inhibits the emission of The presence of the "under-maintenance" container inhibits the emissio
symptoms for that subservice and subservices that depend on them. n of symptoms for the subservice and subservices that depend on them.
In that case, a "contact" MUST be provided to indicate who or which so In that case, a "contact" <bcp14>MUST</bcp14> be provided to indicate
ftware is responsible for the maintenance. who or which software is responsible for the maintenance.
See Section 3.6 of <xref target="I-D.ietf-opsawg-service-assurance-arc See <xref target="RFC9417" section="3.6" sectionFormat="of" format="de
hitecture"/> for a more detailed discussion. fault"/> for a more detailed discussion.
</t> </t>
<t> <t>
The "parameter" choice is intended to be augmented in order to describ e parameters that are specific to the current subservice type. The "parameter" choice is intended to be augmented in order to describ e parameters that are specific to the current subservice type.
This base module defines only the subservice type representing service instances. This base module defines only the subservice type representing service instances.
Service instances MUST be modeled as a particular type of subservice w Service instances <bcp14>MUST</bcp14> be modeled as a particular type
ith two parameters, "service" and "instance-name". of subservice with two parameters: "service" and "instance-name".
The "service" parameter is the name of the service defined in the netw The "service" parameter is the name of the service defined in the netw
ork orchestrator, for instance "point-to-point-l2vpn". ork orchestrator, for instance, "point-to-point-l2vpn".
The "instance-name" parameter is the name assigned to the particular i The "instance-name" parameter is the name assigned to the particular i
nstance to be assured, for instance the name of the customer using that instance nstance to be assured, for instance, the name of the customer using that instanc
. e.
</t> </t>
<t> <t>
The "health-score" contains a value normally between 0 and 100 indicat The "health-score" contains a value normally between 0 and 100, indica
ing how healthy the subservice is. ting how healthy the subservice is.
As mentioned in the health-score definition, the special value -1 can As mentioned in the health score definition, the special value -1 can
be used to specify that no value could be computed for that health-score, for in be used to specify that no value could be computed for that health score, for in
stance if some metric needed for that computation could not be collected. stance, if some metric needed for that computation could not be collected.
</t> </t>
<t> <t>
The "symptoms-history-start" is the cutoff date for reporting symptoms . The "symptoms-history-start" is the cutoff date for reporting symptoms .
Symptoms that were terminated before that date are not reported anymor e in the model. Symptoms that were terminated before that date are not reported anymor e in the model.
</t> </t>
<t> <t>
The status of each subservice contains a list of symptoms. The status of each subservice contains a list of symptoms.
Each symptom is specified by Each symptom is specified by:
<list style="symbols"> </t>
<t> an identifier "symptom-id" which identifies the symptom locally <ul spacing="normal">
to an agent, </t> <li> an identifier "symptom-id", which identifies the symptom locally
<t> an agent identifier "agent-id" which identifies the agent raisi to an agent, </li>
ng the symptom,</t> <li> an agent identifier "agent-id", which identifies the agent raisin
<t> a "health-score-weight" specifying the impact to the health sc g the symptom,</li>
ore incurred by this symptom,</t> <li> a "health-score-weight" specifying the impact to the health scor
<t> a "start-date-time" indicating when the symptom became active a e incurred by this symptom,</li>
nd </t> <li> a "start-date-time" indicating when the symptom became active, an
<t> a "stop-date-time" indicating when the symptom stopped being ac d</li>
tive, that field is not present if the symptom is still active.</t> <li> a "stop-date-time" indicating when the symptom stopped being acti
</list> ve (this field is not present if the symptom is still active).</li>
</ul>
<t>
In order for the pair "agent-id" and "symptom-id" to uniquely identify a symptom, the following is necessary: In order for the pair "agent-id" and "symptom-id" to uniquely identify a symptom, the following is necessary:
<list style="symbols"> </t>
<t> The "agent-id" MUST be unique among all agents of the system </ <ul spacing="normal">
t> <li> "agent-id" <bcp14>MUST</bcp14> be unique among all agents of the
<t> The "symptom-id" MUST be unique among all symptoms raised by th system. </li>
e agent </t> <li> "symptom-id" <bcp14>MUST</bcp14> be unique among all symptoms rai
</list> sed by the agent. </li>
</ul>
<t>
Note that "agent-id" and "symptom-id" are leafrefs pointing to the obj ects defined later in the document. Note that "agent-id" and "symptom-id" are leafrefs pointing to the obj ects defined later in the document.
While the combination of "symptom-id" and "agent-id" is sufficient as a unique key list, the "start-date-time" second key helps to sort and retrieve r elevant symptoms. While the combination of "symptom-id" and "agent-id" is sufficient as a unique key list, the "start-date-time" second key helps to sort and retrieve r elevant symptoms.
</t> </t>
<t> <t>
The "dependency" list contains the dependencies for the current subser vice. The "dependency" list contains the dependencies for the current subser vice.
Each of them is specified by a leafref to both "type" and "id" of the target dependencies. Each of them is specified by a leafref to both "type" and "id" of the target dependencies.
A dependency has a type indicated in the "dependency-type" field. Two types are specified in the model: A dependency has a type indicated in the "dependency-type" field. Two types are specified in the model:
<list style="symbols"> </t>
<t>Impacting: such a dependency indicates an impact on the health of <ul spacing="normal">
the dependent,</t> <li>Impacting: Such a dependency indicates an impact on the health of
<t>Informational: such a dependency might explain why the dependent the dependent.</li>
has issues but does not impact its health.</t> <li>Informational: Such a dependency might explain why the dependent h
</list> as issues but does not impact its health.</li>
To illustrate the difference between "impacting" and "informational", </ul>
consider the interface subservice, representing a network interface. <t>
To illustrate the difference between "impacting" and "informational",
consider the interface subservice representing a network interface.
If the device to which the network interface belongs goes down, the ne twork interface will transition to a "down" state as well. If the device to which the network interface belongs goes down, the ne twork interface will transition to a "down" state as well.
Therefore, the dependency of the interface subservice towards the devi ce subservice is "impacting". Therefore, the dependency of the interface subservice towards the devi ce subservice is "impacting".
On the other hand, a dependency towards the ecmp-load subservice, whic On the other hand, a dependency towards the ecmp-load subservice, whic
h checks that the load between ECMP remains stable throughout time, is only "inf h checks that the load between ECMPs remains stable throughout time, is only "in
ormational". formational".
Indeed, services might be perfectly healthy even if the load distribut Indeed, services might be perfectly healthy even if the load distribut
ion between ECMP changed. ion between ECMPs changed.
However, such an instability might be a relevant symptom for diagnosin g the root cause of a problem. However, such an instability might be a relevant symptom for diagnosin g the root cause of a problem.
</t> </t>
<t> <t>
Within the container "agents", the list "agent" contains the list of s ymptoms per agent. Within the container "agents", the list "agent" contains the list of s ymptoms per agent.
The key of the list is the "id", which MUST be unique among agents of a given assurance system. The key of the list is the "id", which <bcp14>MUST</bcp14> be unique a mong agents of a given assurance system.
For each agent, the list "symptoms-description" maps an "id" to its "d escription". For each agent, the list "symptoms-description" maps an "id" to its "d escription".
The "id" MUST be unique among the symptoms raised by the agent. The "id" <bcp14>MUST</bcp14> be unique among the symptoms raised by th e agent.
</t> </t>
<t> <t>
Within the container "assured-services", the list "assured-service" co ntains the subservices indexed by assured service instances. Within the container "assured-services", the list "assured-service" co ntains the subservices indexed by assured service instances.
For each service type, identified by the "service" leaf, all instances For each service type identified by the "service" leaf, all instances
of that service are listed in the "instances" list. of that service are listed in the "instances" list.
For each instance, identified by the "name" leaf, the "subservices" l For each instance identified by the "name" leaf, the "subservices" li
ist contains all descendant subservices that are part of the assurance graph for st contains all descendant subservices that are part of the assurance graph for
that specific instance. that specific instance.
These imbricated lists provide a query optimization to get the list of These imbricated lists provide a query optimization to get the list of
subservices in that assurance graph in a single query, instead of recursively q subservices in that assurance graph in a single query instead of recursively qu
uerying the dependencies of each subservice, starting from the node representing erying the dependencies of each subservice, starting from the node representing
the service instance. the service instance.
</t> </t>
<t> <t>
The relation between the health score ("health-score") and the health- score-weight of the currently active symptoms is not explicitly defined in this document. The relation between the health score ("health-score") and the "health -score-weight" of the currently active symptoms is not explicitly defined in thi s document.
The only requirement is that a health score that is strictly smaller t han 100 (the maximal value) must be explained by at least one symptom. The only requirement is that a health score that is strictly smaller t han 100 (the maximal value) must be explained by at least one symptom.
A way to enforce that requirement is to first detect symptoms and then A way to enforce that requirement is to first detect symptoms and then
compute the health score based on the health-score-weight of the detected sympt compute the health score based on the "health-score-weight" of the detected sym
oms. ptoms.
As an example, such a computation could be to sum the health-score-wei As an example, such a computation could be to sum the "health-score-we
ght of the active symptoms, subtract that value from 100 and change the value to ight" of the active symptoms, subtract that value from 100, and change the value
0 if negative. to 0 if the result is negative.
The relation between health-score and health-score-weight is left to t The relation between health score and "health-score-weight" is left to
he implementor (of an agent <xref target="I-D.ietf-opsawg-service-assurance-arch the implementor (of an agent <xref target="RFC9417" format="default"/>).
itecture"/>).
</t> </t>
<t> <t>
Keeping the history of the graph structure is out of scope for this YA NG module. Keeping the history of the graph structure is out of scope for this YA NG module.
Only the current version of the assurance graph can be fetched. Only the current version of the assurance graph can be fetched.
In order to keep the history of the graph structure, some time-series database (TSDB) or similar storage must be used. In order to keep the history of the graph structure, some time-series database (TSDB) or similar storage must be used.
</t> </t>
</section> </section>
<section anchor="ietf-service-assurance-yang-model" numbered="true" toc="d
<section title="YANG Module" anchor="ietf-service-assurance-yang-model"> efault">
<t>&lt;CODE BEGINS> file "ietf-service-assurance@2022-08-10.yang"</t> <name>YANG Module</name>
<figure> <t> This model contains references to <xref target="RFC6991"/>. </t>
<artwork><![CDATA[ <sourcecode name="ietf-service-assurance@2023-06-02.yang" type="yang" ma
rkers="true"><![CDATA[
module ietf-service-assurance { module ietf-service-assurance {
yang-version 1.1; yang-version 1.1;
namespace "urn:ietf:params:xml:ns:yang:ietf-service-assurance"; namespace "urn:ietf:params:xml:ns:yang:ietf-service-assurance";
prefix sain; prefix sain;
import ietf-yang-types { import ietf-yang-types {
prefix yang; prefix yang;
reference reference
"RFC 6991: Common YANG Data Types"; "RFC 6991: Common YANG Data Types";
} }
organization organization
"IETF OPSAWG Working Group"; "IETF OPSAWG Working Group";
contact contact
"WG Web: <https://datatracker.ietf.org/wg/opsawg/> "WG Web: <https://datatracker.ietf.org/wg/opsawg/>
WG List: <mailto:opsawg@ietf.org> WG List: <mailto:opsawg@ietf.org>
Author: Benoit Claise <mailto:benoit.claise@huawei.com> Author: Benoit Claise <mailto:benoit.claise@huawei.com>
Author: Jean Quilbeuf <mailto:jean.quilbeu@huawei.com>"; Author: Jean Quilbeuf <mailto:jean.quilbeu@huawei.com>";
description description
"This module defines objects for assuring services based on their "This module defines objects for assuring services based on their
decomposition into so-called subservices, according to the SAIN decomposition into so-called subservices, according to the
(Service Assurance for Intent-based Networking) architecture. Service Assurance for Intent-based Networking (SAIN)
architecture.
The subservices hierarchically organised by dependencies constitute The subservices hierarchically organized by dependencies
an assurance graph. This module should be supported by an assurance constitute an assurance graph. This module should be supported
agent, able to interact with the devices in order to produce a by an assurance agent that is able to interact with the devices
health status and symptoms for each subservice in the assurance in order to produce the health status and symptoms for each
graph. subservice in the assurance graph.
This module is intended for the following use cases: This module is intended for the following use cases:
* Assurance graph configuration: * Assurance graph configuration:
- subservices: configure a set of subservices to assure, by - Subservices: Configure a set of subservices to assure by
specifying their types and parameters. specifying their types and parameters.
- dependencies: configure the dependencies between the - Dependencies: Configure the dependencies between the
subservices, along with their type. subservices, along with their type.
* Assurance telemetry: export the health status of the subservices, * Assurance telemetry: Export the health statuses of the
along with the observed symptoms. subservices, along with the observed symptoms.
Copyright (c) 2022 IETF Trust and the persons identified as Copyright (c) 2023 IETF Trust and the persons identified as
authors of the code. All rights reserved. authors of the code. All rights reserved.
Redistribution and use in source and binary forms, with or Redistribution and use in source and binary forms, with or
without modification, is permitted pursuant to, and subject without modification, is permitted pursuant to, and subject
to the license terms contained in, the Revised BSD License to the license terms contained in, the Revised BSD License
set forth in Section 4.c of the IETF Trust's Legal Provisions set forth in Section 4.c of the IETF Trust's Legal Provisions
Relating to IETF Documents Relating to IETF Documents
(https://trustee.ietf.org/license-info). (https://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC XXXX; see the
This version of this YANG module is part of RFC 9418; see the
RFC itself for full legal notices. "; RFC itself for full legal notices. ";
revision 2022-08-10 { revision 2023-06-02 {
description description
"Initial version."; "Initial version.";
reference reference
"RFC xxxx: YANG Modules for Service Assurance"; "RFC 9418: YANG Modules for Service Assurance";
} }
identity subservice-base { identity subservice-base {
description description
"Base identity for subservice types."; "Base identity for subservice types.";
} }
identity service-instance-type { identity service-instance-type {
base subservice-base; base subservice-base;
description description
"Specific type of subservice that represents a service "Specific type of subservice that represents a service
instance. Instance of this type will depend on other subservices instance. Instance of this type will depend on other
to build the top of the assurance graph."; subservices to build the top of the assurance graph.";
} }
identity dependency-type { identity dependency-type {
description description
"Base identity for representing dependency types."; "Base identity for representing dependency types.";
} }
identity informational { identity informational {
base dependency-type; base dependency-type;
description description
"Indicates that symptoms of the dependency might be of interest "Indicates that symptoms of the dependency might be of interest
for the dependent, but the status of the dependency should not for the dependent, but the status of the dependency should not
have any impact on the dependent."; have any impact on the dependent.";
} }
identity impacting { identity impacting {
base dependency-type; base dependency-type;
description description
"Indicates that the status of the dependency directly impacts the "Indicates that the status of the dependency directly impacts
status of the dependent."; the status of the dependent.";
} }
grouping subservice-reference { grouping subservice-reference {
description description
"Reference to a specific subservice, identified by its type and "Reference to a specific subservice identified by its type and
identifier. This grouping is only for internal use in this identifier. This grouping is only for internal use in this
module."; module.";
leaf type { leaf type {
type leafref { type leafref {
path "/subservices/subservice/type"; path "/subservices/subservice/type";
} }
description description
"The type of the subservice to refer to (e.g., device)."; "The type of the subservice to refer to (e.g., device).";
} }
leaf id { leaf id {
type leafref { type leafref {
path "/subservices/subservice[type=current()/../type]/id"; path "/subservices/subservice[type=current()/../type]/id";
} }
description description
"The identifier of the subservice to refer to."; "The identifier of the subservice to refer to.";
} }
} }
grouping subservice-dependency { grouping subservice-dependency {
description description
"Represents a dependency to another subservice. This grouping "Represents a dependency to another subservice. This grouping
is only for internal use in this module"; is only for internal use in this module";
uses subservice-reference; uses subservice-reference;
leaf dependency-type { leaf dependency-type {
type identityref { type identityref {
base dependency-type; base dependency-type;
} }
description description
"Represents the type of dependency (e.g., informational, "Represents the type of dependency (e.g., informational or
impacting)."; impacting).";
} }
} }
leaf assurance-graph-last-change { leaf assurance-graph-last-change {
type yang:date-and-time; type yang:date-and-time;
config false; config false;
mandatory true; mandatory true;
description description
"Time and date at which the assurance graph last changed after any "Time and date at which the assurance graph last changed after
structural changes (dependencies and/or maintenance windows any structural changes (dependencies and/or maintenance
parameters) are applied to the subservice(s). The time and date windows parameters) are applied to the subservice(s). The
must be the same or more recent than the most recent value of any time and date must be the same or more recent than the most
changed subservices last-change time and date."; recent value of any changed subservices last-change time and
date.";
} }
container subservices { container subservices {
description description
"Root container for the subservices."; "Root container for the subservices.";
list subservice { list subservice {
key "type id"; key "type id";
description description
"List of configured subservices."; "List of configured subservices.";
leaf type { leaf type {
type identityref { type identityref {
base subservice-base; base subservice-base;
} }
description description
"Type of the subservice, identifying the type of the part "Type of the subservice identifying the type of the part
or functionality that is being assured by this list entry. or functionality that is being assured by this list
For instance 'interface', 'device', 'ip-connectivity'."; entry, for instance, interface, device, or
ip-connectivity.";
} }
leaf id { leaf id {
type string; type string;
description description
"Identifier of the subservice instance. Must be unique among "Identifier of the subservice instance. Must be unique
subservices of the same type."; among subservices of the same type.";
} }
leaf last-change { leaf last-change {
type yang:date-and-time; type yang:date-and-time;
config false; config false;
description description
"Date and time at which the structure for this "Date and time at which the structure for this
subservice instance last changed, i.e., dependencies and/or subservice instance last changed, i.e., dependencies
maintenance windows parameters."; and/or maintenance windows parameters.";
} }
leaf label { leaf label {
type string; type string;
config false; config false;
description description
"Label of the subservice, i.e., text describing what the "Label of the subservice, i.e., text describing what the
subservice is to be displayed on a human interface. subservice is to be displayed on a human interface.
It is not intended for random end users but for It is not intended for random end users but for
network/system/software engineers that are able to interpret network/system/software engineers that are able to
it. Therefore, no mechanism for language tagging is needed."; interpret it. Therefore, no mechanism for language
tagging is needed.";
} }
container under-maintenance { container under-maintenance {
presence "true"; presence "true";
description description
"The presence of this container indicates that the current "The presence of this container indicates that the current
subservice is under maintenance"; subservice is under maintenance.";
leaf contact { leaf contact {
type string; type string;
mandatory true; mandatory true;
description description
"A string used to model an administratively assigned name of "A string used to model an administratively assigned name
the resource that is performing maintenance. of the resource that is performing maintenance.
It is suggested that this freeform field, which could be a It is suggested that this freeform field, which could be
URI, contains one or more of the following: IP address, a URI, contains one or more of the following: IP
management station name, network manager's name, location, address, management station name, network manager's
or phone number. It might even contain the expected name, location, and/or phone number. It might even
maintenance time. contain the expected maintenance time.
In some cases the agent itself will be the owner of an In some cases, the agent itself will be the owner of an
entry. In these cases, this string shall be set to a string entry. In these cases, this string shall be set to a
starting with 'monitor'."; string starting with 'monitor'.";
} }
} }
choice parameter { choice parameter {
mandatory true; mandatory true;
description description
"Specify the required parameters per subservice type. Each "Specify the required parameters per subservice type. Each
module augmenting this module with a new subservice type, module augmenting this module with a new subservice type
that is a new identity based on subservice-base should that is a new identity based on subservice-base should
augment this choice as well, by adding a container augment this choice as well by adding a container
available only if the current subservice type is available only if the current subservice type is
the newly added identity."; the newly added identity.";
container service-instance-parameter { container service-instance-parameter {
when "derived-from-or-self(../type, when "derived-from-or-self(../type,
'sain:service-instance-type')"; 'sain:service-instance-type')";
description description
"Specify the parameters of a service instance."; "Specify the parameters of a service instance.";
leaf service { leaf service {
type string; type string;
mandatory true; mandatory true;
description description
"Name of the service."; "Name of the service.";
} }
leaf instance-name { leaf instance-name {
type string; type string;
mandatory true; mandatory true;
description description
"Name of the instance for that service."; "Name of the instance for that service.";
} }
} }
// Other modules can augment their own cases into here // Other modules can augment their own cases into here.
} }
leaf health-score { leaf health-score {
type int8 { type int8 {
range "-1 .. 100"; range "-1 .. 100";
} }
config false; config false;
mandatory true; mandatory true;
description description
"Score value of the subservice health. A value of 100 means "Score value of the subservice health. A value of 100
that subservice is healthy. A value of 0 means that the means that the subservice is healthy. A value of 0 means
subservice is broken. A value between 0 and 100 means that that the subservice is broken. A value between 0 and 100
the subservice is degraded. The special value -1 means that means that the subservice is degraded. The special value
the health-score could not be computed."; -1 means that the health score could not be computed.";
} }
leaf symptoms-history-start { leaf symptoms-history-start {
type yang:date-and-time; type yang:date-and-time;
config false; config false;
description description
"Date and time at which the symptom’s history starts for this "Date and time at which the symptom's history starts for
subservice instance, either because the subservice instance this subservice instance, either because the subservice
started at that date and time or because the symptoms before instance started at that date and time or because the
that were removed due to a garbage collection process."; symptoms before that were removed due to a garbage
collection process.";
} }
container symptoms { container symptoms {
config false; config false;
description description
"Symptoms for the subservice."; "Symptoms for the subservice.";
list symptom { list symptom {
key "start-date-time agent-id symptom-id"; key "start-date-time agent-id symptom-id";
unique "agent-id symptom-id"; unique "agent-id symptom-id";
description description
"List of symptoms the subservice. While the start-date-time "List of symptoms of the subservice. While the
key is not necessary per se, this would get the entries start-date-time key is not necessary per se, this would
sorted by start-date-time for easy consumption."; get the entries sorted by start-date-time for easy
consumption.";
leaf symptom-id { leaf symptom-id {
type leafref { type leafref {
path "/agents/agent[id=current()/../agent-id]" path "/agents/agent[id=current()/../agent-id]"
+ "/symptoms/id"; + "/symptoms/id";
} }
description description
"Identifier of the symptom, to be interpreted according "Identifier of the symptom to be interpreted according
to the agent identified by the agent-id."; to the agent identified by the agent-id.";
} }
leaf agent-id { leaf agent-id {
type leafref { type leafref {
path "/agents/agent/id"; path "/agents/agent/id";
} }
description description
"Identifier of the agent raising the current symptom."; "Identifier of the agent raising the current symptom.";
} }
leaf health-score-weight { leaf health-score-weight {
type uint8 { type uint8 {
range "0 .. 100"; range "0 .. 100";
} }
description description
"The weight to the health score incurred by this symptom. "The weight to the health score incurred by this
The higher the value, the more of an impact this symptom symptom. The higher the value, the more of an impact
has. If a subservice health score is not 100, there must this symptom has. If a subservice health score is not
be at least one symptom with a health score weight 100, there must be at least one symptom with a
larger than 0."; health-score-weight larger than 0.";
} }
leaf start-date-time { leaf start-date-time {
type yang:date-and-time; type yang:date-and-time;
description description
"Date and time at which the symptom was detected."; "Date and time at which the symptom was detected.";
} }
leaf stop-date-time { leaf stop-date-time {
type yang:date-and-time; type yang:date-and-time;
description description
"Date and time at which the symptom stopped being "Date and time at which the symptom stopped being
detected. must be after the start-date-time. If the detected. Must be after the start-date-time. If the
symptom is ongoing, this field should not be populated."; symptom is ongoing, this field should not be
populated.";
} }
} }
} }
container dependencies { container dependencies {
description description
"Indicates the set of dependencies of the current subservice, "Indicates the set of dependencies of the current
along with their types."; subservice, along with their types.";
list dependency { list dependency {
key "type id"; key "type id";
description description
"List of dependencies of the subservice."; "List of dependencies of the subservice.";
uses subservice-dependency; uses subservice-dependency;
} }
} }
} }
} }
container agents { container agents {
config false; config false;
description description
"Container for the list of agents’s symptoms"; "Container for the list of agents's symptoms.";
list agent { list agent {
key "id"; key "id";
description description
"Contains symptoms of each agent involved in computing the "Contains symptoms of each agent involved in computing the
health status of the current graph. This list acts as a health status of the current graph. This list acts as a
glossary for understanding the symptom ids returned by each glossary for understanding the symptom ids returned by each
agent."; agent.";
leaf id { leaf id {
type string; type string;
description description
"Id of the agent for which we are defining the symptoms. This "Id of the agent for which we are defining the symptoms.
identifier must be unique among all agents."; This identifier must be unique among all agents.";
} }
list symptoms { list symptoms {
key "id"; key "id";
description description
"List of symptoms raised by the current agent, identified "List of symptoms raised by the current agent that is
by their symptom-id."; identified by the symptom-id.";
leaf id { leaf id {
type string; type string;
description description
"Id of the symptom for the current agent. The agent must "Id of the symptom for the current agent. The agent must
guarantee the unicity of this identifier."; guarantee the unicity of this identifier.";
} }
leaf description { leaf description {
type string; type string;
mandatory true; mandatory true;
description description
"Description of the symptom, i.e., text describing what the "Description of the symptom, i.e., text describing what
symptom is, to be computer-consumable and be displayed on a the symptom is, is to be computer consumable and
human interface. displayed on a human interface.
It is not intended for random end users but for It is not intended for random end users but for
network/system/software engineers that are able to network/system/software engineers that are able to
interpret it. Therefore, no mechanism for language tagging interpret it. Therefore, no mechanism for language
is needed."; tagging is needed.";
} }
} }
} }
} }
container assured-services { container assured-services {
config false; config false;
description description
"Container for the index of assured services"; "Container for the index of assured services.";
list assured-service { list assured-service {
key "service"; key "service";
description description
"Service instances that are currently part of the assurance "Service instances that are currently part of the assurance
graph. The list must contain an entry for every service graph. The list must contain an entry for every service
that is currently present in the assurance graph. This list that is currently present in the assurance graph. This list
presents an alternate access to the graph stored in presents an alternate access to the graph stored in
/subservices that optimizes querying the assurance graph of a subservices that optimizes querying the assurance graph of
specific service instance."; a specific service instance.";
leaf service { leaf service {
type leafref { type leafref {
path "/subservices/subservice/service-instance-parameter/" path "/subservices/subservice/service-instance-parameter/"
+ "service"; + "service";
} }
description description
"Name of the service."; "Name of the service.";
} }
list instances { list instances {
key "name"; key "name";
description description
"Instances of the service. The list must contain "Instances of the service. The list must contain
an entry for every instance of the parent service."; an entry for every instance of the parent service.";
leaf name { leaf name {
type leafref { type leafref {
path path "/subservices/subservice/service-instance-parameter"
"/subservices/subservice/service-instance-parameter/" + "/instance-name";
+ "instance-name";
} }
description description
"Name of the service instance. The leafref must point to a "Name of the service instance. The leafref must point to
service-instance-parameter whose service leaf matches the a service-instance-parameter whose service leaf matches
parent service."; the parent service.";
} }
list subservices { list subservices {
key "type id"; key "type id";
description description
"Subservices that appear in the assurance graph of the "Subservices that appear in the assurance graph of the
current service instance. current service instance.
The list must contain the subservice corresponding to the The list must contain the subservice corresponding to
service instance, that is the subservice that matches the the service instance, i.e., the subservice that
service and instance-name keys. matches the service and instance-name keys.
For every subservice in the list, all subservices listed as For every subservice in the list, all subservices listed
dependencies must also appear in the list."; as dependencies must also appear in the list.";
uses subservice-reference; uses subservice-reference;
} }
} }
} }
} }
} }
]]></sourcecode>
]]></artwork>
</figure>
<t>&lt;CODE ENDS></t>
</section> </section>
<!-- <section title="Getting the Assurance Graph" anchor="getting-graph">
<t> <section anchor="circular-dependencies" numbered="true" toc="default">
In practice, getting the assurance graph of a service requires applyin <name>Rejecting Circular Dependencies</name>
g a graph traversal algorithm such as depth-first search (DFS) starting from the
node representing the service.
Such an algorithm can be applied on the global graph fetched at once.
Otherwise, the algorithm can query nodes and their dependencies as nee
ded.
The second version might be more interesting if only one service is of
interest among several other services in the global graph.
</t>
<t>
A more frequent use case might be to maintain a local version of the a
ssurance graph.
Model driven telemetry (MDT) enables subscribing to a path of interest
such as '/subservices/subservice/dependencies' and thus getting regular updates
about the graph structure.
If event driven telemetry (EDT) is supported, updates would be sent on
ly when the structure of the graph changes.
Again, one can subscribe to changes in the whole graph (e.g. to save i
t in a time series database (TSDB)), or only on the dependencies of selected nod
e (e.g. to monitor evolution of the graph of a single service).
In the latter case, the subscription must be updated dynamically as no
des are added and removed from the service assurance graph.
</t>
<t>
Finally, some use cases do not require to get the whole assurance grap
h.
For instance, the health status of a given service instance is obtaine
d by monitoring the '/subservices/subservice/health-score' and '/subservices/sub
service/symptoms' paths for that service instance.
In this use case, the assurance graph might be optionally obtained by
using one of the previous methods only if the health score of the service is bel
ow a given threshold.
</t>
</section> -->
<section title="Rejecting Circular Dependencies" anchor="circular-dependen
cies">
<t> <t>
<!-- Circular dependencies check is needed at the server side --> The statuses of services and subservices depend on the statuses of the
The statuses of services and subservices depend on the statuses of the ir dependencies, and thus circular dependencies between them prevent the computa
ir dependencies, and thus circular dependencies between them prevents the comput tion of statuses.
ation of statuses. Section <xref target="RFC9417" sectionFormat="bare" section="3.1.1"/>
The SAIN architecture document <xref target="I-D.ietf-opsawg-service-a of the SAIN architecture document <xref target="RFC9417" format="default"/> disc
ssurance-architecture"/> discusses in Section 3.1.1 how such dependencies appear usses how such dependencies appear and how they could be removed.
and how they could be removed.
The responsibility of avoiding such dependencies falls to the SAIN orc hestrator. The responsibility of avoiding such dependencies falls to the SAIN orc hestrator.
However, we specify in this section the expected behavior when a serve r supporting the ietf-service-assurance module receives a data instance containi ng circular dependencies. However, we specify in this section the expected behavior when a serve r supporting the "ietf-service-assurance" module receives a data instance contai ning circular dependencies.
</t> </t>
<t> <t>
<!--We cannot rely on YANG to validate -->
Enforcing the absence of circular dependencies as a YANG constraint fa lls back to implementing a graph traversal algorithm with XPath and checking tha t the current node is not reachable from its dependencies. Enforcing the absence of circular dependencies as a YANG constraint fa lls back to implementing a graph traversal algorithm with XPath and checking tha t the current node is not reachable from its dependencies.
Even with such a constraint, there is no guarantee that merging two gr aphs without dependency loops will result in a graph without dependency loops. Even with such a constraint, there is no guarantee that merging two gr aphs without dependency loops will result in a graph without dependency loops.
Indeed, the Section 3.1.1 of <xref target="I-D.ietf-opsawg-service-as surance-architecture"/> presents an example where merging two graphs without dep endency loops results in a graph with a dependency loop. Indeed, <xref target="RFC9417" section="3.1.1" sectionFormat="of" form at="default"/> presents an example where merging two graphs without dependency l oops results in a graph with a dependency loop.
</t> </t>
<t> <t>
<!-- The server must reject circular dependencies --> Therefore, a server implementing the "ietf-service-assurance" module <
Therefore, a server implementing the ietf-service-assurance module MUS bcp14>MUST</bcp14> check that there is no dependency loop whenever the graph is
T check that there is no dependency loop whenever the graph is modified. modified.
A modification creating a dependency loop MUST be rejected. A modification creating a dependency loop <bcp14>MUST</bcp14> be rejec
ted.
</t> </t>
</section> </section>
</section> </section>
<section title="Guidelines for Defining New Subservice Types" anchor="augmen <section anchor="augment-guide" numbered="true" toc="default">
t-guide"> <name>Guidelines for Defining New Subservice Types</name>
<t> <t>
The base YANG module defined in <xref target="ietf-service-assurance-yan g-model" /> only defines a single type of subservices that represent service ins tances. The base YANG module defined in <xref target="ietf-service-assurance-yan g-model" format="default"/> only defines a single type of subservice that repres ent service instances.
As explained above, this model is meant to be augmented so that a variet y of subservices can be used in the assurance graph. As explained above, this model is meant to be augmented so that a variet y of subservices can be used in the assurance graph.
In this section, we propose some guidelines for specifying such extensio ns at IETF. In this section, we propose some guidelines for specifying such extensio ns at IETF.
</t> </t>
<t> <t>
The mechanism to add a new subservice type is to define a new module for that subservice. The mechanism to add a new subservice type is to define a new module for that subservice.
The module name should start with "ietf-service-assurance-". The module name should start with "ietf-service-assurance-".
The namespace of the module should start with "urn:ietf:params:xml:ns:ya ng:ietf-service-assurance-". The namespace of the module should start with "urn:ietf:params:xml:ns:ya ng:ietf-service-assurance-".
The prefix of the module should start with "sain-". The prefix of the module should start with "sain-".
For instance, the subservice type representing the assurance of a device should have: For instance, the subservice type representing the assurance of a device should have:
<list style="symbols">
<t>the name "ietf-service-assurance-device",</t>
<t>the namespace "urn:ietf:params:xml:ns:yang:ietf-service-assurance-d
evice",</t>
<t>and the prefix "sain-device".</t>
</list>
</t> </t>
<ul spacing="normal">
<li>the name "ietf-service-assurance-device",</li>
<li>the namespace "urn:ietf:params:xml:ns:yang:ietf-service-assurance-device
", and</li>
<li>the prefix "sain-device".</li>
</ul>
<t> <t>
The new module should define: The new module should define:
<list style="symbols">
<t>
A new identity to represent the new type.
</t>
<t>
The parameters fully specifying an instance of the new subservice ty
pe.
</t>
</list>
</t> </t>
<ul spacing="normal">
<li>
a new identity to represent the new type and
</li>
<li>
the parameters fully specifying an instance of the new subservice ty
pe.
</li>
</ul>
<t> <t>
The new identity should be based on the "subservice-base" identity. The new identity should be based on the "subservice-base" identity.
The name of the identity should end with "-type", for instance "device-t ype". The name of the identity should end with "-type", for instance, "device- type".
</t> </t>
<t> <t>
The parameters should be defined in a container named "parameters" augme nting of the choice "/subservices/subservice/parameter" from the main module. The parameters should be defined in a container named "parameters" that augments the choice "/subservices/subservice/parameter" from the main module.
The augmentation should be restricted to cases where the type of the sub service matches the identity representing the new service type. The augmentation should be restricted to cases where the type of the sub service matches the identity representing the new service type.
</t> </t>
<t> <t>
We define two subservice types in the next sections: the "device" subser vice type is defined in <xref target="device-module"/> and the "interface" subse rvice type is defined is <xref target="interface-module"/>. We define two subservice types in the next sections: the "device" subser vice type is defined in <xref target="device-module" format="default"/> and the "interface" subservice type is defined is <xref target="interface-module" format ="default"/>.
These subservices can be taken as examples of the rules defined in this section. These subservices can be taken as examples of the rules defined in this section.
</t> </t>
<t> <t>
Vendors can specify their own subservices types by defining the correspo nding modules in their own namespace. Vendors can specify their own subservices types by defining the correspo nding modules in their own namespace.
An example of such a vendor-specific module is specified in Appendix <xr ef target="acme-device-module"/>. An example of such a vendor-specific module is specified in <xref target ="acme-device-module" format="default"/>.
Vendors can also augment existing IETF-specified subservices to add thei r own vendor-specific information. Vendors can also augment existing IETF-specified subservices to add thei r own vendor-specific information.
</t> </t>
</section> </section>
<section title="Subservice Augmentation: ietf-service-assurance-device YANG <section anchor="device-module" numbered="true" toc="default">
module" anchor="device-module"> <name>Subservice Augmentation: "ietf-service-assurance-device" YANG Module
<section title="Tree View" anchor="ietf-service-assurance-device-tree-view </name>
"> <section anchor="ietf-service-assurance-device-tree-view" numbered="true"
toc="default">
<name>Tree View</name>
<t> <t>
The following tree diagram <xref target="RFC8340"/> The following tree diagram <xref target="RFC8340" format="default"/>
provides an overview of the "ietf-service-assurance-device" module. provides an overview of the "ietf-service-assurance-device" module.
</t> </t>
<t> <sourcecode type="yangtree"><![CDATA[
<figure>
<artwork><![CDATA[
module: ietf-service-assurance-device module: ietf-service-assurance-device
augment /sain:subservices/sain:subservice/sain:parameter: augment /sain:subservices/sain:subservice/sain:parameter:
+--rw parameters +--rw parameters
+--rw device string +--rw device string
]]></sourcecode>
]]></artwork> <t>A complete tree view of the base module with all augmenting modules p
</figure> resented in this document is available in <xref target="global_tree_view" format
</t> ="default"/>. </t>
<t>A complete tree view of the base module with all augmenting modules p
resented in this draft is available in <xref target="global_tree_view"/>. </t>
</section> </section>
<section anchor="ietf-service-assurance-device-concepts" numbered="true" t
<section title="Concepts" anchor="ietf-service-assurance-device-concepts"> oc="default">
<t> <name>Concepts</name>
As the number of subservices will grow over time, the YANG module i <t>
s designed to be extensible. As the number of subservices will grow over time, the YANG module is d
A new subservice type requires the precise specifications of its ty esigned to be extensible.
pe and expected parameters. A new subservice type requires the precise specifications of its type
Let us illustrate the example of the new device subservice type. and expected parameters.
As the name implies, it monitors and reports the device health, alo Let us illustrate the example of the new device subservice type.
ng with some symptoms in case of degradation. As the name implies, it monitors and reports the device health, along
</t> with some symptoms in case of degradation.
<t> </t>
For our device subservice definition, the new identity "device-type <t>
" is specified, as an inheritance from the base identity for subservices. For our device subservice definition, the new identity "device-type" i
This indicates to the assurance agent that we are now assuring the s specified as an inheritance from the base identity for subservices.
health of a device. This indicates to the assurance agent that we are now assuring the hea
</t> lth of a device.
<t> </t>
The typical parameter for the configuration of the device subservic <t>
e is the name of the device that we want to assure. The typical parameter for the configuration of the device subservice i
By augmenting the parameter choice from ietf-service-assurance YANG s the name of the device that we want to assure.
module for the case of the "device-type" subservice type, this new parameter is By augmenting the parameter choice from the "ietf-service-assurance" Y
specified. ANG module for the case of the "device-type" subservice type, this new parameter
</t> is specified.
</t>
</section> </section>
<section anchor="ietf-service-assurance-device-yang-model" numbered="true"
<section title="YANG Module" anchor="ietf-service-assurance-device-yang-mo toc="default">
del"> <name>YANG Module</name>
<t>&lt;CODE BEGINS> file "ietf-service-assurance-device@2022-08-10.yang" <sourcecode name="ietf-service-assurance-device@2023-06-02.yang" type="y
</t> ang" markers="true"><![CDATA[
<figure>
<artwork><![CDATA[
module ietf-service-assurance-device { module ietf-service-assurance-device {
yang-version 1.1; yang-version 1.1;
namespace namespace
"urn:ietf:params:xml:ns:yang:ietf-service-assurance-device"; "urn:ietf:params:xml:ns:yang:ietf-service-assurance-device";
prefix sain-device; prefix sain-device;
import ietf-service-assurance { import ietf-service-assurance {
prefix sain; prefix sain;
reference reference
"RFC xxxx: YANG Modules for Service Assurance"; "RFC 9418: YANG Modules for Service Assurance";
} }
organization organization
"IETF OPSAWG Working Group"; "IETF OPSAWG Working Group";
contact contact
"WG Web: <https://datatracker.ietf.org/wg/opsawg/> "WG Web: <https://datatracker.ietf.org/wg/opsawg/>
WG List: <mailto:opsawg@ietf.org> WG List: <mailto:opsawg@ietf.org>
Author: Benoit Claise <mailto:benoit.claise@huawei.com> Author: Benoit Claise <mailto:benoit.claise@huawei.com>
Author: Jean Quilbeuf <mailto:jean.quilbeuf@huawei.com>"; Author: Jean Quilbeuf <mailto:jean.quilbeuf@huawei.com>";
description description
"This module augments the ietf-service-assurance module with support "This module augments the ietf-service-assurance module with
of the device subservice. support of the device subservice.
Copyright (c) 2022 IETF Trust and the persons identified as Copyright (c) 2023 IETF Trust and the persons identified as
authors of the code. All rights reserved. authors of the code. All rights reserved.
Redistribution and use in source and binary forms, with or Redistribution and use in source and binary forms, with or
without modification, is permitted pursuant to, and subject without modification, is permitted pursuant to, and subject
to the license terms contained in, the Revised BSD License to the license terms contained in, the Revised BSD License
set forth in Section 4.c of the IETF Trust's Legal Provisions set forth in Section 4.c of the IETF Trust's Legal Provisions
Relating to IETF Documents Relating to IETF Documents
(https://trustee.ietf.org/license-info). (https://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC XXXX; see the
This version of this YANG module is part of RFC 9418; see the
RFC itself for full legal notices. "; RFC itself for full legal notices. ";
revision 2022-08-10 { revision 2023-06-02 {
description description
"Initial revision."; "Initial revision.";
reference reference
"RFC xxxx: YANG Modules for Service Assurance"; "RFC 9418: YANG Modules for Service Assurance";
} }
identity device-type { identity device-type {
base sain:subservice-base; base sain:subservice-base;
description description
"Identity of device subservice."; "Identity of device subservice.";
} }
augment "/sain:subservices/sain:subservice/sain:parameter" { augment "/sain:subservices/sain:subservice/sain:parameter" {
when "derived-from-or-self(sain:type, 'device-type')"; when "derived-from-or-self(sain:type, 'device-type')";
description description
"Augments the parameter choice from ietf-service-assurance "Augments the parameter choice from the ietf-service-assurance
module with a case specific to the device subservice."; module with a case specific to the device subservice.";
container parameters { container parameters {
description description
"Parameters for the device subservice type"; "Parameters for the device subservice type.";
leaf device { leaf device {
type string; type string;
mandatory true; mandatory true;
description description
"Identifier of the device to monitor. The "Identifier of the device to monitor. The
identifier (e.g. device id, hostname, management IP) identifier (e.g., device id, hostname, or management IP)
depends on the context."; depends on the context.";
} }
} }
} }
} }
]]></sourcecode>
]]></artwork>
</figure>
<t>&lt;CODE ENDS></t>
</section> </section>
</section> </section>
<section anchor="interface-module" numbered="true" toc="default">
<section title="Subservice Augmentation: ietf-service-assurance-interface YA <name>Subservice Augmentation: "ietf-service-assurance-interface" YANG Mod
NG module" anchor="interface-module"> ule</name>
<section title="Tree View" anchor="ietf-service-assurance-interface-tree-v <section anchor="ietf-service-assurance-interface-tree-view" numbered="tru
iew"> e" toc="default">
<name>Tree View</name>
<t> <t>
The following tree diagram <xref target="RFC8340"/> The following tree diagram <xref target="RFC8340" format="default"/>
provides an overview of the ietf-service-assurance-interface data model. provides an overview of the "ietf-service-assurance-interface" data mode
l.
</t> </t>
<t> <sourcecode type="yangtree"><![CDATA[
<figure>
<artwork><![CDATA[
module: ietf-service-assurance-interface module: ietf-service-assurance-interface
augment /sain:subservices/sain:subservice/sain:parameter: augment /sain:subservices/sain:subservice/sain:parameter:
+--rw parameters +--rw parameters
+--rw device string +--rw device string
+--rw interface string +--rw interface string
]]></sourcecode>
]]></artwork> <t>A complete tree view of the base module with all augmenting modules p
</figure> resented in this document is available in <xref target="global_tree_view" format
</t> ="default"/>. </t>
<t>A complete tree view of the base module with all augmenting modules p
resented in this draft is available in <xref target="global_tree_view"/>. </t>
</section> </section>
<section anchor="ietf-service-assurance-interface-concepts" numbered="true
<section title="Concepts" anchor="ietf-service-assurance-interface-concept " toc="default">
s"> <name>Concepts</name>
<t> <t>
For the interface subservice definition, the new interface-type is For the interface subservice definition, the new interface-type is spe
specified, as an inheritance from the base identity for subservices. cified as an inheritance from the base identity for subservices.
This indicates to the assurance agent that we are now assuring the This indicates to the assurance agent that we are now assuring the hea
health of an interface. lth of an interface.
</t> </t>
<t> <t>
The parameters for the configuration of the interface subservice ar The parameters for the configuration of the interface subservice are t
e the name of the device and, on that specific device, a specific interface. he name of the device and, on that specific device, a specific interface.
These parameters are aligned with the ietf-interfaces model described These parameters are aligned with the "ietf-interfaces" model describe
in <xref target="RFC8343"/> where the name of the interface is the only key need d in <xref target="RFC8343" format="default"/>, where the name of the interface
ed to identify an interface on a given device. is the only key needed to identify an interface on a given device.
By augmenting the parameter choice from ietf-service-assurance YANG By augmenting the parameter choice from the "ietf-service-assurance" Y
module for the case of the interface-type subservice type, those two new parame ANG module for the case of the interface-type subservice type, those two new par
ters are specified. ameters are specified.
</t> </t>
</section> </section>
<section anchor="ietf-service-assurance-interface-yang-model" numbered="tr
<section title="YANG Module" anchor="ietf-service-assurance-interface-yang ue" toc="default">
-model"> <name>YANG Module</name>
<t>&lt;CODE BEGINS> file "ietf-service-assurance-interface@2022-08-10.ya <sourcecode name="ietf-service-assurance-interface@2023-06-02.yang" type
ng"</t> ="yang" markers="true"><![CDATA[
<figure>
<artwork><![CDATA[
module ietf-service-assurance-interface { module ietf-service-assurance-interface {
yang-version 1.1; yang-version 1.1;
namespace namespace
"urn:ietf:params:xml:ns:yang:ietf-service-assurance-interface"; "urn:ietf:params:xml:ns:yang:ietf-service-assurance-interface";
prefix sain-interface; prefix sain-interface;
import ietf-service-assurance { import ietf-service-assurance {
prefix sain; prefix sain;
reference reference
"RFC xxxx: YANG Modules for Service Assurance"; "RFC 9418: YANG Modules for Service Assurance";
} }
organization organization
"IETF OPSAWG Working Group"; "IETF OPSAWG Working Group";
contact contact
"WG Web: <https://datatracker.ietf.org/wg/opsawg/> "WG Web: <https://datatracker.ietf.org/wg/opsawg/>
WG List: <mailto:opsawg@ietf.org> WG List: <mailto:opsawg@ietf.org>
Author: Benoit Claise <mailto:benoit.claise@huawei.com> Author: Benoit Claise <mailto:benoit.claise@huawei.com>
Author: Jean Quilbeuf <mailto:jean.quilbeuf@huawei.com>"; Author: Jean Quilbeuf <mailto:jean.quilbeuf@huawei.com>";
description description
"This module extends the ietf-service-assurance module to add "This module extends the ietf-service-assurance module to add
support for the interface subservice. support for the interface subservice.
Checks whether an interface is healthy. It checks whether an interface is healthy.
Copyright (c) 2022 IETF Trust and the persons identified as Copyright (c) 2023 IETF Trust and the persons identified as
authors of the code. All rights reserved. authors of the code. All rights reserved.
Redistribution and use in source and binary forms, with or Redistribution and use in source and binary forms, with or
without modification, is permitted pursuant to, and subject without modification, is permitted pursuant to, and subject
to the license terms contained in, the Revised BSD License to the license terms contained in, the Revised BSD License
set forth in Section 4.c of the IETF Trust's Legal Provisions set forth in Section 4.c of the IETF Trust's Legal Provisions
Relating to IETF Documents Relating to IETF Documents
(https://trustee.ietf.org/license-info). (https://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC XXXX; see the This version of this YANG module is part of RFC 9418; see the
RFC itself for full legal notices. "; RFC itself for full legal notices. ";
revision 2022-08-10 { revision 2023-06-02 {
description description
"Initial revision."; "Initial revision.";
reference reference
"RFC xxxx: YANG Modules for Service Assurance"; "RFC 9418: YANG Modules for Service Assurance";
} }
identity interface-type { identity interface-type {
base sain:subservice-base; base sain:subservice-base;
description description
"Checks whether an interface is healthy."; "Checks whether an interface is healthy.";
} }
augment "/sain:subservices/sain:subservice/sain:parameter" { augment "/sain:subservices/sain:subservice/sain:parameter" {
when "derived-from-or-self(sain:type, 'interface-type')"; when "derived-from-or-self(sain:type, 'interface-type')";
skipping to change at line 1114 skipping to change at line 1099
} }
leaf interface { leaf interface {
type string; type string;
mandatory true; mandatory true;
description description
"Name of the interface."; "Name of the interface.";
} }
} }
} }
} }
]]></sourcecode>
]]></artwork>
</figure>
<t>&lt;CODE ENDS></t>
</section>
</section>
<!--
<section title="Guidelines for Specific Subservice Extension" anchor="guidel
ines-specific-subservice">
<t>
The base YANG module defined in <xref target="ietf-service-assurance-
yang-model" /> only defines a single type of subservices that represent service
instances.
As explained above, this model is meant to be augmented so that a var
iety of subservices can be used in the assurance graph.
In this section, we propose some guidelines in order to build theses
extensions.
</t>
<t>
First, the specific subservice must be given an adequate unique short na
me that will be used to form longer names (e.g. module name, prefix ...) appeari
ng in the YANG module.
The short name identifies the type of subpart of feature that the subser
vice will represent, for instance if the subservice will assure the health of a
network interface then "interface" is an adequate short name.
If the subservice will assure the IS-IS routing protocol, then "is-is" i
s an adequate short name.
The short name must be in kebab-case.
</t>
<t>
In this section, by subservice YANG module, we mean "YANG module that ex
tends ietf-service-assurance in order to define a specific subservice".
</t>
<section title="Module Name">
<t>
For subservice YANG modules vetted by the IETF, the module name sho
uld be "ietf-service-assurance-" followed by the short name.
For instance, "ietf-service-assurance-interface" or "ietf-service-a
ssurance-is-is".
</t>
<t>
For subservice YANG module that are directly provided by vendors, we p
ropose that they use the company in the prefix.
For example, the prefix for the company "acme" would be "acme-assur
ance-" and the YANG modules would be "acme-assurance-interface", "acme-assurance
-is-is", etc.
</t>
</section>
<section title="Module Namespace">
<t>
For subservice YANG modules vetted by the IETF, the module namespac
e should be "urn:ietf:params:xml:ns:yang:ietf-service-assurance-" followed by th
e short name.
For instance, "urn:ietf:params:xml:ns:yang:ietf-service-assurance-i
nterface" or "urn:ietf:params:xml:ns:yang:example-service-assurance-is-is".
</t>
<t>
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.
</t>
</section>
<section title="Module Prefix">
<t>
For subservice YANG modules vetted by the IETF, the module prefix s
hould be "sain-" followed by the short name.
For instance, "sain-interface" or "sain-is-is".
</t>
<t>
For subservice YANG module that are directly provided by vendors, t
he same pattern can be used provided it does not conflict with an imported prefi
x.
</t>
</section> </section>
<section title="Subservice Specific Identity" anchor="guidelines_subservic
e_identity">
<t>
Each augment specific to a subservice must define an identity repres
enting 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 <xref target
="ietf-service-assurance-yang-model"/>), that identity must be based on the "sub
service-base" identity.
</t>
<t>
For subservice YANG modules vetted by the IETF, the subservice speci
fic identity should be the short name of the subservice followed by "-type".
For instance, "interface-type" or "is-is-type".
</t>
<t>
For subservice YANG module that are directly provided by vendors, th
e same pattern can be used.
</t>
</section>
<section title="Parameters">
<t>
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 m
odule "ietf-service-assurance" (see <xref target="ietf-service-assurance-yang-mo
del"/> and that augment must be guarded so that it is effective only for subserv
ice instance whose type is the subservice specific identity from <xref target="g
uidelines_subservice_identity" />.
</t>
<t>
For subservice YANG module that are directly provided by vendors, the sa
me pattern can be used.
</t>
</section>
</section> </section>
--> <section anchor="security" numbered="true" toc="default">
<name>Security Considerations</name>
<section anchor="security" title="Security Considerations">
<t> <t>
The YANG module specified in this document defines a schema for data The YANG modules specified in this document define schema for data
that is designed to be accessed via network management protocols such that is designed to be accessed via network management protocols such
as NETCONF <xref target="RFC6241"/> or RESTCONF <xref target="RFC8040"/ as NETCONF <xref target="RFC6241" format="default"/> or RESTCONF <xref
>. target="RFC8040" format="default"/>.
The lowest NETCONF layer is the secure transport layer, and the mandato The lowest NETCONF layer is the secure transport layer, and the mandato
ry-to-implement secure transport is Secure Shell (SSH) <xref target="RFC6242"/>. ry-to-implement secure transport is Secure Shell (SSH) <xref target="RFC6242" fo
The lowest RESTCONF layer is HTTPS, and the mandatory-to-implement secure trans rmat="default"/>. The lowest RESTCONF layer is HTTPS, and the mandatory-to-imple
port is TLS <xref target="RFC8446"/>. ment secure transport is TLS <xref target="RFC8446" format="default"/>.
</t> </t>
<t> <t>
The Network Configuration Access Control Model (NACM) <xref target="RFC 8341"/> The Network Configuration Access Control Model (NACM) <xref target="RFC 8341" format="default"/>
provides the means to restrict access for particular NETCONF or provides the means to restrict access for particular NETCONF or
RESTCONF users to a preconfigured subset of all available NETCONF or RESTCONF users to a preconfigured subset of all available NETCONF or
RESTCONF protocol operations and content. RESTCONF protocol operations and content.
</t> </t>
<t>There are a number of data nodes defined in this YANG module that are w <t>There are a number of data nodes defined in these YANG modules that are
ritable/ writable/creatable/deletable (i.e., config true, which is the default). These d
creatable/deletable (i.e., config true, which is the default). These da ata nodes may be considered sensitive or vulnerable in some network environments
ta nodes may be considered sensitive or vulnerable in some network environments. . Write operations (e.g., edit-config) to these data nodes without proper protec
Write operations (e.g., edit-config) to these data nodes without proper protect tion can have a negative effect on network operations. These are the subtrees an
ion can have a negative effect on network operations. These are the subtrees and d data nodes and their sensitivity/vulnerability:
data nodes and their sensitivity/vulnerability: </t>
<list style="symbols"> <ul spacing="normal">
<t> <li>
/subservices/subservice : /subservices/subservice :
By modifying this subtree, one can modify the structure of the assu By modifying this subtree, one can modify the structure of the assu
rance graph which could alter the status of the services reported by the assuran rance graph, which could alter the status of the services reported by the assura
ce framework. nce framework.
On one hand, modifications can cause the assurance system to report On one hand, modifications can cause the assurance system to report
a service as broken when it is actually healthy (false positive), resulting in a service as broken when it is actually healthy (false positive), resulting in
engineers or automation software losing time, and potentially cause real issues engineers or automation software losing time and potentially causing real issues
by doing unnecessary modifications on the network. by doing unnecessary modifications on the network.
On the other hand, modifications could prevent the assurance system On the other hand, modifications could prevent the assurance system
to report actual issues (false negative), resulting in failures that could have from reporting actual issues (false negative), resulting in failures that could
been avoided. have been avoided.
Depending on the service, the impact of these avoidable failures co Depending on the service, the impact of these avoidable failures co
uld be SLA violations fees or disruption of emergency calls. uld be Service-Level Agreement (SLA) violations fees or disruption of emergency
</t> calls.
</list> </li>
</ul>
<t>
Some readable data nodes in these YANG modules may be considered sensiti
ve or vulnerable in some network environments. It is thus important to control r
ead access (e.g., via get, get-config, or notification) to these data nodes. The
se are the subtrees and data nodes and their sensitivity/vulnerability:
</t> </t>
<ul spacing="normal">
<li>/subservices/subservice</li>
<li>/agents/agent</li>
<li>/assured-services/assured-service</li>
</ul>
<t> <t>
Some readable data nodes in this YANG module may be considered sensitive Each of these subtrees contains information about services, subservices,
or vulnerable in some network environments. It is thus important to control rea or possible symptoms raised by the agents.
d access (e.g., via get, get-config, or notification) to these data nodes. These
are the subtrees and data nodes and their sensitivity/vulnerability:
<list style="symbols">
<t>/subservices/subservice</t>
<t>/agents/agent</t>
<t>/assured-services/assured-service</t>
</list>
Each of these subtrees contains information about services, subservices
or possible symptoms raised by the agents.
The information contained in this subtree might give information about t he underlying network as well as services deployed for the customers. The information contained in this subtree might give information about t he underlying network as well as services deployed for the customers.
For instance, a customer might be given access to monitor their services For instance, a customer might be given access to monitor their services
status (e.g. via model-driven telemetry). status (e.g., via model-driven telemetry).
In that example, the customer access should be restricted to nodes repre In that example, the customer access should be restricted to nodes repre
senting their services, so as not to divulge information about the underlying ne senting their services so as not to divulge information about the underlying net
twork structure or others customers services. work structure or others customers services.
</t> </t>
</section> </section>
<section anchor="iana" title="IANA Considerations">
<section title="The IETF XML Registry"><t>This document registers 3 URIs i
n the IETF XML
registry <xref target="RFC3688"/>. Following the format in
<xref target="RFC3688"/>, the following registrations are
requested:</t><t><figure><artwork>
URI: urn:ietf:params:xml:ns:yang:ietf-service-assurance
Registrant Contact: The OPSAWG WG of the IETF.
XML: N/A, the requested URI is an XML namespace.
URI: urn:ietf:params:xml:ns:yang:ietf-service-assurance-device <section anchor="iana" numbered="true" toc="default">
Registrant Contact: The OPSAWG WG of the IETF. <name>IANA Considerations</name>
XML: N/A, the requested URI is an XML namespace. <section numbered="true" toc="default">
<name>The IETF XML Registry</name>
URI: urn:ietf:params:xml:ns:yang:ietf-service-assurance-interface <t>IANA has registered the following three URIs in the "IETF XML
Registrant Contact: The OPSAWG WG of the IETF. Registry" <xref target="RFC3688" format="default"/>:</t>
XML: N/A, the requested URI is an XML namespace. <dl newline="false" spacing="compact">
</artwork></figure></t></section> <dt>URI:</dt>
<section title="The YANG Module Names Registry"> <dd>urn:ietf:params:xml:ns:yang:ietf-service-assurance</dd>
<t>This document registers three YANG modules in the <dt>Registrant Contact:</dt>
YANG Module Names registry <xref target="RFC7950"/>. <dd>The OPSAWG WG of the IETF.</dd>
Following the format in <xref target="RFC7950"/>, <dt>XML:</dt>
the following registrations are requested:</t> <dd>N/A; the requested URI is an XML namespace.</dd>
<t><figure><artwork> </dl>
name: ietf-service-assurance <dl newline="false" spacing="compact">
namespace: urn:ietf:params:xml:ns:yang:ietf-service-assurance <dt>URI:</dt>
prefix: sain <dd>urn:ietf:params:xml:ns:yang:ietf-service-assurance-device</dd>
reference: RFC XXXX <dt>Registrant Contact:</dt>
<dd>The OPSAWG WG of the IETF.</dd>
name: ietf-service-assurance-device <dt>XML:</dt>
namespace: urn:ietf:params:xml:ns:yang:ietf-service-assurance-device <dd>N/A; the requested URI is an XML namespace.</dd>
prefix: sain-device </dl>
reference: RFC XXXX <dl newline="false" spacing="compact">
<dt>URI:</dt>
name: ietf-service-assurance-interface <dd>urn:ietf:params:xml:ns:yang:ietf-service-assurance-interface</dd>
namespace: urn:ietf:params:xml:ns:yang:ietf-service-assurance-interface <dt>Registrant Contact:</dt>
prefix: sain-interface <dd>The OPSAWG WG of the IETF.</dd>
reference: RFC XXXX <dt>XML:</dt>
</artwork></figure></t> <dd>N/A; the requested URI is an XML namespace.</dd>
<t> </dl>
All these modules are not maintained by IANA. </section>
</t> <section numbered="true" toc="default">
<name>The YANG Module Names Registry</name>
<t>IANA has registered the following three YANG modules in the
"YANG Module Names" registry <xref target="RFC7950" format="default"/>:
</t>
<dl newline="false" spacing="compact">
<dt>name:</dt>
<dd>ietf-service-assurance</dd>
<dt>namespace:</dt>
<dd>urn:ietf:params:xml:ns:yang:ietf-service-assurance</dd>
<dt>prefix:</dt>
<dd>sain</dd>
<dt>reference:</dt>
<dd>RFC 9418</dd>
</dl>
<dl newline="false" spacing="compact">
<dt>name:</dt>
<dd>ietf-service-assurance-device</dd>
<dt>namespace:</dt>
<dd>urn:ietf:params:xml:ns:yang:ietf-service-assurance-device</dd>
<dt>prefix:</dt>
<dd>sain-device</dd>
<dt>reference:</dt>
<dd>RFC 9418</dd>
</dl>
<dl newline="false" spacing="compact">
<dt>name:</dt>
<dd>ietf-service-assurance-interface</dd>
<dt>namespace:</dt>
<dd>urn:ietf:params:xml:ns:yang:ietf-service-assurance-interface</dd>
<dt>prefix:</dt>
<dd>sain-interface</dd>
<dt>reference:</dt>
<dd>RFC 9418</dd>
</dl>
<t>
These modules are not maintained by IANA.
</t>
</section> </section>
</section> </section>
</middle>
</middle>
<back> <back>
<references title="Normative References"> <references>
<?rfc include='reference.I-D.ietf-opsawg-service-assurance-architecture'?> <name>References</name>
<?rfc include='reference.RFC.2119'?> <references>
<?rfc include='reference.RFC.3688'?> <name>Normative References</name>
<?rfc include='reference.RFC.6241'?>
<?rfc include='reference.RFC.6242'?>
<?rfc include='reference.RFC.6991'?>
<?rfc include='reference.RFC.7950'?>
<?rfc include="reference.RFC.8040"?>
<?rfc include='reference.RFC.8174'?>
<?rfc include="reference.RFC.8446"?>
<?rfc include="reference.RFC.8341"?>
<?rfc include="reference.RFC.8342"?>
</references>
<references title="Informative References">
<?rfc include="reference.RFC.8340"?>
<?rfc include="reference.RFC.8343"?>
<?rfc include="reference.RFC.8525"?>
</references>
<?rfc needLines="100"?>
<section title="Vendor-specific Subservice Augmentation: example-service-ass <reference anchor='RFC9417' target='https://www.rfc-editor.org/info/rfc9417'>
urance-device-acme YANG module" anchor="acme-device-module"> <front>
<section title="Tree View" anchor="example-service-assurance-device-acme-t <title>
ree-view"> Service Assurance for Intent-Based Networking Architecture
</title>
<author initials="B." surname="Claise" fullname="Benoit Claise">
</author>
<author initials="J." surname="Quilbeuf" fullname="Jean Quilbeuf">
</author>
<author initials="D." surname="Lopez" fullname="Diego R. Lopez">
</author>
<author initials="D." surname="Voyer" fullname="Dan Voyer">
</author>
<author initials="T." surname="Arumugam" fullname="Thangam Arumugam">
</author>
<date month="June" year="2023"/>
</front>
<seriesInfo name="RFC" value="9417"/>
<seriesInfo name="DOI" value="10.17487/RFC9417"/>
</reference>
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.2
119.xml"/>
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.3
688.xml"/>
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.6
241.xml"/>
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.6
242.xml"/>
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.6
991.xml"/>
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.7
950.xml"/>
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8
040.xml"/>
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8
174.xml"/>
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8
446.xml"/>
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8
341.xml"/>
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8
342.xml"/>
</references>
<references>
<name>Informative References</name>
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8
340.xml"/>
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8
343.xml"/>
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8
525.xml"/>
</references>
</references>
<section anchor="acme-device-module" numbered="true" toc="default">
<name>Vendor-Specific Subservice Augmentation: "example-service-assurance-
device-acme" YANG Module</name>
<section anchor="example-service-assurance-device-acme-tree-view" numbered
="true" toc="default">
<name>Tree View</name>
<t> <t>
The following tree diagram <xref target="RFC8340"/> The following tree diagram <xref target="RFC8340" format="default"/>
provides an overview of the "example-service-assurance-device-acme" mo dule. provides an overview of the "example-service-assurance-device-acme" mo dule.
</t> </t>
<t> <sourcecode type="yangtree"><![CDATA[
<figure>
<artwork><![CDATA[
module: example-service-assurance-device-acme module: example-service-assurance-device-acme
augment /sain:subservices/sain:subservice/sain:parameter: augment /sain:subservices/sain:subservice/sain:parameter:
+--rw parameters +--rw parameters
+--rw device string +--rw device string
+--rw acme-specific-parameter string +--rw acme-specific-parameter string
]]></sourcecode>
]]></artwork> <t>A complete tree view of the base module with all augmenting modules p
</figure> resented in this document is available in <xref target="global_tree_view" format
</t> ="default"/>. </t>
<t>A complete tree view of the base module with all augmenting modules p
resented in this draft is available in <xref target="global_tree_view"/>. </t>
</section> </section>
<section anchor="example-service-assurance-device-acme-concepts" numbered=
<section title="Concepts" anchor="example-service-assurance-device-acme-co "true" toc="default">
ncepts"> <name>Concepts</name>
<t> <t>
Under some circumstances, vendor-specific subservice types might be re quired. Under some circumstances, vendor-specific subservice types might be re quired.
As an example of this vendor-specific implementation, this section sho As an example of this vendor-specific implementation, this section sho
ws how to augment the "ietf-service-assurance-device" module to add custom suppo ws how to augment the "ietf-service-assurance-device" module to add custom suppo
rt for the device subservice, specific to the ACME Corporation. rt for the device subservice specific to the Acme Corporation.
The specific version adds a new parameter, named "acme-specific-parame The specific version adds a new parameter named "acme-specific-paramet
ter". er".
It's an implementation choice to either derive a new specific identity It's an implementation choice to either derive a new specific identity
from the "subservice-base" identity defined in ietf-service-assurance or to aug from the "subservice-base" identity defined in the "ietf-service-assurance" mod
ment the parameters from ietf-service-assurance-device, here we choose to create ule or to augment the parameters from the "ietf-service-assurance-device" module
a new identity. ; here, we choose to create a new identity.
</t> </t>
</section> </section>
<section anchor="example-service-assurance-device-acme-yang-model" numbere
<section title="YANG Module" anchor="example-service-assurance-device-acme d="true" toc="default">
-yang-model"> <name>YANG Module</name>
<figure> <sourcecode type="yang"><![CDATA[
<artwork><![CDATA[
module example-service-assurance-device-acme { module example-service-assurance-device-acme {
yang-version 1.1; yang-version 1.1;
namespace "urn:example:example-service-assurance-device-acme"; namespace "urn:example:example-service-assurance-device-acme";
prefix example-device-acme; prefix example-device-acme;
import ietf-service-assurance { import ietf-service-assurance {
prefix sain; prefix sain;
reference reference
"RFC xxxx: YANG Modules for Service Assurance"; "RFC 9418: YANG Modules for Service Assurance";
} }
import ietf-service-assurance-device { import ietf-service-assurance-device {
prefix sain-device; prefix sain-device;
reference reference
"RFC xxxx: YANG Modules for Service Assurance"; "RFC 9418: YANG Modules for Service Assurance";
} }
organization organization
"IETF OPSAWG Working Group"; "IETF OPSAWG Working Group";
contact contact
"WG Web: <https://datatracker.ietf.org/wg/opsawg/> "WG Web: <https://datatracker.ietf.org/wg/opsawg/>
WG List: <mailto:opsawg@ietf.org> WG List: <mailto:opsawg@ietf.org>
Author: Benoit Claise <mailto:benoit.claise@huawei.com> Author: Benoit Claise <mailto:benoit.claise@huawei.com>
Author: Jean Quilbeuf <mailto:jean.quilbeuf@huawei.com>"; Author: Jean Quilbeuf <mailto:jean.quilbeuf@huawei.com>";
description description
"This example module extends the ietf-service-assurance-device "This example module extends the ietf-service-assurance-device
module to add specific support for devices of ACME Corporation. "; module to add specific support for devices of the Acme
Corporation. ";
revision 2022-08-10 { revision 2023-06-02 {
description description
"Initial revision"; "Initial revision.";
reference reference
"RFC xxxx: YANG Modules for Service Assurance"; "RFC 9418: YANG Modules for Service Assurance";
} }
identity device-acme-type { identity device-acme-type {
base sain-device:device-type; base sain-device:device-type;
description description
"Network Device is healthy."; "Network device is healthy.";
} }
augment "/sain:subservices/sain:subservice/sain:parameter" { augment "/sain:subservices/sain:subservice/sain:parameter" {
when "derived-from-or-self(sain:type, 'device-acme-type')"; when "derived-from-or-self(sain:type, 'device-acme-type')";
description description
"Augments the parameter choice from ietf-service-assurance "Augments the parameter choice from the ietf-service-assurance
module with a case specific to the device-acme subservice."; module with a case specific to the device-acme subservice.";
container parameters { container parameters {
description description
"Parameters for the device-acme subservice type"; "Parameters for the device-acme subservice type.";
leaf device { leaf device {
type string; type string;
mandatory true; mandatory true;
description description
"The device to monitor."; "The device to monitor.";
} }
leaf acme-specific-parameter { leaf acme-specific-parameter {
type string; type string;
mandatory true; mandatory true;
description description
"The ACME Corporation specific parameter."; "The Acme-Corporation-specific parameter.";
} }
} }
} }
} }
]]></sourcecode>
]]></artwork>
</figure>
</section> </section>
</section> </section>
<section anchor="ip-connectivity-is-is" numbered="true" toc="default">
<section title="Further Augmentations: IP Connectivity and IS-IS subservices <name>Further Augmentations: IP Connectivity and IS-IS Subservices</name>
" anchor="ip-connectivity-is-is">
<t> <t>
In this section, we provide two additional YANG modules to completely co In this section, we provide two additional YANG modules to completely co
ver the example in Figure 2 from Section 3.1 of <xref target="I-D.ietf-opsawg-s ver the example in Figure 2 from <xref target="RFC9417" section="3.1" sectionFor
ervice-assurance-architecture"/>. mat="of" format="default"/>.
The two missing subservice types are IP Connectivity and the Intermediat The two missing subservice types are IP connectivity and the Intermediat
e System to Intermediate System (IS-IS) routing protocol. e System to Intermediate System (IS-IS) routing protocol.
These modules are presented as examples, some future work is needed to These modules are presented as examples; some future work is needed to
propose a more complete version. propose a more complete version.
</t> </t>
<section title="IP Connectivity Module Tree View"> <section numbered="true" toc="default">
<name>IP Connectivity Module Tree View</name>
<t> <t>
That subservice represents the unicast connectivity between two IP add resses located on two different devices. That subservice represents the unicast connectivity between two IP add resses located on two different devices.
Such a subservice could report symptoms such as "No route found". Such a subservice could report symptoms such as "No route found".
The following tree diagram <xref target="RFC8340"/> provides an overvi ew of the "example-service-assurance-ip-connectivity" module. The following tree diagram <xref target="RFC8340" format="default"/> p rovides an overview of the "example-service-assurance-ip-connectivity" module.
</t> </t>
<t> <sourcecode type="yangtree"><![CDATA[
<figure>
<artwork><![CDATA[
module: example-service-assurance-ip-connectivity module: example-service-assurance-ip-connectivity
augment /sain:subservices/sain:subservice/sain:parameter: augment /sain:subservices/sain:subservice/sain:parameter:
+--rw parameters +--rw parameters
+--rw device1 string +--rw device1 string
+--rw address1 inet:ip-address +--rw address1 inet:ip-address
+--rw device2 string +--rw device2 string
+--rw address2 inet:ip-address +--rw address2 inet:ip-address
]]></sourcecode>
]]></artwork>
</figure>
</t>
<t> <t>
To specify the connectivity that we are interested in, we specify two IP addresses and two devices. 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 d evice 1 and IP address 2 on device 2 is healthy. The subservice assures that the connectivity between IP address 1 on d evice 1 and IP address 2 on device 2 is healthy.
</t> </t>
</section> </section>
<section title="IS-IS Module Tree View"> <section numbered="true" toc="default">
<name>IS-IS Module Tree View</name>
<t> <t>
The following tree diagram <xref target="RFC8340"/> provides an overvi ew of the "example-service-assurance-is-is" module. The following tree diagram <xref target="RFC8340" format="default"/> p rovides an overview of the "example-service-assurance-is-is" module.
</t> </t>
<t> <sourcecode type="yangtree"><![CDATA[
<figure>
<artwork><![CDATA[
module: example-service-assurance-is-is module: example-service-assurance-is-is
augment /sain:subservices/sain:subservice/sain:parameter: augment /sain:subservices/sain:subservice/sain:parameter:
+--rw parameters +--rw parameters
+--rw instance-name string +--rw instance-name string
]]></sourcecode>
]]></artwork>
</figure>
</t>
<t> <t>
The parameter of this subservice is the name of the IS-IS instance to assure. The parameter of this subservice is the name of the IS-IS instance to assure.
</t> </t>
</section> </section>
<section title="Global Tree View" anchor="global_tree_view"> <section anchor="global_tree_view" numbered="true" toc="default">
<name>Global Tree View</name>
<t> <t>
The following tree diagram <xref target="RFC8340"/> The following tree diagram <xref target="RFC8340" format="default"/>
provides an overview of the "ietf-service-assurance", "ietf-service-as surance-device", provides an overview of the "ietf-service-assurance", "ietf-service-as surance-device",
"example-service-assurance-device-acme", "example-service-assurance-ip -connectivity" and "example-service-assurance-is-is" modules. "example-service-assurance-device-acme", "example-service-assurance-ip -connectivity", and "example-service-assurance-is-is" modules.
</t> </t>
<t> <sourcecode type="yangtree"><![CDATA[
<figure>
<artwork><![CDATA[
module: ietf-service-assurance module: ietf-service-assurance
+--ro assurance-graph-last-change yang:date-and-time +--ro assurance-graph-last-change yang:date-and-time
+--rw subservices +--rw subservices
| +--rw subservice* [type id] | +--rw subservice* [type id]
| +--rw type identityref | +--rw type identityref
| +--rw id string | +--rw id string
| +--ro last-change? | +--ro last-change?
| | yang:date-and-time | | yang:date-and-time
| +--ro label? string | +--ro label? string
| +--rw under-maintenance! | +--rw under-maintenance!
skipping to change at line 1529 skipping to change at line 1482
| +--ro id string | +--ro id string
| +--ro description string | +--ro description string
+--ro assured-services +--ro assured-services
+--ro assured-service* [service] +--ro assured-service* [service]
+--ro service leafref +--ro service leafref
+--ro instances* [name] +--ro instances* [name]
+--ro name leafref +--ro name leafref
+--ro subservices* [type id] +--ro subservices* [type id]
+--ro type -> /subservices/subservice/type +--ro type -> /subservices/subservice/type
+--ro id leafref +--ro id leafref
]]></sourcecode>
]]></artwork>
</figure>
</t>
</section> </section>
<section title="IP Connectivity YANG Module"> <section numbered="true" toc="default">
<figure> <name>IP Connectivity YANG Module</name>
<artwork><![CDATA[ <sourcecode type="yang"><![CDATA[
module example-service-assurance-ip-connectivity { module example-service-assurance-ip-connectivity {
yang-version 1.1; yang-version 1.1;
namespace "urn:example:example-service-assurance-ip-connectivity"; namespace "urn:example:example-service-assurance-ip-connectivity";
prefix example-ip-connectivity; prefix example-ip-connectivity;
import ietf-inet-types { import ietf-inet-types {
prefix inet; prefix inet;
reference reference
"RFC 6991: Common YANG Data Types"; "RFC 6991: Common YANG Data Types";
} }
import ietf-service-assurance { import ietf-service-assurance {
prefix sain; prefix sain;
reference reference
"RFC xxxx: YANG Modules for Service Assurance"; "RFC 9418: YANG Modules for Service Assurance";
} }
organization organization
"IETF OPSAWG Working Group"; "IETF OPSAWG Working Group";
contact contact
"WG Web: <https://datatracker.ietf.org/wg/opsawg/> "WG Web: <https://datatracker.ietf.org/wg/opsawg/>
WG List: <mailto:opsawg@ietf.org> WG List: <mailto:opsawg@ietf.org>
Author: Benoit Claise <mailto:benoit.claise@huawei.com> Author: Benoit Claise <mailto:benoit.claise@huawei.com>
Author: Jean Quilbeuf <mailto:jean.quilbeuf@huawei.com>"; Author: Jean Quilbeuf <mailto:jean.quilbeuf@huawei.com>";
description description
"This example module augments the ietf-service-assurance module to "This example module augments the ietf-service-assurance module
add support for the subservice ip-connectivity. to add support for the subservice ip-connectivity.
Checks whether the ip connectivity between two ip addresses It checks whether the IP connectivity between two IP addresses
belonging to two network devices is healthy."; belonging to two network devices is healthy.";
revision 2022-08-10 { revision 2023-06-02 {
description description
"Initial version"; "Initial version.";
reference reference
"RFC xxxx: YANG Modules for Service Assurance"; "RFC 9418: YANG Modules for Service Assurance";
} }
identity ip-connectivity-type { identity ip-connectivity-type {
base sain:subservice-base; base sain:subservice-base;
description description
"Checks connectivity between two IP addresses."; "Checks connectivity between two IP addresses.";
} }
augment "/sain:subservices/sain:subservice/sain:parameter" { augment "/sain:subservices/sain:subservice/sain:parameter" {
when "derived-from-or-self(sain:type, 'ip-connectivity-type')"; when "derived-from-or-self(sain:type, 'ip-connectivity-type')";
description description
"Augments the parameter choice from ietf-service-assurance "Augments the parameter choice from the ietf-service-assurance
module with a case specific to the ip-connectivity module with a case specific to the ip-connectivity
subservice."; subservice.";
container parameters { container parameters {
description description
"Parameters for the ip-connectivity subservice type"; "Parameters for the ip-connectivity subservice type.";
leaf device1 { leaf device1 {
type string; type string;
mandatory true; mandatory true;
description description
"Device at the first end of the connection."; "Device at the first end of the connection.";
} }
leaf address1 { leaf address1 {
type inet:ip-address; type inet:ip-address;
mandatory true; mandatory true;
description description
skipping to change at line 1616 skipping to change at line 1566
} }
leaf address2 { leaf address2 {
type inet:ip-address; type inet:ip-address;
mandatory true; mandatory true;
description description
"Address at the second end of the connection."; "Address at the second end of the connection.";
} }
} }
} }
} }
]]></sourcecode>
]]></artwork>
</figure>
</section> </section>
<section title="IS-IS YANG Module"> <section numbered="true" toc="default">
<figure> <name>IS-IS YANG Module</name>
<artwork><![CDATA[ <sourcecode type="yang"><![CDATA[
module example-service-assurance-is-is { module example-service-assurance-is-is {
yang-version 1.1; yang-version 1.1;
namespace "urn:example:example-service-assurance-is-is"; namespace "urn:example:example-service-assurance-is-is";
prefix example-is-is; prefix example-is-is;
import ietf-service-assurance { import ietf-service-assurance {
prefix sain; prefix sain;
reference reference
"RFC xxxx: YANG Modules for Service Assurance"; "RFC 9418: YANG Modules for Service Assurance";
} }
organization organization
"IETF OPSAWG Working Group"; "IETF OPSAWG Working Group";
contact contact
"WG Web: <https://datatracker.ietf.org/wg/opsawg/> "WG Web: <https://datatracker.ietf.org/wg/opsawg/>
WG List: <mailto:opsawg@ietf.org> WG List: <mailto:opsawg@ietf.org>
Author: Benoit Claise <mailto:benoit.claise@huawei.com> Author: Benoit Claise <mailto:benoit.claise@huawei.com>
Author: Jean Quilbeuf <mailto:jean.quilbeuf@huawei.com>"; Author: Jean Quilbeuf <mailto:jean.quilbeuf@huawei.com>";
description description
"This example module augments the ietf-service-assurance module to "This example module augments the ietf-service-assurance module
add support for the subservice is-is. to add support for the subservice is-is.
Checks whether an IS-IS instance is healthy."; It checks whether an IS-IS instance is healthy.";
revision 2022-08-10 { revision 2023-06-02 {
description description
"Initial version"; "Initial version.";
reference reference
"RFC xxxx: YANG Modules for Service Assurance"; "RFC 9418: YANG Modules for Service Assurance";
} }
identity is-is-type { identity is-is-type {
base sain:subservice-base; base sain:subservice-base;
description description
"Health of IS-IS routing protocol."; "Health of IS-IS routing protocol.";
} }
augment "/sain:subservices/sain:subservice/sain:parameter" { augment "/sain:subservices/sain:subservice/sain:parameter" {
when "derived-from-or-self(sain:type, 'is-is-type')"; when "derived-from-or-self(sain:type, 'is-is-type')";
description description
"Augments the parameter choice from ietf-service-assurance "Augments the parameter choice from the ietf-service-assurance
module with a case specific to the is-is subservice."; module with a case specific to the is-is subservice.";
container parameters { container parameters {
description description
"Parameters for the is-is subservice type."; "Parameters for the is-is subservice type.";
leaf instance-name { leaf instance-name {
type string; type string;
mandatory true; mandatory true;
description description
"The instance to monitor."; "The instance to monitor.";
} }
} }
} }
} }
]]></sourcecode>
]]></artwork>
</figure>
</section> </section>
</section> </section>
<section title="Example of YANG instance" anchor="example_instances"> <section anchor="example_instances" numbered="true" toc="default">
<name>Example of a YANG Instance</name>
<t> <t>
This section contains an example of YANG instance that conform to the Y This section contains an example of a YANG instance that conforms to th
ANG modules. e YANG modules.
The validity of this data instance has been checked using <eref target= The validity of this data instance has been checked using <eref target=
"https://yangson.labs.nic.cz/" >yangson</eref>. "https://yangson.labs.nic.cz/" brackets="angle">yangson</eref>.
Yangson requires a YANG library <xref target="RFC8525"/> to define the Yangson requires a YANG library <xref target="RFC8525" format="default"
complete model against which the data instance must be validated. /> to define the complete model against which the data instance must be validate
We provide in <xref target="yang_library_for_validation" /> the JSON li d.
brary file, named "ietf-service-assurance-library.json", that we used for valid In <xref target="yang_library_for_validation" format="default"/>, we pr
ation. ovide the JSON library file named "ietf-service-assurance-library.json", which
we used for validation.
</t> </t>
<t> <t>
We provide below the contents of the file "example_configuration_instan Below, we provide the contents of the file "example_configuration_insta
ce.json" which contains the configuration data that models the Figure 2 from Sec nce.json", which contains the configuration data that models Figure 2 from <xref
tion 3.1 of <xref target="I-D.ietf-opsawg-service-assurance-architecture" />. target="RFC9417" section="3.1" sectionFormat="of" format="default"/>.
The instance can be validated with yangson by using the invocation "yan The instance can be validated with yangson by using the invocation "yan
gson -v example_configuration_instance.json ietf-service-assurance-library.json" gson -v example_configuration_instance.json ietf-service-assurance-library.json"
, assuming all the files (YANG and JSON) defined in this draft reside in the cur , assuming all the files (YANG and JSON) defined in this document reside in the
rent folder. current folder.
</t> </t>
<figure> <sourcecode type="json"><![CDATA[
<artwork><![CDATA[
{ {
"ietf-service-assurance:subservices": { "ietf-service-assurance:subservices": {
"subservice": [ "subservice": [
{ {
"type": "service-instance-type", "type": "service-instance-type",
"id": "simple-tunnel/example", "id": "simple-tunnel/example",
"service-instance-parameter": { "service-instance-parameter": {
"service": "simple-tunnel", "service": "simple-tunnel",
"instance-name": "example" "instance-name": "example"
}, },
"dependencies": { "dependencies": {
"dependency": [ "dependency": [
{ {
"type": "ietf-service-assurance-interface:interface-type", "type":
"ietf-service-assurance-interface:interface-type",
"id": "interface/peer1/tunnel0", "id": "interface/peer1/tunnel0",
"dependency-type": "impacting" "dependency-type": "impacting"
}, },
{ {
"type": "ietf-service-assurance-interface:interface-type", "type":
"ietf-service-assurance-interface:interface-type",
"id": "interface/peer2/tunnel9", "id": "interface/peer2/tunnel9",
"dependency-type": "impacting" "dependency-type": "impacting"
}, },
{ {
"type": "type":
"example-service-assurance-ip-connectivity:ip-connectivity-type", "example-service-assurance-ip-connectivity:ip-connectivity-type",
"id": "connectivity/peer1/2001:db8::1/peer2/2001:db8::2", "id":
"connectivity/peer1/2001:db8::1/peer2/2001:db8::2",
"dependency-type": "impacting" "dependency-type": "impacting"
} }
] ]
} }
}, },
{ {
"type": "type":
"example-service-assurance-ip-connectivity:ip-connectivity-type", "example-service-assurance-ip-connectivity:ip-connectivity-type",
"id": "connectivity/peer1/2001:db8::1/peer2/2001:db8::2", "id": "connectivity/peer1/2001:db8::1/peer2/2001:db8::2",
"example-service-assurance-ip-connectivity:parameters": { "example-service-assurance-ip-connectivity:parameters": {
"device1": "Peer1", "device1": "Peer1",
"address1": "2001:db8::1", "address1": "2001:db8::1",
"device2": "Peer2", "device2": "Peer2",
"address2": "2001:db8::2" "address2": "2001:db8::2"
}, },
"dependencies": { "dependencies": {
"dependency": [ "dependency": [
{ {
"type": "ietf-service-assurance-interface:interface-type", "type":
"ietf-service-assurance-interface:interface-type",
"id": "interface/peer1/physical0", "id": "interface/peer1/physical0",
"dependency-type": "impacting" "dependency-type": "impacting"
}, },
{ {
"type": "ietf-service-assurance-interface:interface-type", "type":
"ietf-service-assurance-interface:interface-type",
"id": "interface/peer2/physical5", "id": "interface/peer2/physical5",
"dependency-type": "impacting" "dependency-type": "impacting"
}, },
{ {
"type": "example-service-assurance-is-is:is-is-type", "type": "example-service-assurance-is-is:is-is-type",
"id": "is-is/instance1", "id": "is-is/instance1",
"dependency-type": "impacting" "dependency-type": "impacting"
} }
] ]
} }
skipping to change at line 1773 skipping to change at line 1724
{ {
"type": "ietf-service-assurance-interface:interface-type", "type": "ietf-service-assurance-interface:interface-type",
"id": "interface/peer1/tunnel0", "id": "interface/peer1/tunnel0",
"ietf-service-assurance-interface:parameters": { "ietf-service-assurance-interface:parameters": {
"device": "Peer1", "device": "Peer1",
"interface": "tunnel0" "interface": "tunnel0"
}, },
"dependencies": { "dependencies": {
"dependency": [ "dependency": [
{ {
"type": "ietf-service-assurance-interface:interface-type", "type":
"ietf-service-assurance-interface:interface-type",
"id": "interface/peer1/physical0", "id": "interface/peer1/physical0",
"dependency-type": "impacting" "dependency-type": "impacting"
} }
] ]
} }
}, },
{ {
"type": "ietf-service-assurance-interface:interface-type", "type": "ietf-service-assurance-interface:interface-type",
"id": "interface/peer1/physical0", "id": "interface/peer1/physical0",
"ietf-service-assurance-interface:parameters": { "ietf-service-assurance-interface:parameters": {
skipping to change at line 1814 skipping to change at line 1766
{ {
"type": "ietf-service-assurance-interface:interface-type", "type": "ietf-service-assurance-interface:interface-type",
"id": "interface/peer2/tunnel9", "id": "interface/peer2/tunnel9",
"ietf-service-assurance-interface:parameters": { "ietf-service-assurance-interface:parameters": {
"device": "Peer2", "device": "Peer2",
"interface": "tunnel9" "interface": "tunnel9"
}, },
"dependencies": { "dependencies": {
"dependency": [ "dependency": [
{ {
"type": "ietf-service-assurance-interface:interface-type", "type":
"ietf-service-assurance-interface:interface-type",
"id": "interface/peer2/physical5", "id": "interface/peer2/physical5",
"dependency-type": "impacting" "dependency-type": "impacting"
} }
] ]
} }
}, },
{ {
"type": "ietf-service-assurance-interface:interface-type", "type": "ietf-service-assurance-interface:interface-type",
"id": "interface/peer2/physical5", "id": "interface/peer2/physical5",
"ietf-service-assurance-interface:parameters": { "ietf-service-assurance-interface:parameters": {
skipping to change at line 1848 skipping to change at line 1801
{ {
"type": "ietf-service-assurance-device:device-type", "type": "ietf-service-assurance-device:device-type",
"id": "interface/peer2", "id": "interface/peer2",
"ietf-service-assurance-device:parameters": { "ietf-service-assurance-device:parameters": {
"device": "Peer2" "device": "Peer2"
} }
} }
] ]
} }
} }
]]></sourcecode>
]]></artwork>
</figure>
</section> </section>
<section title="YANG Library for Service Assurance" anchor="yang_library_for <section anchor="yang_library_for_validation" numbered="true" toc="default">
_validation"> <name>YANG Library for Service Assurance</name>
<t> <t>
This section provides the JSON encoding of the YANG library <xref target ="RFC8525"/> listing all modules defined in this draft and their dependencies. This section provides the JSON encoding of the YANG library <xref target ="RFC8525" format="default"/> that lists all modules defined in this document an d their dependencies.
This library can be used to validate data instances using yangson, as ex plained in the previous section. This library can be used to validate data instances using yangson, as ex plained in the previous section.
</t> </t>
<figure> <sourcecode type="json"><![CDATA[
<artwork><![CDATA[
{ {
"ietf-yang-library:modules-state": { "ietf-yang-library:modules-state": {
"module-set-id": "ietf-service-assurance@2022-08-10", "module-set-id": "ietf-service-assurance@2023-06-02",
"module": [ "module": [
{ {
"name": "ietf-service-assurance", "name": "ietf-service-assurance",
"namespace": "namespace":
"urn:ietf:params:xml:ns:yang:ietf-service-assurance", "urn:ietf:params:xml:ns:yang:ietf-service-assurance",
"revision": "2022-08-10", "revision": "2023-06-02",
"conformance-type": "implement" "conformance-type": "implement"
}, },
{ {
"name": "ietf-service-assurance-device", "name": "ietf-service-assurance-device",
"namespace": "namespace":
"urn:ietf:params:xml:ns:yang:ietf-service-assurance-device", "urn:ietf:params:xml:ns:yang:ietf-service-assurance-device",
"revision": "2022-08-10", "revision": "2023-06-02",
"conformance-type": "implement" "conformance-type": "implement"
}, },
{ {
"name": "ietf-service-assurance-interface", "name": "ietf-service-assurance-interface",
"namespace": "namespace":
"urn:ietf:params:xml:ns:yang:ietf-service-assurance-interface", "urn:ietf:params:xml:ns:yang:ietf-service-assurance-interface",
"revision": "2022-08-10", "revision": "2023-06-02",
"conformance-type": "implement" "conformance-type": "implement"
}, },
{ {
"name": "example-service-assurance-device-acme", "name": "example-service-assurance-device-acme",
"namespace": "namespace":
"urn:example:example-service-assurance-device-acme", "urn:example:example-service-assurance-device-acme",
"revision": "2022-08-10", "revision": "2023-06-02",
"conformance-type": "implement" "conformance-type": "implement"
}, },
{ {
"name": "example-service-assurance-is-is", "name": "example-service-assurance-is-is",
"namespace": "urn:example:example-service-assurance-is-is", "namespace": "urn:example:example-service-assurance-is-is",
"revision": "2022-08-10", "revision": "2023-06-02",
"conformance-type": "implement" "conformance-type": "implement"
}, },
{ {
"name": "example-service-assurance-ip-connectivity", "name": "example-service-assurance-ip-connectivity",
"namespace": "namespace":
"urn:example:example-service-assurance-ip-connectivity", "urn:example:example-service-assurance-ip-connectivity",
"revision": "2022-08-10", "revision": "2023-06-02",
"conformance-type": "implement" "conformance-type": "implement"
}, },
{ {
"name": "ietf-yang-types", "name": "ietf-yang-types",
"namespace": "urn:ietf:params:xml:ns:yang:ietf-yang-types", "namespace": "urn:ietf:params:xml:ns:yang:ietf-yang-types",
"revision": "2021-04-14", "revision": "2013-07-05",
"conformance-type": "import" "conformance-type": "import"
}, },
{ {
"name": "ietf-inet-types", "name": "ietf-inet-types",
"namespace": "urn:ietf:params:xml:ns:yang:ietf-inet-types", "namespace": "urn:ietf:params:xml:ns:yang:ietf-inet-types",
"revision": "2021-02-22", "revision": "2013-07-05",
"conformance-type": "import" "conformance-type": "import"
} }
] ]
} }
} }
]]></sourcecode>
]]></artwork>
</figure>
</section> </section>
<section numbered="false" toc="default">
<section title="Changes between revisions"> <name>Acknowledgements</name>
<t>[[RFC editor: please remove this section before publication.]]</t> <t>The authors would like to thank <contact fullname="Jan Lindblad"/> for
<t>v09 - v10 his help during the design of these YANG modules.
<list style="symbols"> The authors would like to thank <contact fullname="Stephane Litkowski"
<t>Address comments from Last Call</t> />, <contact fullname="Charles Eckel"/>, <contact fullname="Mohamed Boucadair"/>
</list> , <contact fullname="Tom Petch"/>, <contact fullname="Dhruv Dhody"/>, and <conta
</t> ct fullname="Rob Wilton"/> for their reviews.
<t>v07 - v08
<list style="symbols">
<t>Address comments from Rob Wilton’s AD review</t>
</list>
</t>
<t>v06 - v07
<list style="symbols">
<t>Addressed early YANG doctor comments from version -06: changed -idt
y for -type or -base in identity names and removed "under-maintenance" leaf </t>
<t>Add new list of services with the corresponding subservices</t>
<t>Remove assurance-graph-version and state the limitations of having
only the current graph available in the module.</t>
<t>Added new list of agents to store symptom and guarantee unicity of
symptom ids </t>
<t>Added security consideration for readable nodes</t>
<t>Added section on rejecting circular dependencies</t>
</list>
</t>
<t>v05 - v06
<list style="symbols">
<t>Remove revision history in modules</t>
<t>Present elements in order of the tree for the main module</t>
<t>Rewriting and rewording for clarity</t>
<t>Made parameters mandatory for the subservices</t>
</list>
</t>
<t>v04 - v05
<list style="symbols">
<t>Remove Guidelines section </t>
<t>Move informative parts (examples) to appendix</t>
<t>Minor text edits and reformulations</t>
</list>
</t>
<t>v03 - v04
<list style="symbols">
<t> Fix YANG errors </t>
<t> Change is-is and ip-connectivity subservices from ietf to example.
</t>
<t> Mention that models are NMDA compliant </t>
<t> Fix typos, reformulate for clarity </t>
</list>
</t>
<t>v02 - v03
<list style="symbols">
<t>Change counter32 to counter64 to avoid resetting too frequently </t
>
<t>Explain why relation between health-score and symptom’s health-scor
e-weight is not defined and how it could be defined</t>
</list>
</t>
<t>v01 - v02
<list style="symbols">
<t>Explicitly represent the fact that the health-score could not be co
mputed (value -1)</t>
</list>
</t>
<t>v00 - v01
<list style="symbols">
<t>Added needed subservice to model example from architecture draft</t
>
<t>Added guideline section for naming models</t>
<t>Added data instance examples and validation procedure</t>
<t>Added the "parameters" container in the interface YANG module to co
rrect a bug.</t>
</list>
</t> </t>
</section> </section>
<section title="Acknowledgements" numbered="no">
<t>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, Charles Eckel, Moh
amed Boucadair, Tom Petch, Dhruv Dhody and Rob Wilton for their reviews.
</t>
</section>
</back> </back>
</rfc> </rfc>
<!-- Local Variables: --> <!-- Local Variables: -->
<!-- fill-column:72 --> <!-- fill-column:72 -->
<!-- End: --> <!-- End: -->
 End of changes. 250 change blocks. 
1001 lines changed or deleted 844 lines changed or added

This html diff was produced by rfcdiff 1.48.