idnits 2.17.1 draft-ietf-opsawg-service-assurance-yang-04.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 196 has weird spacing: '...-change yan...' == Line 209 has weird spacing: '...ce-name str...' == Line 703 has weird spacing: '... device str...' == Line 712 has weird spacing: '...-change yan...' == Line 725 has weird spacing: '...ce-name str...' == (17 more instances...) == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (25 April 2022) is 725 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Downref: Normative reference to an Informational draft: draft-claise-opsawg-service-assurance-architecture (ref. 'I-D.ietf-opsawg-service-assurance-architecture') -- Obsolete informational reference (is this intentional?): RFC 7895 (Obsoleted by RFC 8525) Summary: 1 error (**), 0 flaws (~~), 8 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 OPSAWG B. Claise 3 Internet-Draft J. Quilbeuf 4 Intended status: Standards Track Huawei 5 Expires: 27 October 2022 P. Lucente 6 NTT 7 P. Fasano 8 TIM S.p.A 9 T. Arumugam 10 Cisco Systems, Inc. 11 25 April 2022 13 YANG Modules for Service Assurance 14 draft-ietf-opsawg-service-assurance-yang-04 16 Abstract 18 This document specifies YANG modules representing assurance graphs. 19 These graphs represent the assurance of a given service by 20 decomposing it into atomic assurance elements called subservices. A 21 companion RFC, Service Assurance for Intent-based Networking 22 Architecture, presents an architecture for implementing the assurance 23 of such services. 25 The YANG data models in this document conforms to the Network 26 Management Datastore Architecture (NMDA) defined in RFC 8342. 28 Status of This Memo 30 This Internet-Draft is submitted in full conformance with the 31 provisions of BCP 78 and BCP 79. 33 Internet-Drafts are working documents of the Internet Engineering 34 Task Force (IETF). Note that other groups may also distribute 35 working documents as Internet-Drafts. The list of current Internet- 36 Drafts is at https://datatracker.ietf.org/drafts/current/. 38 Internet-Drafts are draft documents valid for a maximum of six months 39 and may be updated, replaced, or obsoleted by other documents at any 40 time. It is inappropriate to use Internet-Drafts as reference 41 material or to cite them other than as "work in progress." 43 This Internet-Draft will expire on 27 October 2022. 45 Copyright Notice 47 Copyright (c) 2022 IETF Trust and the persons identified as the 48 document authors. All rights reserved. 50 This document is subject to BCP 78 and the IETF Trust's Legal 51 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 52 license-info) in effect on the date of publication of this document. 53 Please review these documents carefully, as they describe your rights 54 and restrictions with respect to this document. Code Components 55 extracted from this document must include Revised BSD License text as 56 described in Section 4.e of the Trust Legal Provisions and are 57 provided without warranty as described in the Revised BSD License. 59 Table of Contents 61 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 62 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 63 2. YANG Models Overview . . . . . . . . . . . . . . . . . . . . 3 64 3. Base ietf-service-assurance YANG module . . . . . . . . . . . 4 65 3.1. Tree View . . . . . . . . . . . . . . . . . . . . . . . . 4 66 3.2. Concepts . . . . . . . . . . . . . . . . . . . . . . . . 5 67 3.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 7 68 4. Subservice Extension: ietf-service-assurance-device YANG 69 module . . . . . . . . . . . . . . . . . . . . . . . . . 15 70 4.1. Tree View . . . . . . . . . . . . . . . . . . . . . . . . 15 71 4.2. Complete Tree View . . . . . . . . . . . . . . . . . . . 15 72 4.3. Concepts . . . . . . . . . . . . . . . . . . . . . . . . 16 73 4.4. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 17 74 5. Subservice Extension: ietf-service-assurance-interface YANG 75 module . . . . . . . . . . . . . . . . . . . . . . . . . 19 76 5.1. Tree View . . . . . . . . . . . . . . . . . . . . . . . . 19 77 5.2. Complete Tree View . . . . . . . . . . . . . . . . . . . 19 78 5.3. Concepts . . . . . . . . . . . . . . . . . . . . . . . . 20 79 5.4. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 21 80 6. Vendor-specific Subservice Extension: 81 example-service-assurance-device-acme YANG module . . . . 23 82 6.1. Tree View . . . . . . . . . . . . . . . . . . . . . . . . 23 83 6.2. Complete Tree View . . . . . . . . . . . . . . . . . . . 23 84 6.3. Concepts . . . . . . . . . . . . . . . . . . . . . . . . 25 85 6.4. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 25 86 7. Further Extensions: IP Connectivity and IS-IS subservices . . 27 87 7.1. IP Connectivity Tree View . . . . . . . . . . . . . . . . 27 88 7.2. IS-IS Tree View . . . . . . . . . . . . . . . . . . . . . 28 89 7.3. Global Tree View . . . . . . . . . . . . . . . . . . . . 28 90 7.4. IP Connectivity YANG Module . . . . . . . . . . . . . . . 29 91 7.5. IS-IS YANG Module . . . . . . . . . . . . . . . . . . . . 32 92 8. Guidelines for Specific Subservice Extension . . . . . . . . 33 93 8.1. Module Name . . . . . . . . . . . . . . . . . . . . . . . 34 94 8.2. Module Namespace . . . . . . . . . . . . . . . . . . . . 34 95 8.3. Module Prefix . . . . . . . . . . . . . . . . . . . . . . 34 96 8.4. Subservice Specific Identity . . . . . . . . . . . . . . 35 97 8.5. Parameters . . . . . . . . . . . . . . . . . . . . . . . 35 99 9. Security Considerations . . . . . . . . . . . . . . . . . . . 35 100 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 36 101 10.1. The IETF XML Registry . . . . . . . . . . . . . . . . . 36 102 10.2. The YANG Module Names Registry . . . . . . . . . . . . . 36 103 11. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 37 104 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 37 105 12.1. Normative References . . . . . . . . . . . . . . . . . . 37 106 12.2. Informative References . . . . . . . . . . . . . . . . . 38 107 Appendix A. Example of YANG instances . . . . . . . . . . . . . 38 108 Appendix B. YANG Library for Service Assurance . . . . . . . . . 42 109 Appendix C. Changes between revisions . . . . . . . . . . . . . 43 110 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 44 111 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 44 113 1. Introduction 115 The "Service Assurance for Intent-based Networking Architecture" 116 [I-D.ietf-opsawg-service-assurance-architecture], specifies the 117 architecture and all of its components for service assurance. This 118 document complements the architecture by providing open interfaces 119 between components. More specifically, the goal is to provide YANG 120 modules for the purpose of service assurance in a format that is: 122 * machine readable 124 * vendor independent 126 * augmentable 128 1.1. Terminology 130 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 131 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 132 "OPTIONAL" in this document are to be interpreted as described in BCP 133 13 [RFC2119] [RFC8174] when, and only when, they appear in all 134 capitals, as shown here. 136 The terms used in this document are defined in 137 [I-D.ietf-opsawg-service-assurance-architecture] 139 2. YANG Models Overview 141 The main YANG module, ietf-service-assurance, defines objects for 142 assuring network services based on their decomposition into so-called 143 subservices. The subservices are hierarchically organised by 144 dependencies. The subservices, along with the dependencies, 145 constitute an assurance graph. This module should be supported by an 146 agent, able to interact with the devices in order to produce a health 147 status and symptoms for each subservice in the assurance graph. This 148 module is intended for the following use cases: 150 * Assurance graph configuration: 152 - Subservices: configure a set of subservices to assure, by 153 specifying their types and parameters. 155 - Dependencies: configure the dependencies between the 156 subservices, along with their type. 158 * Assurance telemetry: export the health status of the subservices, 159 along with the observed symptoms. 161 The main module represents the configuration (subservice and 162 dependencies) and operational data (health status and symptoms) in a 163 single tree. Other modules follows the same pattern. Thus, the 164 modules presented in this document conform to the Network Management 165 Datastore Architecture defined in [RFC8342]. 167 The second YANG module, ietf-service-assurance-device, extends the 168 ietf-service-assurance module to add support for the subservice 169 DeviceHealthy. Additional subservice types might be added the same 170 way. 172 The third YANG module, ietf-service-assurance-device, is another 173 example that extends the ietf-service-assurance-device module. This 174 extension adds support for the subservice InterfaceHealthy. 176 The fourth YANG module, example-service-assurance-device-acme, 177 extends the ietf-service-assurance-device module as an example to add 178 support for the subservice DeviceHealthy, with specifics for the 179 fictional ACME Corporation. Additional vendor-specific parameters 180 might be added the same way. 182 Finally, the modules example-service-assurance-ip-connectivity and 183 example-service-assurance-is-is are provided to completely model the 184 example from the SAIN architecture draft 185 [I-D.ietf-opsawg-service-assurance-architecture]. 187 3. Base ietf-service-assurance YANG module 189 3.1. Tree View 191 The following tree diagram [RFC8340] provides an overview of the 192 ietf-service-assurance data model. 194 module: ietf-service-assurance 195 +--ro assurance-graph-version yang:counter64 196 +--ro assurance-graph-last-change yang:date-and-time 197 +--rw subservices 198 +--rw subservice* [type id] 199 +--rw type identityref 200 +--rw id string 201 +--ro last-change? yang:date-and-time 202 +--ro label? string 203 +--rw under-maintenance? boolean 204 +--rw maintenance-contact string 205 +--rw (parameter)? 206 | +--:(service-instance-parameter) 207 | +--rw service-instance-parameter 208 | +--rw service string 209 | +--rw instance-name string 210 +--ro health-score? union 211 +--ro symptoms-history-start? yang:date-and-time 212 +--rw symptoms 213 | +--ro symptom* [start-date-time id] 214 | +--ro id string 215 | +--ro health-score-weight? uint8 216 | +--ro description? string 217 | +--ro start-date-time yang:date-and-time 218 | +--ro stop-date-time? yang:date-and-time 219 +--rw dependencies 220 +--rw dependency* [type id] 221 +--rw type 222 | -> /subservices/subservice/type 223 +--rw id leafref 224 +--rw dependency-type? identityref 226 3.2. Concepts 228 The ietf-service-assurance YANG model assumes an identified number of 229 subservices, to be assured independently. A subservice is a feature 230 or a subpart of the network system that a given service instance 231 might depend on. Example of subservices include: 233 * DeviceHealthy: whether a device is healthy, and if not, what are 234 the symptoms. Potential symptoms are "CPU overloaded", "Out of 235 RAM", or "Out of TCAM". 237 * ConnectivityHealthy: given two IP addresses owned by two devices, 238 what is the quality of the connection between them. Potential 239 symptoms are "No route available" or "ECMP Imbalance". 241 The first example is a subservice representing a subpart of the 242 network system, while the second is a subservice representing a 243 feature of the network, In both cases, these subservices might depend 244 on other subservices, for instance, the connectivity might depend on 245 a subservice representing the routing mechanism and on a subservice 246 representing ECMP. 248 The status of each subservice contains a list of symptoms. Each 249 symptom is specified by a unique id and contains a health-score- 250 weight (the impact to the health score incurred by this symptom), a 251 label (text describing what the symptom is), and dates and times at 252 which the symptom was detected and stopped being detected. While the 253 unique id is sufficient as an unique key list, the start-date-time 254 second key help sorting and retrieving relevant symptoms. 256 The relation between the health score and the health-score-weight of 257 the currently active symptoms is not explicitly defined in this 258 draft. The only requirement is that a non-maximal score must be 259 explained by at least one symptom. A way to enforce that requirement 260 is to first detect symptoms and then compute the health score based 261 on the health-score-weight of the detected symptoms. As an example, 262 this computation could be to sum the health-score-weight of the 263 active symptoms, subtract that value from 100 and change the value to 264 0 if negative. The relation between health-score and health-score- 265 weight is left to the implementor (of an agent 266 [I-D.ietf-opsawg-service-assurance-architecture]). To consider for 267 implementing this relation: the health-score is mostly for humans, 268 the symptoms are what the closed loop automation can build on. 270 The assurance of a given service instance can be obtained by 271 composing the assurance of the subservices that it depends on, via 272 the dependency relations. 274 A subservice declaration MUST provide: 276 * A type: identity inheriting of the base identity for subservice, 278 * An id: string uniquely identifying the subservice among those with 279 the same identity, 281 * One or more parameters, which should be specified in an augmenting 282 model, as described in the next sections. 284 The type and id uniquely identify a given subservice. They are used 285 to indicate the dependencies. Dependencies have types as well. Two 286 types are specified in the model: 288 * Impacting: such a dependency indicates an impact on the health of 289 the dependent, 291 * Informational: such a dependency might explain why the dependent 292 has issues but does not impact its health. 294 To illustrate the difference between "impacting" and "informational", 295 consider the subservice InterfaceHealthy, representing a network 296 interface. If the device to which the network interface belongs goes 297 down, the network interface will transition to a down state as well. 298 Therefore, the dependency of InterfaceHealthy towards DeviceHealthy 299 is "impacting". On the other hand, as a the dependency towards the 300 ECMPLoad subservice, which checks that the load between ECMP remains 301 ce remains stable throughout time, is only "informational". Indeed, 302 services might be perfectly healthy even if the load distribution 303 between ECMP changed. However, such an instability might be a 304 relevant symptom for diagnosing the root cause of a problem. 306 Service instances MUST be modeled as a particular type of subservice 307 with two parameters, a type and an instance name. The type is the 308 name of the service defined in the network orchestrator, for instance 309 "point-to-point-l2vpn". The instance name is the name assigned to 310 the particular instance that we are assuring, for instance the name 311 of the customer using that instance. 313 The "under-maintenance" and "maintenance-contact" flags inhibit the 314 emission of symptoms for that subservice and subservices that depend 315 on them. See Section 3.7 of 316 [I-D.ietf-opsawg-service-assurance-architecture] for a more detailed 317 discussion. 319 By specifying service instances and their dependencies in terms of 320 subservices, one defines the whole assurance to apply for them. An 321 assurance agent supporting this model should then produce telemetry 322 in return with, for each subservice: a health-status indicating how 323 healthy the subservice is and when the subservice is not healthy, a 324 list of symptoms explaining why the subservice is not healthy. 326 3.3. YANG Module 328 file "ietf-service-assurance@2022-04-07.yang" 330 module ietf-service-assurance { 331 yang-version 1.1; 332 namespace "urn:ietf:params:xml:ns:yang:ietf-service-assurance"; 333 prefix sain; 335 import ietf-yang-types { 336 prefix yang; 337 reference 338 "RFC 6991: Common YANG Data Types"; 339 } 341 organization 342 "IETF OPSAWG Working Group"; 343 contact 344 "WG Web: 345 WG List: 346 Author: Benoit Claise 347 Author: Jean Quilbeuf "; 348 description 349 "This module defines objects for assuring network services based on 350 their decomposition into so-called subservices, according to the 351 SAIN (Service Assurance for Intent-based Networking) architecture. 353 The subservices hierarchically organised by dependencies constitute 354 an assurance graph. This module should be supported by an assurance 355 agent, able to interact with the devices in order to produce a 356 health status and symptoms for each subservice in the assurance 357 graph. 359 This module is intended for the following use cases: 360 * Assurance graph configuration: 361 - subservices: configure a set of subservices to assure, by 362 specifying their types and parameters. 363 - dependencies: configure the dependencies between the 364 subservices, along with their type. 365 * Assurance telemetry: export the health status of the subservices, 366 along with the observed symptoms. 368 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 369 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 370 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 371 are to be interpreted as described in BCP 14 (RFC 2119) 372 (RFC 8174) when, and only when, they appear in all 373 capitals, as shown here. 375 Copyright (c) 2022 IETF Trust and the persons identified as 376 authors of the code. All rights reserved. 378 Redistribution and use in source and binary forms, with or 379 without modification, is permitted pursuant to, and subject 380 to the license terms contained in, the Revised BSD License 381 set forth in Section 4.c of the IETF Trust's Legal Provisions 382 Relating to IETF Documents 383 (https://trustee.ietf.org/license-info). 385 This version of this YANG module is part of RFC XXXX; see the 386 RFC itself for full legal notices. "; 388 revision 2022-04-07 { 389 description 390 "Shorten prefix. Fix copyright. 391 Fix module description"; 392 reference 393 "RFC xxxx: YANG Modules for Service Assurance"; 394 } 395 revision 2022-01-04 { 396 description 397 "Explicitely model a missing value"; 398 reference 399 "RFC xxxx: YANG Modules for Service Assurance"; 400 } 401 revision 2021-06-28 { 402 description 403 "Made service-instance parameters mandatory."; 404 reference 405 "RFC xxxx: YANG Modules for Service Assurance"; 406 } 407 revision 2020-01-13 { 408 description 409 "Added the maintenance window concept."; 410 reference 411 "RFC xxxx: YANG Modules for Service Assurance"; 412 } 413 revision 2019-11-16 { 414 description 415 "Initial revision."; 416 reference 417 "RFC xxxx: YANG Modules for Service Assurance"; 418 } 420 identity subservice-idty { 421 description 422 "Root identity for all subservice types."; 423 } 425 identity service-instance-idty { 426 base subservice-idty; 427 description 428 "Identity representing a service instance."; 429 } 431 identity dependency-type { 432 description 433 "Base identity for representing dependency types."; 434 } 436 identity informational-dependency { 437 base dependency-type; 438 description 439 "Indicates that symptoms of the dependency might be of interest 440 for the dependent, but the status of the dependency should not 441 have any impact on the dependent."; 442 } 444 identity impacting-dependency { 445 base dependency-type; 446 description 447 "Indicates that the status of the dependency directly impacts the 448 status of the dependent."; 449 } 451 grouping symptom { 452 description 453 "Contains the list of symptoms for a specific subservice."; 454 leaf id { 455 type string; 456 description 457 "A unique identifier for the symptom."; 458 } 459 leaf health-score-weight { 460 type uint8 { 461 range "0 .. 100"; 462 } 463 description 464 "The weight to the health score incurred by this symptom. The 465 higher the value, the more of an impact this symptom has. If a 466 subservice health score is not 100, there must be at least one 467 symptom with a health score weight larger than 0."; 468 } 469 leaf description { 470 type string; 471 description 472 "Description of the symptom, i.e. text describing what the 473 symptom is, to be computer-consumable and be displayed on a 474 human interface. "; 475 } 476 leaf start-date-time { 477 type yang:date-and-time; 478 description 479 "Date and time at which the symptom was detected."; 480 } 481 leaf stop-date-time { 482 type yang:date-and-time; 483 description 484 "Date and time at which the symptom stopped being detected."; 485 } 486 } 488 grouping subservice-dependency { 489 description 490 "Represent a dependency to another subservice."; 491 leaf type { 492 type leafref { 493 path "/subservices/subservice/type"; 494 } 495 description 496 "The type of the subservice to refer to (e.g. DeviceHealthy)."; 497 } 498 leaf id { 499 type leafref { 500 path "/subservices/subservice[type=current()/../type]/id"; 501 } 502 description 503 "The identifier of the subservice to refer to."; 504 } 505 leaf dependency-type { 506 type identityref { 507 base dependency-type; 508 } 509 description 510 "Represents the type of dependency (i.e. informational, 511 impacting)."; 512 } 513 // Augment here to add parameters specific to a new dependency-type. 514 // For instance, a specific dependency type could keep symptom 515 // whose health-score-weight is larger than a given value. 516 } 518 leaf assurance-graph-version { 519 type yang:counter64; 520 config false; 521 mandatory true; 522 description 523 "The assurance graph version, which increases by 1 for each new 524 version, after the changes (dependencies and/or maintenance 525 windows parameters) are applied to the subservice(s)."; 526 } 527 leaf assurance-graph-last-change { 528 type yang:date-and-time; 529 config false; 530 mandatory true; 531 description 532 "Date and time at which the assurance graph last changed after the 533 changes (dependencies and/or maintenance windows parameters) are 534 applied to the subservice(s). These date and time must be more 535 recent or equal compared to the more recent value of any changed 536 subservices last-change"; 537 } 538 container subservices { 539 description 540 "Root container for the subservices."; 541 list subservice { 542 key "type id"; 543 description 544 "List of subservice configured."; 545 leaf type { 546 type identityref { 547 base subservice-idty; 548 } 549 description 550 "Name of the subservice, e.g. DeviceHealthy."; 551 } 552 leaf id { 553 type string; 554 description 555 "Unique identifier of the subservice instance, for each 556 type."; 557 } 558 leaf last-change { 559 type yang:date-and-time; 560 config false; 561 description 562 "Date and time at which the assurance graph for this 563 subservice instance last changed, i.e. dependencies and/or 564 maintenance windows parameters."; 565 } 566 leaf label { 567 type string; 568 config false; 569 description 570 "Label of the subservice, i.e. text describing what the 571 subservice is to be displayed on a human interface."; 572 } 573 leaf under-maintenance { 574 type boolean; 575 default "false"; 576 description 577 "An optional flag indicating whether this particular 578 subservice is under maintenance. Under this circumstance, the 579 subservice symptoms and the symptoms of its dependencies in 580 the assurance graph should not be taken into account. 581 Instead, the subservice should send a 'Under Maintenance' 582 single symptom. 584 The operator changing the under-maintenance value must set 585 the maintenance-contact variable. 587 When the subservice is not under maintenance any longer, the 588 under-maintenance flag must return to its default value and 589 the under-maintenance-owner variable deleted."; 590 } 591 leaf maintenance-contact { 592 when "../under-maintenance = 'true'"; 593 type string; 594 mandatory true; 595 description 596 "A string used to model an administratively assigned name of 597 the resource that changed the under-maintenance value to 598 'true'. 600 It is suggested that this name contain one or more of the 601 following: IP address, management station name, 602 network manager's name, location, or phone number. In some 603 cases the agent itself will be the owner of an entry. In 604 these cases, this string shall be set to a string starting 605 with 'monitor'."; 606 } 607 choice parameter { 608 description 609 "Specify the required parameters per subservice type."; 610 container service-instance-parameter { 611 when "derived-from-or-self(../type, 612 'sain:service-instance-idty')"; 613 description 614 "Specify the parameters of a service instance."; 615 leaf service { 616 type string; 617 mandatory true; 618 description 619 "Name of the service."; 620 } 621 leaf instance-name { 622 type string; 623 mandatory true; 624 description 625 "Name of the instance for that service."; 626 } 627 } 628 // Other modules can augment their own cases into here 629 } 630 leaf health-score { 631 type union { 632 type uint8 { 633 range "0 .. 100"; 634 } 635 type enumeration { 636 enum missing { 637 value -1; 638 description 639 "Explictly represent the fact that the health score is 640 missing. This could be used when metrics crucial to 641 establish the health score are not collected anymore."; 642 } 643 } 644 } 645 config false; 646 description 647 "Score value of the subservice health. A value of 100 means 648 that subservice is healthy. A value of 0 means that the 649 subservice is broken. A value between 0 and 100 means that 650 the subservice is degraded."; 651 } 652 leaf symptoms-history-start { 653 type yang:date-and-time; 654 config false; 655 description 656 "Date and time at which the symptoms history starts for this 657 subservice instance, either because the subservice instance 658 started at that date and time or because the symptoms before 659 that were removed due to a garbage collection process."; 660 } 661 container symptoms { 662 description 663 "Symptoms for the subservice."; 664 list symptom { 665 key "start-date-time id"; 666 config false; 667 description 668 "List of symptoms the subservice. While the start-date-time 669 key is not necessary per se, this would get the entries 670 sorted by start-date-time for easy consumption."; 671 uses symptom; 672 } 674 } 675 container dependencies { 676 description 677 "configure the dependencies between the subservices, along 678 with their types."; 679 list dependency { 680 key "type id"; 681 description 682 "List of soft dependencies of the subservice."; 683 uses subservice-dependency; 684 } 685 } 686 } 687 } 688 } 690 692 4. Subservice Extension: ietf-service-assurance-device YANG module 694 4.1. Tree View 696 The following tree diagram [RFC8340] provides an overview of the 697 ietf-service-assurance-device data model. 699 module: ietf-service-assurance-device 701 augment /sain:subservices/sain:subservice/sain:parameter: 702 +--rw parameters 703 +--rw device string 705 4.2. Complete Tree View 707 The following tree diagram [RFC8340] provides an overview of the 708 ietf-service-assurance and ietf-service-assurance-device data models. 710 module: ietf-service-assurance 711 +--ro assurance-graph-version yang:counter64 712 +--ro assurance-graph-last-change yang:date-and-time 713 +--rw subservices 714 +--rw subservice* [type id] 715 +--rw type identityref 716 +--rw id string 717 +--ro last-change? yang:date-and-time 718 +--ro label? string 719 +--rw under-maintenance? boolean 720 +--rw maintenance-contact string 721 +--rw (parameter)? 722 | +--:(service-instance-parameter) 723 | | +--rw service-instance-parameter 724 | | +--rw service string 725 | | +--rw instance-name string 726 | +--:(sain-device:parameters) 727 | +--rw sain-device:parameters 728 | +--rw sain-device:device string 729 +--ro health-score? union 730 +--ro symptoms-history-start? yang:date-and-time 731 +--rw symptoms 732 | +--ro symptom* [start-date-time id] 733 | +--ro id string 734 | +--ro health-score-weight? uint8 735 | +--ro description? string 736 | +--ro start-date-time yang:date-and-time 737 | +--ro stop-date-time? yang:date-and-time 738 +--rw dependencies 739 +--rw dependency* [type id] 740 +--rw type 741 | -> /subservices/subservice/type 742 +--rw id leafref 743 +--rw dependency-type? identityref 745 4.3. Concepts 747 As the number of subservices will grow over time, the YANG module is 748 designed to be extensible. A new subservice type requires the 749 precise specifications of its type and expected parameters. Let us 750 illustrate the example of the new DeviceHealthy subservice type. As 751 the name implies, it monitors and reports the device health, along 752 with some symptoms in case of degradation. 754 For our DeviceHealthy subservice definition, the new identity device- 755 idty is specified, as an inheritance from the base identity for 756 subservices. This indicates to the assurance agent that we are now 757 assuring the health of a device. 759 The typical parameter for the configuration of the DeviceHealthy 760 subservice is the name of the device that we want to assure. By 761 augmenting the parameter choice from ietf-service-assurance YANG 762 module for the case of the device-idty subservice type, this new 763 parameter is specified. 765 4.4. YANG Module 767 file "ietf-service-assurance-device@2022-04-07.yang" 769 module ietf-service-assurance-device { 770 yang-version 1.1; 771 namespace 772 "urn:ietf:params:xml:ns:yang:ietf-service-assurance-device"; 773 prefix sain-device; 775 import ietf-service-assurance { 776 prefix sain; 777 reference 778 "RFC xxxx: YANG Modules for Service Assurance"; 779 } 781 organization 782 "IETF OPSAWG Working Group"; 783 contact 784 "WG Web: 785 WG List: 786 Author: Benoit Claise 787 Author: Jean Quilbeuf "; 788 description 789 "This module extends the ietf-service-assurance module to add 790 support for the subservice DeviceHealthy. 792 Checks whether a network device is healthy. 794 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 795 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 796 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 797 are to be interpreted as described in BCP 14 (RFC 2119) 798 (RFC 8174) when, and only when, they appear in all 799 capitals, as shown here. 801 Copyright (c) 2022 IETF Trust and the persons identified as 802 authors of the code. All rights reserved. 804 Redistribution and use in source and binary forms, with or 805 without modification, is permitted pursuant to, and subject 806 to the license terms contained in, the Revised BSD License 807 set forth in Section 4.c of the IETF Trust's Legal Provisions 808 Relating to IETF Documents 809 (https://trustee.ietf.org/license-info). 810 This version of this YANG module is part of RFC XXXX; see the 811 RFC itself for full legal notices. "; 813 revision 2022-04-07 { 814 description 815 "Fix mandatory in augment error by moving when clause. 816 Shorten prefix. Fix module description. 817 Fix module description"; 818 reference 819 "RFC xxxx: YANG Modules for Service Assurance"; 820 } 821 revision 2021-06-28 { 822 description 823 "Renamed the container for parameters."; 824 reference 825 "RFC xxxx: YANG Modules for Service Assurance"; 826 } 827 revision 2020-01-13 { 828 description 829 "Added the maintenance window concept."; 830 reference 831 "RFC xxxx: YANG Modules for Service Assurance"; 832 } 833 revision 2019-11-16 { 834 description 835 "Initial revision."; 836 reference 837 "RFC xxxx: YANG Modules for Service Assurance"; 838 } 840 identity device-idty { 841 base sain:subservice-idty; 842 description 843 "Network Device is healthy."; 844 } 846 augment "/sain:subservices/sain:subservice/sain:parameter" { 847 when "derived-from-or-self(sain:type, 'device-idty')"; 848 description 849 "Specify the required parameters for a new subservice type"; 851 container parameters { 852 description 853 "Specify the required parameters for the device-idty 854 subservice type"; 855 leaf device { 856 type string; 857 mandatory true; 858 description 859 "The device to monitor."; 860 } 861 } 862 } 863 } 865 867 5. Subservice Extension: ietf-service-assurance-interface YANG module 869 5.1. Tree View 871 The following tree diagram [RFC8340] provides an overview of the 872 ietf-service-assurance-interface data model. 874 module: ietf-service-assurance-interface 876 augment /sain:subservices/sain:subservice/sain:parameter: 877 +--rw parameters 878 +--rw device string 879 +--rw interface string 881 5.2. Complete Tree View 883 The following tree diagram [RFC8340] provides an overview of the 884 ietf-service-assurance, ietf-service-assurance-device, and ietf- 885 service-assurance-interface data models. 887 module: ietf-service-assurance 888 +--ro assurance-graph-version yang:counter64 889 +--ro assurance-graph-last-change yang:date-and-time 890 +--rw subservices 891 +--rw subservice* [type id] 892 +--rw type identityref 893 +--rw id string 894 +--ro last-change? yang:date-and-time 895 +--ro label? string 896 +--rw under-maintenance? boolean 897 +--rw maintenance-contact string 898 +--rw (parameter)? 899 | +--:(service-instance-parameter) 900 | | +--rw service-instance-parameter 901 | | +--rw service string 902 | | +--rw instance-name string 903 | +--:(sain-interface:parameters) 904 | | +--rw sain-interface:parameters 905 | | +--rw sain-interface:device string 906 | | +--rw sain-interface:interface string 907 | +--:(sain-device:parameters) 908 | +--rw sain-device:parameters 909 | +--rw sain-device:device string 910 +--ro health-score? union 911 +--ro symptoms-history-start? yang:date-and-time 912 +--rw symptoms 913 | +--ro symptom* [start-date-time id] 914 | +--ro id string 915 | +--ro health-score-weight? uint8 916 | +--ro description? string 917 | +--ro start-date-time yang:date-and-time 918 | +--ro stop-date-time? yang:date-and-time 919 +--rw dependencies 920 +--rw dependency* [type id] 921 +--rw type 922 | -> /subservices/subservice/type 923 +--rw id leafref 924 +--rw dependency-type? identityref 926 5.3. Concepts 928 For our InterfaceHealthy subservice definition, the new interface- 929 idty is specified, as an inheritance from the base identity for 930 subservices. This indicates to the assurance agent that we are now 931 assuring the health of an interface. 933 The typical parameters for the configuration of the InterfaceHealthy 934 subservice are the name of the device and, on that specific device, a 935 specific interface. By augmenting the parameter choice from ietf- 936 service-assurance YANG module for the case of the interface-idty 937 subservice type, those two new parameters are specified. 939 5.4. YANG Module 941 file "ietf-service-assurance-interface@2022-04-07.yang" 943 module ietf-service-assurance-interface { 944 yang-version 1.1; 945 namespace 946 "urn:ietf:params:xml:ns:yang:ietf-service-assurance-interface"; 947 prefix sain-interface; 949 import ietf-service-assurance { 950 prefix sain; 951 reference 952 "RFC xxxx: YANG Modules for Service Assurance"; 953 } 955 organization 956 "IETF OPSAWG Working Group"; 957 contact 958 "WG Web: 959 WG List: 960 Author: Benoit Claise 961 Author: Jean Quilbeuf "; 962 description 963 "This module extends the ietf-service-assurance module to add 964 support for the subservice InterfaceHealthy. 966 Checks whether an interface is healthy. 968 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 969 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 970 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 971 are to be interpreted as described in BCP 14 (RFC 2119) 972 (RFC 8174) when, and only when, they appear in all 973 capitals, as shown here. 975 Copyright (c) 2022 IETF Trust and the persons identified as 976 authors of the code. All rights reserved. 977 Redistribution and use in source and binary forms, with or 978 without modification, is permitted pursuant to, and subject 979 to the license terms contained in, the Revised BSD License 980 set forth in Section 4.c of the IETF Trust's Legal Provisions 981 Relating to IETF Documents 982 (https://trustee.ietf.org/license-info). 984 This version of this YANG module is part of RFC XXXX; see the 985 RFC itself for full legal notices. "; 987 revision 2022-04-07 { 988 description 989 "Fix mandatory in augment error by moving when clause. 990 Shorten prefix. Fix module description. 991 Fix module description"; 992 reference 993 "RFC xxxx: YANG Modules for Service Assurance"; 994 } 995 revision 2021-06-28 { 996 description 997 "Regroup parameters in a container."; 998 reference 999 "RFC xxxx: YANG Modules for Service Assurance"; 1000 } 1001 revision 2020-01-13 { 1002 description 1003 "Initial revision."; 1004 reference 1005 "RFC xxxx: YANG Modules for Service Assurance"; 1006 } 1008 identity interface-idty { 1009 base sain:subservice-idty; 1010 description 1011 "Checks whether an interface is healthy."; 1012 } 1014 augment "/sain:subservices/sain:subservice/sain:parameter" { 1015 when "derived-from-or-self(sain:type, 'interface-idty')"; 1016 description 1017 "Specify the required parameters for the interface-idty 1018 subservice type"; 1019 container parameters { 1020 description 1021 "Required parameters for the interface-idty subservice 1022 type"; 1023 leaf device { 1024 type string; 1025 mandatory true; 1026 description 1027 "Device supporting the interface."; 1028 } 1029 leaf interface { 1030 type string; 1031 mandatory true; 1032 description 1033 "Name of the interface."; 1034 } 1035 } 1036 } 1037 } 1039 1041 6. Vendor-specific Subservice Extension: example-service-assurance- 1042 device-acme YANG module 1044 6.1. Tree View 1046 The following tree diagram [RFC8340] provides an overview of the 1047 example-service-assurance-device-acme data model. 1049 module: example-service-assurance-device-acme 1051 augment /sain:subservices/sain:subservice/sain:parameter: 1052 +--rw parameters 1053 +--rw device string 1054 +--rw acme-specific-parameter string 1056 6.2. Complete Tree View 1058 The following tree diagram [RFC8340] provides an overview of the 1059 ietf-service-assurance, ietf-service-assurance-device, and example- 1060 service-assurance-device-acme data models. 1062 module: ietf-service-assurance 1063 +--ro assurance-graph-version yang:counter64 1064 +--ro assurance-graph-last-change yang:date-and-time 1065 +--rw subservices 1066 +--rw subservice* [type id] 1067 +--rw type identityref 1068 +--rw id string 1069 +--ro last-change? 1070 | yang:date-and-time 1071 +--ro label? string 1072 +--rw under-maintenance? boolean 1073 +--rw maintenance-contact string 1074 +--rw (parameter)? 1075 | +--:(service-instance-parameter) 1076 | | +--rw service-instance-parameter 1077 | | +--rw service string 1078 | | +--rw instance-name string 1079 | +--:(sain-device:parameters) 1080 | | +--rw sain-device:parameters 1081 | | +--rw sain-device:device string 1082 | +--:(example-device-acme:parameters) 1083 | | +--rw example-device-acme:parameters 1084 | | +--rw example-device-acme:device 1085 | | | string 1086 | | +--rw example-device-acme:acme-specific-parameter 1087 | | string 1088 | +--:(sain-interface:parameters) 1089 | +--rw sain-interface:parameters 1090 | +--rw sain-interface:device string 1091 | +--rw sain-interface:interface string 1092 +--ro health-score? union 1093 +--ro symptoms-history-start? 1094 | yang:date-and-time 1095 +--rw symptoms 1096 | +--ro symptom* [start-date-time id] 1097 | +--ro id string 1098 | +--ro health-score-weight? uint8 1099 | +--ro description? string 1100 | +--ro start-date-time yang:date-and-time 1101 | +--ro stop-date-time? yang:date-and-time 1102 +--rw dependencies 1103 +--rw dependency* [type id] 1104 +--rw type 1105 | -> /subservices/subservice/type 1106 +--rw id leafref 1107 +--rw dependency-type? identityref 1109 6.3. Concepts 1111 Under some circumstances, vendor-specific subservice types might be 1112 required. As an example of this vendor-specific implementation, this 1113 section shows how to augment the ietf-service-assurance-device module 1114 to add support for the subservice DeviceHealthy, specific to the ACME 1115 Corporation. The new parameter is acme-specific-parameter. 1117 6.4. YANG Module 1119 module example-service-assurance-device-acme { 1120 yang-version 1.1; 1121 namespace "urn:example:example-service-assurance-device-acme"; 1122 prefix example-device-acme; 1124 import ietf-service-assurance { 1125 prefix sain; 1126 reference 1127 "RFC xxxx: YANG Modules for Service Assurance"; 1128 } 1129 import ietf-service-assurance-device { 1130 prefix sain-device; 1131 reference 1132 "RFC xxxx: YANG Modules for Service Assurance"; 1133 } 1135 organization 1136 "IETF OPSAWG Working Group"; 1137 contact 1138 "WG Web: 1139 WG List: 1140 Author: Benoit Claise 1141 Author: Jean Quilbeuf "; 1142 description 1143 "This module extends the ietf-service-assurance-device module to 1144 add support for the subservice DeviceHealthy, specific to the ACME 1145 Corporation. 1147 ACME Network Device is healthy. 1149 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 1150 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 1151 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 1152 are to be interpreted as described in BCP 14 (RFC 2119) 1153 (RFC 8174) when, and only when, they appear in all 1154 capitals, as shown here. 1156 Copyright (c) 2022 IETF Trust and the persons identified as 1157 authors of the code. All rights reserved. 1159 Redistribution and use in source and binary forms, with or 1160 without modification, is permitted pursuant to, and subject 1161 to the license terms contained in, the Revised BSD License 1162 set forth in Section 4.c of the IETF Trust's Legal Provisions 1163 Relating to IETF Documents 1164 (https://trustee.ietf.org/license-info). 1166 This version of this YANG module is part of RFC XXXX; see the 1167 RFC itself for full legal notices. "; 1169 revision 2022-04-07 { 1170 description 1171 "Fix mandatory in augment error by moving when clause. 1172 Shorten prefix. 1173 Fix module description"; 1174 reference 1175 "RFC xxxx: YANG Modules for Service Assurance"; 1176 } 1177 revision 2021-06-28 { 1178 description 1179 "Renamed the parameters container."; 1180 reference 1181 "RFC xxxx: YANG Modules for Service Assurance"; 1182 } 1183 revision 2020-01-13 { 1184 description 1185 "Added the maintenance window concept."; 1186 reference 1187 "RFC xxxx: YANG Modules for Service Assurance"; 1188 } 1189 revision 2019-11-16 { 1190 description 1191 "Initial revision."; 1192 reference 1193 "RFC xxxx: YANG Modules for Service Assurance"; 1194 } 1196 identity device-acme-idty { 1197 base sain-device:device-idty; 1198 description 1199 "Network Device is healthy."; 1200 } 1202 augment "/sain:subservices/sain:subservice/sain:parameter" { 1203 when "derived-from-or-self(sain:type, 'device-acme-idty')"; 1204 description 1205 "Specify the required parameters for a new subservice type"; 1206 container parameters { 1207 description 1208 "Specify the required parameters for the device-acme-idty 1209 subservice type"; 1210 leaf device { 1211 type string; 1212 mandatory true; 1213 description 1214 "The device to monitor."; 1215 } 1216 leaf acme-specific-parameter { 1217 type string; 1218 mandatory true; 1219 description 1220 "The ACME Corporation sepcific parameter."; 1221 } 1222 } 1223 } 1224 } 1226 7. Further Extensions: IP Connectivity and IS-IS subservices 1228 In this section, we provide two additional YANG models to completely 1229 cover the example from Figure 2 in 1230 [I-D.ietf-opsawg-service-assurance-architecture]. The complete 1231 normalization of these modules is to be done in future work. 1233 7.1. IP Connectivity Tree View 1235 That subservice represents the unicast connectivity between two IP 1236 addresses located on to different devices. Such a subservice could 1237 report symptoms such as "No route found". The following tree diagram 1238 [RFC8340] provides an overview of the example-service-assurance-ip- 1239 connectivity data model. 1241 module: example-service-assurance-ip-connectivity 1243 augment /sain:subservices/sain:subservice/sain:parameter: 1244 +--rw parameters 1245 +--rw device1 string 1246 +--rw address1 inet:ip-address 1247 +--rw device2 string 1248 +--rw address2 inet:ip-address 1250 To specify the connectivity that we are interested in, we specify two 1251 IP addresses and two devices. The subservice assures that the 1252 connectivity between IP address 1 on device 1 and IP address 2 on 1253 device 2 is healthy. 1255 7.2. IS-IS Tree View 1257 The following tree diagram [RFC8340] provides an overview of the 1258 example-service-assurance-is-is data model. 1260 module: example-service-assurance-is-is 1262 augment /sain:subservices/sain:subservice/sain:parameter: 1263 +--rw parameters 1264 +--rw instance-name string 1266 The parameter of this subservice is the name of the IS-IS instance to 1267 assure. 1269 7.3. Global Tree View 1271 The following tree diagram [RFC8340] provides an overview of the 1272 ietf-service-assurance, ietf-service-assurance-device, example- 1273 service-assurance-device-acme, example-service-assurance-ip- 1274 connectivity and example-service-assurance-is-is data models. 1276 module: ietf-service-assurance 1277 +--ro assurance-graph-version yang:counter64 1278 +--ro assurance-graph-last-change yang:date-and-time 1279 +--rw subservices 1280 +--rw subservice* [type id] 1281 +--rw type identityref 1282 +--rw id string 1283 +--ro last-change? 1284 | yang:date-and-time 1285 +--ro label? string 1286 +--rw under-maintenance? boolean 1287 +--rw maintenance-contact string 1288 +--rw (parameter)? 1289 | +--:(service-instance-parameter) 1290 | | +--rw service-instance-parameter 1291 | | +--rw service string 1292 | | +--rw instance-name string 1293 | +--:(example-ip-connectivity:parameters) 1294 | | +--rw example-ip-connectivity:parameters 1295 | | +--rw example-ip-connectivity:device1 string 1296 | | +--rw example-ip-connectivity:address1 1297 | | | inet:ip-address 1298 | | +--rw example-ip-connectivity:device2 string 1299 | | +--rw example-ip-connectivity:address2 1300 | | inet:ip-address 1301 | +--:(example-is-is:parameters) 1302 | | +--rw example-is-is:parameters 1303 | | +--rw example-is-is:instance-name string 1304 | +--:(sain-device:parameters) 1305 | | +--rw sain-device:parameters 1306 | | +--rw sain-device:device string 1307 | +--:(example-device-acme:parameters) 1308 | | +--rw example-device-acme:parameters 1309 | | +--rw example-device-acme:device 1310 | | | string 1311 | | +--rw example-device-acme:acme-specific-parameter 1312 | | string 1313 | +--:(sain-interface:parameters) 1314 | +--rw sain-interface:parameters 1315 | +--rw sain-interface:device string 1316 | +--rw sain-interface:interface string 1317 +--ro health-score? union 1318 +--ro symptoms-history-start? 1319 | yang:date-and-time 1320 +--rw symptoms 1321 | +--ro symptom* [start-date-time id] 1322 | +--ro id string 1323 | +--ro health-score-weight? uint8 1324 | +--ro description? string 1325 | +--ro start-date-time yang:date-and-time 1326 | +--ro stop-date-time? yang:date-and-time 1327 +--rw dependencies 1328 +--rw dependency* [type id] 1329 +--rw type 1330 | -> /subservices/subservice/type 1331 +--rw id leafref 1332 +--rw dependency-type? identityref 1334 7.4. IP Connectivity YANG Module 1336 module example-service-assurance-ip-connectivity { 1337 yang-version 1.1; 1338 namespace "urn:example:example-service-assurance-ip-connectivity"; 1339 prefix example-ip-connectivity; 1341 import ietf-inet-types { 1342 prefix inet; 1343 reference 1344 "RFC 6991: Common YANG Data Types"; 1345 } 1346 import ietf-service-assurance { 1347 prefix sain; 1348 reference 1349 "RFC xxxx: YANG Modules for Service Assurance"; 1350 } 1352 organization 1353 "IETF OPSAWG Working Group"; 1354 contact 1355 "WG Web: 1356 WG List: 1357 Author: Benoit Claise 1358 Author: Jean Quilbeuf "; 1359 description 1360 "This example module extends the ietf-service-assurance module to 1361 add support for the subservice ip-connectivity. 1363 Checks whether the ip connectivity between two ip addresses 1364 belonging to two network devices is healthy. 1366 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 1367 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 1368 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 1369 are to be interpreted as described in BCP 14 (RFC 2119) 1370 (RFC 8174) when, and only when, they appear in all 1371 capitals, as shown here. 1373 Copyright (c) 2022 IETF Trust and the persons identified as 1374 authors of the code. All rights reserved. 1375 Redistribution and use in source and binary forms, with or 1376 without modification, is permitted pursuant to, and subject 1377 to the license terms contained in, the Revised BSD License 1378 set forth in Section 4.c of the IETF Trust's Legal Provisions 1379 Relating to IETF Documents 1380 (https://trustee.ietf.org/license-info). 1382 This version of this YANG module is part of RFC XXXX; see the 1383 RFC itself for full legal notices. "; 1385 revision 2022-04-07 { 1386 description 1387 "Fix mandatory in augment error by moving when clause. 1388 Shorten prefix. Fix module description. 1389 Fix module description"; 1390 reference 1391 "RFC xxxx: YANG Modules for Service Assurance"; 1393 } 1394 revision 2021-06-28 { 1395 description 1396 "Initial revision."; 1397 reference 1398 "RFC xxxx: YANG Modules for Service Assurance"; 1399 } 1401 identity ip-connectivity-idty { 1402 base sain:subservice-idty; 1403 description 1404 "Checks connectivity between two IP addresses."; 1405 } 1407 augment "/sain:subservices/sain:subservice/sain:parameter" { 1408 when "derived-from-or-self(sain:type, 'ip-connectivity-idty')"; 1409 description 1410 "Specify the required parameters for the ip-connectivity-idty 1411 subservice type"; 1412 container parameters { 1413 description 1414 "Required parameters for the ip-connectivity-idty 1415 subservice type"; 1416 leaf device1 { 1417 type string; 1418 mandatory true; 1419 description 1420 "Device at the first end of the connection."; 1421 } 1422 leaf address1 { 1423 type inet:ip-address; 1424 mandatory true; 1425 description 1426 "Address at the first end of the connection."; 1427 } 1428 leaf device2 { 1429 type string; 1430 mandatory true; 1431 description 1432 "Device at the second end of the connection."; 1433 } 1434 leaf address2 { 1435 type inet:ip-address; 1436 mandatory true; 1437 description 1438 "Address at the second end of the connection."; 1439 } 1440 } 1442 } 1443 } 1445 7.5. IS-IS YANG Module 1447 module example-service-assurance-is-is { 1448 yang-version 1.1; 1449 namespace "urn:example:example-service-assurance-is-is"; 1450 prefix example-is-is; 1452 import ietf-service-assurance { 1453 prefix sain; 1454 reference 1455 "RFC xxxx: YANG Modules for Service Assurance"; 1456 } 1458 organization 1459 "IETF OPSAWG Working Group"; 1460 contact 1461 "WG Web: 1462 WG List: 1463 Author: Benoit Claise 1464 Author: Jean Quilbeuf "; 1465 description 1466 "This module extends the ietf-service-assurance module to 1467 add support for the subservice is-is. 1469 Checks whether an IS-IS instance is healthy. 1471 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 1472 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 1473 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 1474 are to be interpreted as described in BCP 14 (RFC 2119) 1475 (RFC 8174) when, and only when, they appear in all 1476 capitals, as shown here. 1478 Copyright (c) 2022 IETF Trust and the persons identified as 1479 authors of the code. All rights reserved. 1481 Redistribution and use in source and binary forms, with or 1482 without modification, is permitted pursuant to, and subject 1483 to the license terms contained in, the Revised BSD License 1484 set forth in Section 4.c of the IETF Trust's Legal Provisions 1485 Relating to IETF Documents 1486 (https://trustee.ietf.org/license-info). 1487 This version of this YANG module is part of RFC XXXX; see the 1488 RFC itself for full legal notices. "; 1490 revision 2022-04-07 { 1491 description 1492 "Fix mandatory in augment error by moving when clause. 1493 Shorten prefix. Fix module description. 1494 Fix module description"; 1495 reference 1496 "RFC xxxx: YANG Modules for Service Assurance"; 1497 } 1498 revision 2021-06-28 { 1499 description 1500 "Initial revision."; 1501 reference 1502 "RFC xxxx: YANG Modules for Service Assurance"; 1503 } 1505 identity is-is-idty { 1506 base sain:subservice-idty; 1507 description 1508 "Health of IS-IS routing protocol."; 1509 } 1511 augment "/sain:subservices/sain:subservice/sain:parameter" { 1512 when "derived-from-or-self(sain:type, 'is-is-idty')"; 1513 description 1514 "Specify the required parameters for a new subservice 1515 type"; 1516 container parameters { 1517 description 1518 "Specify the required parameters for the IS-IS subservice 1519 type"; 1520 leaf instance-name { 1521 type string; 1522 mandatory true; 1523 description 1524 "The instance to monitor."; 1525 } 1526 } 1527 } 1528 } 1530 8. Guidelines for Specific Subservice Extension 1532 The base YANG module defined in Section 3.3 only defines a single 1533 type of subservices that represent service instances. As explained 1534 above, this model is meant to be augmented so that a variety of 1535 subservices can be used in the assurance graph. In this section, we 1536 propose some guidelines in order to build theses extensions. 1538 First, the specific subservice must be given an adequate unique short 1539 name that will be used to form longer names (e.g. module name, prefix 1540 ...) appearing in the YANG module. The short name identifies the 1541 type of subpart of feature that the subservice will represent, for 1542 instance if the subservice will assure the health of a network 1543 interface then "interface" is an adequate short name. If the 1544 subservice will assure the IS-IS routing protocol, then "is-is" is an 1545 adequate short name. The short name must be in kebab-case. 1547 In this section, by subservice YANG module, we mean "YANG module that 1548 extends ietf-service-assurance in order to define a specific 1549 subservice". 1551 8.1. Module Name 1553 For subservice YANG modules vetted by the IETF, the module name 1554 should be "ietf-service-assurance-" followed by the short name. For 1555 instance, "ietf-service-assurance-interface" or "ietf-service- 1556 assurance-is-is". 1558 For subservice YANG module that are directly provided by vendors, we 1559 propose that they use the company in the prefix. For example, the 1560 prefix for the company "acme" would be "acme-assurance-" and the YANG 1561 modules would be "acme-assurance-interface", "acme-assurance-is-is", 1562 etc. 1564 8.2. Module Namespace 1566 For subservice YANG modules vetted by the IETF, the module namespace 1567 should be "urn:ietf:params:xml:ns:yang:ietf-service-assurance-" 1568 followed by the short name. For instance, 1569 "urn:ietf:params:xml:ns:yang:ietf-service-assurance-interface" or 1570 "urn:ietf:params:xml:ns:yang:example-service-assurance-is-is". 1572 For subservice YANG module that are directly provided by vendors, a 1573 similar pattern can be used with the prefix being a namespace 1574 controlled by the vendor. 1576 8.3. Module Prefix 1578 For subservice YANG modules vetted by the IETF, the module prefix 1579 should be "sain-" followed by the short name. For instance, "sain- 1580 interface" or "sain-is-is". 1582 For subservice YANG module that are directly provided by vendors, the 1583 same pattern can be used provided it does not conflict with an 1584 imported prefix. 1586 8.4. Subservice Specific Identity 1588 Each augment specific to a subservice must define an identity 1589 representing the type of subpart or features of the network system 1590 that are assured by the subservice. As required in the "ietf- 1591 service-assurance" module (see Section 3.3), that identity must be 1592 based on the "subservice-idty" identity. 1594 For subservice YANG modules vetted by the IETF, the subservice 1595 specific identity should be the short name of the subservice followed 1596 by "-idty". For instance, "interface-idty" or "is-is-identity". 1598 For subservice YANG module that are directly provided by vendors, the 1599 same pattern can be used. 1601 8.5. Parameters 1603 For subservice YANG modules vetted by the IETF, the parameters 1604 specific to the subservice should be placed in a container named 1605 "parameters". That container must be used to augment the "parameter" 1606 choice from the module "ietf-service-assurance" (see Section 3.3 and 1607 that augment must be guarded so that it is effective only for 1608 subservice instance whose type is the subservice specific identity 1609 from Section 8.4. 1611 For subservice YANG module that are directly provided by vendors, the 1612 same pattern can be used. 1614 9. Security Considerations 1616 The YANG module specified in this document defines a schema for data 1617 that is designed to be accessed via network management protocols such 1618 as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer 1619 is the secure transport layer, and the mandatory-to-implement secure 1620 transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer 1621 is HTTPS, and the mandatory-to-implement secure transport is TLS 1622 [RFC8446]. 1624 The Network Configuration Access Control Model (NACM) [RFC8341] 1625 provides the means to restrict access for particular NETCONF or 1626 RESTCONF users to a preconfigured subset of all available NETCONF or 1627 RESTCONF protocol operations and content. 1629 There are a number of data nodes defined in this YANG module that are 1630 writable/ creatable/deletable (i.e., config true, which is the 1631 default). These data nodes may be considered sensitive or vulnerable 1632 in some network environments. Write operations (e.g., edit-config) 1633 to these data nodes without proper protection can have a negative 1634 effect on network operations. These are the subtrees and data nodes 1635 and their sensitivity/vulnerability: 1637 * /subservices/subservice/type 1639 * /subservices/subservice/id 1641 * /subservices/subservice/under-maintenance 1643 * /subservices/subservice/maintenance-contact 1645 10. IANA Considerations 1647 10.1. The IETF XML Registry 1649 This document registers two URIs in the IETF XML registry [RFC3688]. 1650 Following the format in [RFC3688], the following registrations are 1651 requested: 1653 URI: urn:ietf:params:xml:ns:yang:ietf-service-assurance 1654 Registrant Contact: The NETCONF WG of the IETF. 1655 XML: N/A, the requested URI is an XML namespace. 1657 URI: urn:ietf:params:xml:ns:yang:ietf-service-assurance-device 1658 Registrant Contact: The NETCONF WG of the IETF. 1659 XML: N/A, the requested URI is an XML namespace. 1661 URI: urn:ietf:params:xml:ns:yang:ietf-service-assurance-interface 1662 Registrant Contact: The NETCONF WG of the IETF. 1663 XML: N/A, the requested URI is an XML namespace. 1665 10.2. The YANG Module Names Registry 1667 This document registers three YANG modules in the YANG Module Names 1668 registry [RFC7950]. Following the format in [RFC7950], the the 1669 following registrations are requested: 1671 name: ietf-service-assurance 1672 namespace: urn:ietf:params:xml:ns:yang:ietf-service-assurance 1673 prefix: inc 1674 reference: RFC XXXX 1676 name: ietf-service-assurance-device 1677 namespace: urn:ietf:params:xml:ns:yang:ietf-service-assurance-device 1678 prefix: inc 1679 reference: RFC XXXX 1681 name: ietf-service-assurance-interface 1682 namespace: urn:ietf:params:xml:ns:yang:ietf-service-assurance-interface 1683 prefix: inc 1684 reference: RFC XXXX 1686 11. Open Issues 1688 -None 1690 12. References 1692 12.1. Normative References 1694 [I-D.ietf-opsawg-service-assurance-architecture] 1695 Claise, B.C., Quilbeuf, J.Q., Lopez, D.L., Voyer, D.V., 1696 and T.A. Arumugam, "draft-claise-opsawg-service-assurance- 1697 architecture", 2020. 1699 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1700 and A. Bierman, Ed., "Network Configuration Protocol 1701 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1702 . 1704 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 1705 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 1706 . 1708 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1709 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1710 . 1712 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1713 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1714 . 1716 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 1717 Access Control Model", STD 91, RFC 8341, 1718 DOI 10.17487/RFC8341, March 2018, 1719 . 1721 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 1722 and R. Wilton, "Network Management Datastore Architecture 1723 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 1724 . 1726 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 1727 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 1728 . 1730 12.2. Informative References 1732 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1733 Requirement Levels", BCP 14, RFC 2119, 1734 DOI 10.17487/RFC2119, March 1997, 1735 . 1737 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1738 DOI 10.17487/RFC3688, January 2004, 1739 . 1741 [RFC7895] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module 1742 Library", RFC 7895, DOI 10.17487/RFC7895, June 2016, 1743 . 1745 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1746 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1747 May 2017, . 1749 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 1750 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 1751 . 1753 Appendix A. Example of YANG instances 1755 This section contains examples of YANG instances that conform to the 1756 YANG modules. The validity of these data instances has been checked 1757 using yangson (https://yangson.labs.nic.cz/). Yangson requires a 1758 YANG library [RFC7895] to define the complete model against which the 1759 data instance must be validated. We provide in Appendix B the JSON 1760 library file, named "ietf-service-assurance-library.json", that we 1761 used for validation. 1763 We provide below the contents of the file 1764 "example_configuration_instance.json" which contains the 1765 configuration data that models the Figure 2 of 1766 [I-D.ietf-opsawg-service-assurance-architecture]. The instance can 1767 be validated with yangson by using the invocation "yangson -v 1768 example_configuration_instance.json ietf-service-assurance- 1769 library.json", assuming all the files (YANG and JSON) defined in this 1770 draft reside in the current folder. 1772 { 1773 "ietf-service-assurance:subservices": { 1774 "subservice": [ 1775 { 1776 "type": "service-instance-idty", 1777 "id": "simple-tunnel/example", 1778 "service-instance-parameter": { 1779 "service": "simple-tunnel", 1780 "instance-name": "example" 1781 }, 1782 "dependencies": { 1783 "dependency": [ 1784 { 1785 "type": "ietf-service-assurance-interface:interface-idty", 1786 "id": "interface/peer1/tunnel0", 1787 "dependency-type": "impacting-dependency" 1788 }, 1789 { 1790 "type": "ietf-service-assurance-interface:interface-idty", 1791 "id": "interface/peer2/tunnel9", 1792 "dependency-type": "impacting-dependency" 1793 }, 1794 { 1795 "type": 1796 "example-service-assurance-ip-connectivity:ip-connectivity-idty", 1797 "id": "connectivity/peer1/2001:db8::1/peer2/2001:db8::2", 1798 "dependency-type": "impacting-dependency" 1799 } 1800 ] 1801 } 1802 }, 1803 { 1804 "type": 1805 "example-service-assurance-ip-connectivity:ip-connectivity-idty", 1806 "id": "connectivity/peer1/2001:db8::1/peer2/2001:db8::2", 1807 "example-service-assurance-ip-connectivity:parameters": { 1808 "device1": "Peer1", 1809 "address1": "2001:db8::1", 1810 "device2": "Peer2", 1811 "address2": "2001:db8::2" 1812 }, 1813 "dependencies": { 1814 "dependency": [ 1815 { 1816 "type": "ietf-service-assurance-interface:interface-idty", 1817 "id": "interface/peer1/physical0", 1818 "dependency-type": "impacting-dependency" 1819 }, 1820 { 1821 "type": "ietf-service-assurance-interface:interface-idty", 1822 "id": "interface/peer2/physical5", 1823 "dependency-type": "impacting-dependency" 1824 }, 1825 { 1826 "type": "example-service-assurance-is-is:is-is-idty", 1827 "id": "is-is/instance1", 1828 "dependency-type": "impacting-dependency" 1829 } 1830 ] 1831 } 1832 }, 1833 { 1834 "type": "example-service-assurance-is-is:is-is-idty", 1835 "id": "is-is/instance1", 1836 "example-service-assurance-is-is:parameters": { 1837 "instance-name": "instance1" 1838 } 1839 }, 1840 { 1841 "type": "ietf-service-assurance-interface:interface-idty", 1842 "id": "interface/peer1/tunnel0", 1843 "ietf-service-assurance-interface:parameters": { 1844 "device": "Peer1", 1845 "interface": "tunnel0" 1846 }, 1847 "dependencies": { 1848 "dependency": [ 1849 { 1850 "type": "ietf-service-assurance-interface:interface-idty", 1851 "id": "interface/peer1/physical0", 1852 "dependency-type": "impacting-dependency" 1853 } 1854 ] 1855 } 1856 }, 1857 { 1858 "type": "ietf-service-assurance-interface:interface-idty", 1859 "id": "interface/peer1/physical0", 1860 "ietf-service-assurance-interface:parameters": { 1861 "device": "Peer1", 1862 "interface": "physical0" 1863 }, 1864 "dependencies": { 1865 "dependency": [ 1866 { 1867 "type": "ietf-service-assurance-device:device-idty", 1868 "id": "interface/peer1", 1869 "dependency-type": "impacting-dependency" 1870 } 1871 ] 1872 } 1873 }, 1874 { 1875 "type": "ietf-service-assurance-device:device-idty", 1876 "id": "interface/peer1", 1877 "ietf-service-assurance-device:parameters": { 1878 "device": "Peer1" 1879 } 1880 }, 1881 { 1882 "type": "ietf-service-assurance-interface:interface-idty", 1883 "id": "interface/peer2/tunnel9", 1884 "ietf-service-assurance-interface:parameters": { 1885 "device": "Peer2", 1886 "interface": "tunnel9" 1887 }, 1888 "dependencies": { 1889 "dependency": [ 1890 { 1891 "type": "ietf-service-assurance-interface:interface-idty", 1892 "id": "interface/peer2/physical5", 1893 "dependency-type": "impacting-dependency" 1894 } 1895 ] 1896 } 1897 }, 1898 { 1899 "type": "ietf-service-assurance-interface:interface-idty", 1900 "id": "interface/peer2/physical5", 1901 "ietf-service-assurance-interface:parameters": { 1902 "device": "Peer2", 1903 "interface": "physical5" 1904 }, 1905 "dependencies": { 1906 "dependency": [ 1907 { 1908 "type": "ietf-service-assurance-device:device-idty", 1909 "id": "interface/peer2", 1910 "dependency-type": "impacting-dependency" 1911 } 1912 ] 1913 } 1914 }, 1915 { 1916 "type": "ietf-service-assurance-device:device-idty", 1917 "id": "interface/peer2", 1918 "ietf-service-assurance-device:parameters": { 1919 "device": "Peer2" 1920 } 1921 } 1922 ] 1923 } 1924 } 1926 Appendix B. YANG Library for Service Assurance 1928 This section provides the JSON encoding of the YANG library [RFC7895] 1929 listing all modules defined in this draft and their dependencies. 1930 This library can be used to validate data instances using yangson, as 1931 explained in the previous section. 1933 { 1934 "ietf-yang-library:modules-state": { 1935 "module-set-id": "ietf-service-assurance@2022-04-07", 1936 "module": [ 1937 { 1938 "name": "ietf-service-assurance", 1939 "namespace": 1940 "urn:ietf:params:xml:ns:yang:ietf-service-assurance", 1941 "revision": "2022-04-07", 1942 "conformance-type": "implement" 1943 }, 1944 { 1945 "name": "ietf-service-assurance-device", 1946 "namespace": 1947 "urn:ietf:params:xml:ns:yang:ietf-service-assurance-device", 1948 "revision": "2022-04-07", 1949 "conformance-type": "implement" 1950 }, 1951 { 1952 "name": "ietf-service-assurance-interface", 1953 "namespace": 1954 "urn:ietf:params:xml:ns:yang:ietf-service-assurance-interface", 1955 "revision": "2022-04-07", 1956 "conformance-type": "implement" 1957 }, 1958 { 1959 "name": "example-service-assurance-device-acme", 1960 "namespace": 1961 "urn:example:example-service-assurance-device-acme", 1962 "revision": "2022-04-07", 1963 "conformance-type": "implement" 1964 }, 1965 { 1966 "name": "example-service-assurance-is-is", 1967 "namespace": "urn:example:example-service-assurance-is-is", 1968 "revision": "2022-04-07", 1969 "conformance-type": "implement" 1970 }, 1971 { 1972 "name": "example-service-assurance-ip-connectivity", 1973 "namespace": 1974 "urn:example:example-service-assurance-ip-connectivity", 1975 "revision": "2022-04-07", 1976 "conformance-type": "implement" 1977 }, 1978 { 1979 "name": "ietf-yang-types", 1980 "namespace": "urn:ietf:params:xml:ns:yang:ietf-yang-types", 1981 "revision": "2021-04-14", 1982 "conformance-type": "import" 1983 }, 1984 { 1985 "name": "ietf-inet-types", 1986 "namespace": "urn:ietf:params:xml:ns:yang:ietf-inet-types", 1987 "revision": "2021-02-22", 1988 "conformance-type": "import" 1989 } 1990 ] 1991 } 1992 } 1994 Appendix C. Changes between revisions 1996 v03 - v04 1998 * Fix YANG errors 1999 * Change is-is and ip-connectivity subservices from ietf to example. 2001 * Mention that models are NMDA compliant 2003 * Fix typos, reformulate for clarity 2005 v02 - v03 2007 * Change counter32 to counter64 to avoid resetting too frequently 2009 * Explain why relation between health-score and symptom's health- 2010 score-weight is not defined and how it could be defined 2012 v01 - v02 2014 * Explicitly represent the fact that the health-score could not be 2015 computed (value -1) 2017 v00 - v01 2019 * Added needed subservice to model example from architecture draft 2021 * Added guideline section for naming models 2023 * Added data instance examples and validation procedure 2025 * Added the "parameters" container in the interface YANG module to 2026 correct a bug. 2028 Acknowledgements 2030 The authors would like to thank Jan Lindblad for his help during the 2031 design of these YANG modules. The authors would like to thank 2032 Stephane Litkowski, Charles Eckel, Mohamed Boucadair and Tom Petch 2033 for their reviews. 2035 Authors' Addresses 2037 Benoit Claise 2038 Huawei 2039 Email: benoit.claise@huawei.com 2041 Jean Quilbeuf 2042 Huawei 2043 Email: jean.quilbeuf@huawei.com 2044 Paolo Lucente 2045 NTT 2046 Siriusdreef 70-72 2047 2132 Hoofddorp 2048 Netherlands 2049 Email: paolo@ntt.net 2051 Paolo Fasano 2052 TIM S.p.A 2053 via G. Reiss Romoli, 274 2054 10148 Torino 2055 Italy 2056 Email: paolo2.fasano@telecomitalia.it 2058 Thangam Arumugam 2059 Cisco Systems, Inc. 2060 Milpitas (California), 2061 United States 2062 Email: tarumuga@cisco.com