3. Base IETF Service Assurance YANG Module
3.1. Concepts
The "ietf-service-assurance" YANG module assumes a set of subservices, to be assured independently. A subservice is a feature or a subpart of the network system that a given service instance depends on. Examples of subservices include:¶
- device: whether a device is healthy, and if not, what are the symptoms. Potential symptoms are "CPU overloaded", "Out of RAM", or "Out of TCAM".¶
- ip-connectivity: given two IP addresses bound to two devices, what is the quality of the IP connectivity between them. Potential symptoms are "No route available" or "ECMP Imbalance".¶
The first example is a subservice representing a subpart of the network system, while the second is a subservice representing a feature of the network. In both cases, these subservices might depend on other subservices, for instance, the connectivity might depend on a subservice representing the routing system and on a subservice representing ECMP.¶
The two subservices presented above need different sets of parameters to fully characterize one of their instance. An instance of the device subservice is fully characterized by a single 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. Therefore, the "ietf-service-assurance" module is intended to be augmented for each type of subservice, so that the needed parameters are modelled in the augmenting module.¶
The only "built-in" type available represents service instances. A service instance is represented as a subservice instance of type "service". The parameters required to fully identify a service instance are the type of the service and the name of the service instance.¶
The dependencies are modelled as an adjacency list, in the sense that each subservice contains a list of pointers to its dependencies. That list can be empty if the subservice instance does not have any dependencies.¶
By specifying service instances and their dependencies in terms of subservices, one defines a global assurance graph. That assurance graph is the result of merging all the individual assurance graphs for the assured service instances. Each subservice instance is expected to appear only one in the global assurance graph even if several service instances depend on it. For example, an instance of the device subservice is a dependency of every service instance that rely on the corresponding device. The assurance graph of a specific service instance is the subgraph obtained by traversing the global assurance graph through the dependencies starting from the specific service instance.¶
An assurance agent configured with such a graph is expected to produce, for each configured subservice: a health-status indicating how healthy the subservice is and when the subservice is not healthy, a list of symptoms explaining why the subservice is not healthy.¶
3.2. Tree View
The following tree diagram [RFC8340] provides an overview of the "ietf-service-assurance" module.¶
module: ietf-service-assurance
+--ro assurance-graph-version yang:counter64
+--ro assurance-graph-last-change yang:date-and-time
+--rw subservices
+--rw subservice* [type id]
+--rw type identityref
+--rw id string
+--ro last-change? yang:date-and-time
+--ro label? string
+--rw under-maintenance? boolean
+--rw maintenance-contact string
+--rw (parameter)
| +--:(service-instance-parameter)
| +--rw service-instance-parameter
| +--rw service string
| +--rw instance-name string
+--ro health-score? union
+--ro symptoms-history-start? yang:date-and-time
+--ro symptoms
| +--ro symptom* [start-date-time id]
| +--ro id string
| +--ro health-score-weight? uint8
| +--ro description? string
| +--ro start-date-time yang:date-and-time
| +--ro stop-date-time? yang:date-and-time
+--rw dependencies
+--rw dependency* [type id]
+--rw type
| -> /subservices/subservice/type
+--rw id leafref
+--rw dependency-type? identityref
¶
The current version "assurance-graph-version" and date of last change "assurance-graph-last-change" are read only and must be maintained by the server. The version should be incremented and the date updated each time the graph structure is changed by addition or deletion of subservices, dependencies or modification of their configurable attributes. Such modifications correspond to a structural change in the graph. The current version and the date of last change are useful for a client to quickly check if there is a need to update the graph structure. A change in the health-score or symptoms associated to a service or subservice does not change the structure of the graph and thus has no effect on the version or date of last change.¶
The "subservice" list contains all the subservice instances currently configured on the server. A subservice declaration MUST provide:¶
- A subservice type ("type"): reference to an identity that inherits from "subservice-idty", which is the base identity for any subservice type.¶
- An id ("id"): string uniquely identifying the subservice among those with the same type,¶
The type and id uniquely identify a given subservice.¶
The "last-change" indicates when this particular subservice was modified for the last time.¶
The "label" is a human-readable description of the subservice.¶
The "under-maintenance" and "maintenance-contact" flags inhibit the emission of symptoms for that subservice and subservices that depend on them. See Section 3.7 of [I-D.ietf-opsawg-service-assurance-architecture] for a more detailed discussion.¶
The "parameter" choice is intended to be augmented in order to describe parameters that are specific to the current subservice type. This base module defines only the subservice type representing service instances. Service instances MUST be modeled as a particular type of subservice with two parameters, "service" and "instance-name". The "service" parameter is the name of the service defined in the network orchestrator, for instance "point-to-point-l2vpn". The "instance-name" parameter is the name assigned to the particular instance to be assured, for instance the name of the customer using that instance.¶
The "health-score" contains a value normally between 0 and 100 indicating how healthy the subservice is. The special value -1 can be used to specify that no value could be computed for that health-score, for instance if some metric needed for that computation could not be collected.¶
The "symptoms-history-start" is the cutoff date for reporting symptoms. Symptoms that were terminated before that date are not reported anymore in the model.¶
The status of each subservice contains a list of symptoms. Each symptom is specified by¶
- an identifier "id" which MUST be globally unique,¶
- a "health-score-weight" specifying the impact to the health score incurred by this symptom,¶
- a "description" explaining what the symptom is,¶
- a "start-date-time" indicating when the symptom became active and¶
- a "stop-date-time" indicating when the symptom stopped being active, that field is not present if the symptom is still active.¶
While the unique id is sufficient as an unique key list, the start-date-time second key help sorting and retrieving relevant symptoms.¶
The "dependency" list contains the dependencies for the current subservice. 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:¶
- Impacting: such a dependency indicates an impact on the health of the dependent,¶
- Informational: such a dependency might explain why the dependent has issues but does not impact its health.¶
To illustrate the difference between "impacting" and "informational", consider the interface subservice, representing a network interface. If the device to which the network interface belongs goes down, the network interface will transition to a "down" state as well. Therefore, the dependency of the interface subservice towards the device subservice is "impacting". On the other hand, a dependency towards the ecmp-load subservice, which checks that the load between ECMP remains stable throughout time, is only "informational". Indeed, services might be perfectly healthy even if the load distribution between ECMP changed. However, such an instability might be a relevant symptom for diagnosing the root cause of a problem.¶
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 only requirement is that a health score that strictly smaller than 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 compute the health score based on the health-score-weight of the detected symptoms. As an example, such a computation could be to sum the health-score-weight of the active symptoms, subtract that value from 100 and change the value to 0 if negative. The relation between health-score and health-score-weight is left to the implementor (of an agent [I-D.ietf-opsawg-service-assurance-architecture]).¶
3.3. YANG Module
<CODE BEGINS> file "ietf-service-assurance@2022-04-07.yang"¶
module ietf-service-assurance {
yang-version 1.1;
namespace "urn:ietf:params:xml:ns:yang:ietf-service-assurance";
prefix sain;
import ietf-yang-types {
prefix yang;
reference
"RFC 6991: Common YANG Data Types";
}
organization
"IETF OPSAWG Working Group";
contact
"WG Web: <https://datatracker.ietf.org/wg/opsawg/>
WG List: <mailto:opsawg@ietf.org>
Author: Benoit Claise <mailto:benoit.claise@huawei.com>
Author: Jean Quilbeuf <mailto:jean.quilbeu@huawei.com>";
description
"This module defines objects for assuring services based on their
decomposition into so-called subservices, according to the SAIN
(Service Assurance for Intent-based Networking) architecture.
The subservices hierarchically organised by dependencies constitute
an assurance graph. This module should be supported by an assurance
agent, able to interact with the devices in order to produce a
health status and symptoms for each subservice in the assurance
graph.
This module is intended for the following use cases:
* Assurance graph configuration:
- subservices: configure a set of subservices to assure, by
specifying their types and parameters.
- dependencies: configure the dependencies between the
subservices, along with their type.
* Assurance telemetry: export the health status of the subservices,
along with the observed symptoms.
Copyright (c) 2022 IETF Trust and the persons identified as
authors of the code. All rights reserved.
Redistribution and use in source and binary forms, with or
without modification, is permitted pursuant to, and subject
to the license terms contained in, the Revised BSD License
set forth in Section 4.c of the IETF Trust's Legal Provisions
Relating to IETF Documents
(https://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC XXXX; see the
RFC itself for full legal notices. ";
revision 2022-06-23 {
description
"Initial version.";
reference
"RFC xxxx: YANG Modules for Service Assurance";
}
identity subservice-idty {
description
"Base identity for subservice types.";
}
identity service-instance-idty {
base subservice-idty;
description
"Identity representing a service instance.";
}
identity dependency-type {
description
"Base identity for representing dependency types.";
}
identity informational {
base dependency-type;
description
"Indicates that symptoms of the dependency might be of interest
for the dependent, but the status of the dependency should not
have any impact on the dependent.";
}
identity impacting {
base dependency-type;
description
"Indicates that the status of the dependency directly impacts the
status of the dependent.";
}
grouping symptom {
description
"A grouping for the symptoms for a specific subservice.";
leaf id {
type string;
description
"A globally unique identifier for the symptom, to be generated
by the SAIN agent that detected the symptom.";
}
leaf health-score-weight {
type uint8 {
range "0 .. 100";
}
description
"The weight to the health score incurred by this symptom. The
higher the value, the more of an impact this symptom has. If a
subservice health score is not 100, there must be at least one
symptom with a health score weight larger than 0.";
}
leaf description {
type string;
description
"Description of the symptom, i.e., text describing what the
symptom is, to be computer-consumable and be displayed on a
human interface. It is not intended for random end users but
for network/system/software engineers that use their local
context to provide and interpret such information. Therefore,
no mechanism for language tagging is needed.";
}
leaf start-date-time {
type yang:date-and-time;
description
"Date and time at which the symptom was detected.";
}
leaf stop-date-time {
type yang:date-and-time;
description
"Date and time at which the symptom stopped being detected.
must after the start-date-time.";
}
}
grouping subservice-dependency {
description
"Represents a dependency to another subservice.";
leaf type {
type leafref {
path "/subservices/subservice/type";
}
description
"The type of the subservice to refer to (e.g., device).";
}
leaf id {
type leafref {
path "/subservices/subservice[type=current()/../type]/id";
}
description
"The identifier of the subservice to refer to.";
}
leaf dependency-type {
type identityref {
base dependency-type;
}
description
"Represents the type of dependency (e.g., informational,
impacting).";
}
}
leaf assurance-graph-version {
type yang:counter64;
config false;
mandatory true;
description
"The assurance graph version, which increases by 1 for each new
version, that cause structural changes to the graph. Structural
changes include addition or deletion of subservices and
modification of a subservice parameters, dependencies or
maintenance windows. Structural changes correspond to changes in
the nodes that are config true.
The counter wraps around when the maximum value is reached.";
}
leaf assurance-graph-last-change {
type yang:date-and-time;
config false;
mandatory true;
description
"Date and time at which the assurance graph last changed after the
changes (dependencies and/or maintenance windows parameters) are
applied to the subservice(s). These date and time must be more
recent or equal compared to the more recent value of any changed
subservices last-change";
}
container subservices {
description
"Root container for the subservices.";
list subservice {
key "type id";
description
"List of configured subservices.";
leaf type {
type identityref {
base subservice-idty;
}
description
"Type of the subservice, for instance, device or interface.";
}
leaf id {
type string;
description
"Identifier of the subservice instance. Must be unique among
subservices of the same type.";
}
leaf last-change {
type yang:date-and-time;
config false;
description
"Date and time at which the structure for this
subservice instance last changed, i.e., dependencies and/or
maintenance windows parameters.";
}
leaf label {
type string;
config false;
description
"Label of the subservice, i.e., text describing what the
subservice is to be displayed on a human interface.
It is not intended for random end users but for
network/system/software engineers that use their local
context to provide and interpret such information.
Therefore, no mechanism for language tagging is needed.";
}
leaf under-maintenance {
type boolean;
default "false";
description
"A flag indicating whether this particular subservice is
under maintenance. Under this circumstance, the subservice
symptoms and the symptoms of its dependencies in the
assurance graph are not taken into account. Instead,
the subservice should report a single symptom 'Under
Maintenance'.
The operator changing the under-maintenance value must set
the maintenance-contact variable.
When the subservice is not under maintenance any longer, the
under-maintenance flag must return to its default value and
the under-maintenance-owner variable deleted.";
}
leaf maintenance-contact {
when "../under-maintenance = 'true'";
type string;
mandatory true;
description
"A string used to model an administratively assigned name of
the resource that changed the under-maintenance value to
'true'.
It is suggested that this name contain one or more of the
following: IP address, management station name,
network manager's name, location, or phone number. In some
cases the agent itself will be the owner of an entry. In
these cases, this string shall be set to a string starting
with 'monitor'.";
}
choice parameter {
mandatory true;
description
"Specify the required parameters per subservice type. Each
module augmenting this module with a new subservice type,
that is a new identity based on subservice-idty should
augment this choice as well, by adding a container
available only if the current subservice type is
the newly added identity.";
container service-instance-parameter {
when "derived-from-or-self(../type,
'sain:service-instance-idty')";
description
"Specify the parameters of a service instance.";
leaf service {
type string;
mandatory true;
description
"Name of the service.";
}
leaf instance-name {
type string;
mandatory true;
description
"Name of the instance for that service.";
}
}
// Other modules can augment their own cases into here
}
leaf health-score {
type union {
type uint8 {
range "0 .. 100";
}
type enumeration {
enum missing {
value -1;
description
"Explictly represent the fact that the health score is
missing. This could be used when metrics crucial to
establish the health score are not collected anymore.";
}
}
}
config false;
description
"Score value of the subservice health. A value of 100 means
that subservice is healthy. A value of 0 means that the
subservice is broken. A value between 0 and 100 means that
the subservice is degraded.";
}
leaf symptoms-history-start {
type yang:date-and-time;
config false;
description
"Date and time at which the symptoms history starts for this
subservice instance, either because the subservice instance
started at that date and time or because the symptoms before
that were removed due to a garbage collection process.";
}
container symptoms {
config false;
description
"Symptoms for the subservice.";
list symptom {
key "start-date-time id";
description
"List of symptoms the subservice. While the start-date-time
key is not necessary per se, this would get the entries
sorted by start-date-time for easy consumption.";
uses symptom;
}
}
container dependencies {
description
"Indicates the set of dependencies of the current subservice,
along with their types.";
list dependency {
key "type id";
description
"List of dependencies of the subservice.";
uses subservice-dependency;
}
}
}
}
}
¶
<CODE ENDS>¶