idnits 2.17.1 draft-ietf-opsawg-service-assurance-yang-05.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 187 has weird spacing: '...-change yan...' == Line 200 has weird spacing: '...ce-name str...' == Line 694 has weird spacing: '... device str...' == Line 703 has weird spacing: '...-change yan...' == Line 716 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 (29 April 2022) is 726 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) == Outdated reference: A later version (-13) exists of draft-ietf-opsawg-service-assurance-architecture-03 ** Downref: Normative reference to an Informational draft: draft-ietf-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 (~~), 9 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: 31 October 2022 P. Lucente 6 NTT 7 P. Fasano 8 TIM S.p.A 9 T. Arumugam 10 Cisco Systems, Inc. 11 29 April 2022 13 YANG Modules for Service Assurance 14 draft-ietf-opsawg-service-assurance-yang-05 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 31 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. Security Considerations . . . . . . . . . . . . . . . . . . . 23 81 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23 82 7.1. The IETF XML Registry . . . . . . . . . . . . . . . . . . 24 83 7.2. The YANG Module Names Registry . . . . . . . . . . . . . 24 84 8. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 24 85 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 24 86 9.1. Normative References . . . . . . . . . . . . . . . . . . 24 87 9.2. Informative References . . . . . . . . . . . . . . . . . 25 88 Appendix A. Vendor-specific Subservice Extension: 89 example-service-assurance-device-acme YANG module . . . . 26 90 A.1. Tree View . . . . . . . . . . . . . . . . . . . . . . . . 26 91 A.2. Complete Tree View . . . . . . . . . . . . . . . . . . . 26 92 A.3. Concepts . . . . . . . . . . . . . . . . . . . . . . . . 28 93 A.4. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 28 94 Appendix B. Further Extensions: IP Connectivity and IS-IS 95 subservices . . . . . . . . . . . . . . . . . . . . . . . 30 96 B.1. IP Connectivity Tree View . . . . . . . . . . . . . . . . 30 97 B.2. IS-IS Tree View . . . . . . . . . . . . . . . . . . . . . 31 98 B.3. Global Tree View . . . . . . . . . . . . . . . . . . . . 31 99 B.4. IP Connectivity YANG Module . . . . . . . . . . . . . . . 32 100 B.5. IS-IS YANG Module . . . . . . . . . . . . . . . . . . . . 35 101 Appendix C. Example of YANG instances . . . . . . . . . . . . . 37 102 Appendix D. YANG Library for Service Assurance . . . . . . . . . 40 103 Appendix E. Changes between revisions . . . . . . . . . . . . . 42 104 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 43 105 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 43 107 1. Introduction 109 The "Service Assurance for Intent-based Networking Architecture" 110 [I-D.ietf-opsawg-service-assurance-architecture], specifies the 111 architecture and all of its components for service assurance. This 112 document complements the architecture by providing open interfaces 113 between components. More specifically, the goal is to provide YANG 114 modules for the purpose of service assurance in a format that is: 116 * machine readable 118 * vendor independent 120 * augmentable 122 1.1. Terminology 124 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 125 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 126 "OPTIONAL" in this document are to be interpreted as described in BCP 127 13 [RFC2119] [RFC8174] when, and only when, they appear in all 128 capitals, as shown here. 130 The terms used in this document are defined in 131 [I-D.ietf-opsawg-service-assurance-architecture] 133 2. YANG Models Overview 135 The main YANG module, ietf-service-assurance, defines objects for 136 assuring network services based on their decomposition into so-called 137 subservices. The subservices are hierarchically organised by 138 dependencies. The subservices, along with the dependencies, 139 constitute an assurance graph. This module should be supported by an 140 agent, able to interact with the devices in order to produce a health 141 status and symptoms for each subservice in the assurance graph. This 142 module is intended for the following use cases: 144 * Assurance graph configuration: 146 - Subservices: configure a set of subservices to assure, by 147 specifying their types and parameters. 149 - Dependencies: configure the dependencies between the 150 subservices, along with their type. 152 * Assurance telemetry: export the health status of the subservices, 153 along with the observed symptoms. 155 The main module represents the configuration (subservice and 156 dependencies) and operational data (health status and symptoms) in a 157 single tree. Other modules follows the same pattern. Thus, the 158 modules presented in this document conform to the Network Management 159 Datastore Architecture defined in [RFC8342]. 161 The second YANG module, ietf-service-assurance-device, extends the 162 ietf-service-assurance module to add support for the device 163 subservice. Additional subservice types might be added the same way. 165 The third YANG module, ietf-service-assurance-interface, is another 166 example that extends the ietf-service-assurance module. This 167 extension adds support for the interface subservice. 169 We provide additional examples in the appendix. The module example- 170 service-assurance-device-acme extends the ietf-service-assurance- 171 device module to customize it for devices of the fictional ACME 172 Corporation. Additional vendor-specific parameters might be added 173 the same way. We also provide the modules example-service-assurance- 174 ip-connectivity and example-service-assurance-is-is to completely 175 model the example from the SAIN architecture draft 176 [I-D.ietf-opsawg-service-assurance-architecture]. 178 3. Base ietf-service-assurance YANG module 180 3.1. Tree View 182 The following tree diagram [RFC8340] provides an overview of the 183 ietf-service-assurance data model. 185 module: ietf-service-assurance 186 +--ro assurance-graph-version yang:counter64 187 +--ro assurance-graph-last-change yang:date-and-time 188 +--rw subservices 189 +--rw subservice* [type id] 190 +--rw type identityref 191 +--rw id string 192 +--ro last-change? yang:date-and-time 193 +--ro label? string 194 +--rw under-maintenance? boolean 195 +--rw maintenance-contact string 196 +--rw (parameter)? 197 | +--:(service-instance-parameter) 198 | +--rw service-instance-parameter 199 | +--rw service string 200 | +--rw instance-name string 201 +--ro health-score? union 202 +--ro symptoms-history-start? yang:date-and-time 203 +--rw symptoms 204 | +--ro symptom* [start-date-time id] 205 | +--ro id string 206 | +--ro health-score-weight? uint8 207 | +--ro description? string 208 | +--ro start-date-time yang:date-and-time 209 | +--ro stop-date-time? yang:date-and-time 210 +--rw dependencies 211 +--rw dependency* [type id] 212 +--rw type 213 | -> /subservices/subservice/type 214 +--rw id leafref 215 +--rw dependency-type? identityref 217 3.2. Concepts 219 The ietf-service-assurance YANG model assumes an identified number of 220 subservices, to be assured independently. A subservice is a feature 221 or a subpart of the network system that a given service instance 222 might depend on. Example of subservices include: 224 * device: whether a device is healthy, and if not, what are the 225 symptoms. Potential symptoms are "CPU overloaded", "Out of RAM", 226 or "Out of TCAM". 228 * ip-connectivity: given two IP addresses owned by two devices, what 229 is the quality of the connection between them. Potential symptoms 230 are "No route available" or "ECMP Imbalance". 232 The first example is a subservice representing a subpart of the 233 network system, while the second is a subservice representing a 234 feature of the network, In both cases, these subservices might depend 235 on other subservices, for instance, the connectivity might depend on 236 a subservice representing the routing mechanism and on a subservice 237 representing ECMP. 239 The status of each subservice contains a list of symptoms. Each 240 symptom is specified by a unique id and contains a health-score- 241 weight (the impact to the health score incurred by this symptom), a 242 label (text describing what the symptom is), and dates and times at 243 which the symptom was detected and stopped being detected. While the 244 unique id is sufficient as an unique key list, the start-date-time 245 second key help sorting and retrieving relevant symptoms. 247 The relation between the health score and the health-score-weight of 248 the currently active symptoms is not explicitly defined in this 249 draft. The only requirement is that a non-maximal score must be 250 explained by at least one symptom. A way to enforce that requirement 251 is to first detect symptoms and then compute the health score based 252 on the health-score-weight of the detected symptoms. As an example, 253 this computation could be to sum the health-score-weight of the 254 active symptoms, subtract that value from 100 and change the value to 255 0 if negative. The relation between health-score and health-score- 256 weight is left to the implementor (of an agent 257 [I-D.ietf-opsawg-service-assurance-architecture]). To consider for 258 implementing this relation: the health-score is mostly for humans, 259 the symptoms are what the closed loop automation can build on. 261 The assurance of a given service instance can be obtained by 262 composing the assurance of the subservices that it depends on, via 263 the dependency relations. 265 A subservice declaration MUST provide: 267 * A type: identity inheriting of the base identity for subservice, 269 * An id: string uniquely identifying the subservice among those with 270 the same identity, 272 * One or more parameters, which should be specified in an augmenting 273 model, as described in the next sections. 275 The type and id uniquely identify a given subservice. They are used 276 to indicate the dependencies. Dependencies have types as well. Two 277 types are specified in the model: 279 * Impacting: such a dependency indicates an impact on the health of 280 the dependent, 282 * Informational: such a dependency might explain why the dependent 283 has issues but does not impact its health. 285 To illustrate the difference between "impacting" and "informational", 286 consider the interface subservice, representing a network interface. 287 If the device to which the network interface belongs goes down, the 288 network interface will transition to a down state as well. 289 Therefore, the dependency of the interface subservice towards the 290 device subservice is "impacting". On the other hand, a dependency 291 towards the ecmp-load subservice, which checks that the load between 292 ECMP remains stable throughout time, is only "informational". 293 Indeed, services might be perfectly healthy even if the load 294 distribution between ECMP changed. However, such an instability 295 might be a relevant symptom for diagnosing the root cause of a 296 problem. 298 Service instances MUST be modeled as a particular type of subservice 299 with two parameters, a type and an instance name. The type is the 300 name of the service defined in the network orchestrator, for instance 301 "point-to-point-l2vpn". The instance name is the name assigned to 302 the particular instance to be assured, for instance the name of the 303 customer using that instance. 305 The "under-maintenance" and "maintenance-contact" flags inhibit the 306 emission of symptoms for that subservice and subservices that depend 307 on them. See Section 3.7 of 308 [I-D.ietf-opsawg-service-assurance-architecture] for a more detailed 309 discussion. 311 By specifying service instances and their dependencies in terms of 312 subservices, one defines the whole assurance to apply for them. An 313 assurance agent supporting this model should then produce telemetry 314 in return with, for each subservice: a health-status indicating how 315 healthy the subservice is and when the subservice is not healthy, a 316 list of symptoms explaining why the subservice is not healthy. 318 3.3. YANG Module 320 file "ietf-service-assurance@2022-04-07.yang" 322 module ietf-service-assurance { 323 yang-version 1.1; 324 namespace "urn:ietf:params:xml:ns:yang:ietf-service-assurance"; 325 prefix sain; 327 import ietf-yang-types { 328 prefix yang; 329 reference 330 "RFC 6991: Common YANG Data Types"; 331 } 333 organization 334 "IETF OPSAWG Working Group"; 335 contact 336 "WG Web: 337 WG List: 338 Author: Benoit Claise 339 Author: Jean Quilbeuf "; 340 description 341 "This module defines objects for assuring network services based on 342 their decomposition into so-called subservices, according to the 343 SAIN (Service Assurance for Intent-based Networking) architecture. 345 The subservices hierarchically organised by dependencies constitute 346 an assurance graph. This module should be supported by an assurance 347 agent, able to interact with the devices in order to produce a 348 health status and symptoms for each subservice in the assurance 349 graph. 351 This module is intended for the following use cases: 352 * Assurance graph configuration: 353 - subservices: configure a set of subservices to assure, by 354 specifying their types and parameters. 355 - dependencies: configure the dependencies between the 356 subservices, along with their type. 357 * Assurance telemetry: export the health status of the subservices, 358 along with the observed symptoms. 360 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 361 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 362 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 363 are to be interpreted as described in BCP 14 (RFC 2119) 364 (RFC 8174) when, and only when, they appear in all 365 capitals, as shown here. 367 Copyright (c) 2022 IETF Trust and the persons identified as 368 authors of the code. All rights reserved. 370 Redistribution and use in source and binary forms, with or 371 without modification, is permitted pursuant to, and subject 372 to the license terms contained in, the Revised BSD License 373 set forth in Section 4.c of the IETF Trust's Legal Provisions 374 Relating to IETF Documents 375 (https://trustee.ietf.org/license-info). 376 This version of this YANG module is part of RFC XXXX; see the 377 RFC itself for full legal notices. "; 379 revision 2022-04-07 { 380 description 381 "Shorten prefix. Fix copyright. 382 Fix module description"; 383 reference 384 "RFC xxxx: YANG Modules for Service Assurance"; 385 } 386 revision 2022-01-04 { 387 description 388 "Explicitely model a missing value"; 389 reference 390 "RFC xxxx: YANG Modules for Service Assurance"; 391 } 392 revision 2021-06-28 { 393 description 394 "Made service-instance parameters mandatory."; 395 reference 396 "RFC xxxx: YANG Modules for Service Assurance"; 397 } 398 revision 2020-01-13 { 399 description 400 "Added the maintenance window concept."; 401 reference 402 "RFC xxxx: YANG Modules for Service Assurance"; 403 } 404 revision 2019-11-16 { 405 description 406 "Initial revision."; 407 reference 408 "RFC xxxx: YANG Modules for Service Assurance"; 409 } 411 identity subservice-idty { 412 description 413 "Root identity for all subservice types."; 414 } 416 identity service-instance-idty { 417 base subservice-idty; 418 description 419 "Identity representing a service instance."; 420 } 422 identity dependency-type { 423 description 424 "Base identity for representing dependency types."; 425 } 427 identity informational-dependency { 428 base dependency-type; 429 description 430 "Indicates that symptoms of the dependency might be of interest 431 for the dependent, but the status of the dependency should not 432 have any impact on the dependent."; 433 } 435 identity impacting-dependency { 436 base dependency-type; 437 description 438 "Indicates that the status of the dependency directly impacts the 439 status of the dependent."; 440 } 442 grouping symptom { 443 description 444 "Contains the list of symptoms for a specific subservice."; 445 leaf id { 446 type string; 447 description 448 "A unique identifier for the symptom."; 449 } 450 leaf health-score-weight { 451 type uint8 { 452 range "0 .. 100"; 453 } 454 description 455 "The weight to the health score incurred by this symptom. The 456 higher the value, the more of an impact this symptom has. If a 457 subservice health score is not 100, there must be at least one 458 symptom with a health score weight larger than 0."; 459 } 460 leaf description { 461 type string; 462 description 463 "Description of the symptom, i.e. text describing what the 464 symptom is, to be computer-consumable and be displayed on a 465 human interface. "; 467 } 468 leaf start-date-time { 469 type yang:date-and-time; 470 description 471 "Date and time at which the symptom was detected."; 472 } 473 leaf stop-date-time { 474 type yang:date-and-time; 475 description 476 "Date and time at which the symptom stopped being detected."; 477 } 478 } 480 grouping subservice-dependency { 481 description 482 "Represent a dependency to another subservice."; 483 leaf type { 484 type leafref { 485 path "/subservices/subservice/type"; 486 } 487 description 488 "The type of the subservice to refer to (e.g. device)."; 489 } 490 leaf id { 491 type leafref { 492 path "/subservices/subservice[type=current()/../type]/id"; 493 } 494 description 495 "The identifier of the subservice to refer to."; 496 } 497 leaf dependency-type { 498 type identityref { 499 base dependency-type; 500 } 501 description 502 "Represents the type of dependency (i.e. informational, 503 impacting)."; 504 } 505 // Augment here to add parameters specific to a new dependency-type. 506 // For instance, a specific dependency type could keep symptom 507 // whose health-score-weight is larger than a given value. 508 } 510 leaf assurance-graph-version { 511 type yang:counter64; 512 config false; 513 mandatory true; 514 description 515 "The assurance graph version, which increases by 1 for each new 516 version, after the changes (dependencies and/or maintenance 517 windows parameters) are applied to the subservice(s)."; 518 } 519 leaf assurance-graph-last-change { 520 type yang:date-and-time; 521 config false; 522 mandatory true; 523 description 524 "Date and time at which the assurance graph last changed after the 525 changes (dependencies and/or maintenance windows parameters) are 526 applied to the subservice(s). These date and time must be more 527 recent or equal compared to the more recent value of any changed 528 subservices last-change"; 529 } 530 container subservices { 531 description 532 "Root container for the subservices."; 533 list subservice { 534 key "type id"; 535 description 536 "List of subservice configured."; 537 leaf type { 538 type identityref { 539 base subservice-idty; 540 } 541 description 542 "Type of the subservice, for instance device or interface."; 543 } 544 leaf id { 545 type string; 546 description 547 "Unique identifier of the subservice instance, for each 548 type."; 549 } 550 leaf last-change { 551 type yang:date-and-time; 552 config false; 553 description 554 "Date and time at which the assurance graph for this 555 subservice instance last changed, i.e. dependencies and/or 556 maintenance windows parameters."; 557 } 558 leaf label { 559 type string; 560 config false; 561 description 562 "Label of the subservice, i.e. text describing what the 563 subservice is to be displayed on a human interface."; 564 } 565 leaf under-maintenance { 566 type boolean; 567 default "false"; 568 description 569 "An optional flag indicating whether this particular 570 subservice is under maintenance. Under this circumstance, the 571 subservice symptoms and the symptoms of its dependencies in 572 the assurance graph should not be taken into account. 573 Instead, the subservice should send a 'Under Maintenance' 574 single symptom. 576 The operator changing the under-maintenance value must set 577 the maintenance-contact variable. 579 When the subservice is not under maintenance any longer, the 580 under-maintenance flag must return to its default value and 581 the under-maintenance-owner variable deleted."; 582 } 583 leaf maintenance-contact { 584 when "../under-maintenance = 'true'"; 585 type string; 586 mandatory true; 587 description 588 "A string used to model an administratively assigned name of 589 the resource that changed the under-maintenance value to 590 'true'. 592 It is suggested that this name contain one or more of the 593 following: IP address, management station name, 594 network manager's name, location, or phone number. In some 595 cases the agent itself will be the owner of an entry. In 596 these cases, this string shall be set to a string starting 597 with 'monitor'."; 598 } 599 choice parameter { 600 description 601 "Specify the required parameters per subservice type."; 602 container service-instance-parameter { 603 when "derived-from-or-self(../type, 604 'sain:service-instance-idty')"; 605 description 606 "Specify the parameters of a service instance."; 607 leaf service { 608 type string; 609 mandatory true; 610 description 611 "Name of the service."; 612 } 613 leaf instance-name { 614 type string; 615 mandatory true; 616 description 617 "Name of the instance for that service."; 618 } 619 } 620 // Other modules can augment their own cases into here 621 } 622 leaf health-score { 623 type union { 624 type uint8 { 625 range "0 .. 100"; 626 } 627 type enumeration { 628 enum missing { 629 value -1; 630 description 631 "Explictly represent the fact that the health score is 632 missing. This could be used when metrics crucial to 633 establish the health score are not collected anymore."; 634 } 635 } 636 } 637 config false; 638 description 639 "Score value of the subservice health. A value of 100 means 640 that subservice is healthy. A value of 0 means that the 641 subservice is broken. A value between 0 and 100 means that 642 the subservice is degraded."; 643 } 644 leaf symptoms-history-start { 645 type yang:date-and-time; 646 config false; 647 description 648 "Date and time at which the symptoms history starts for this 649 subservice instance, either because the subservice instance 650 started at that date and time or because the symptoms before 651 that were removed due to a garbage collection process."; 652 } 653 container symptoms { 654 description 655 "Symptoms for the subservice."; 656 list symptom { 657 key "start-date-time id"; 658 config false; 659 description 660 "List of symptoms the subservice. While the start-date-time 661 key is not necessary per se, this would get the entries 662 sorted by start-date-time for easy consumption."; 663 uses symptom; 664 } 665 } 666 container dependencies { 667 description 668 "configure the dependencies between the subservices, along 669 with their types."; 670 list dependency { 671 key "type id"; 672 description 673 "List of soft dependencies of the subservice."; 674 uses subservice-dependency; 675 } 676 } 677 } 678 } 679 } 681 683 4. Subservice Extension: ietf-service-assurance-device YANG module 685 4.1. Tree View 687 The following tree diagram [RFC8340] provides an overview of the 688 ietf-service-assurance-device data model. 690 module: ietf-service-assurance-device 692 augment /sain:subservices/sain:subservice/sain:parameter: 693 +--rw parameters 694 +--rw device string 696 4.2. Complete Tree View 698 The following tree diagram [RFC8340] provides an overview of the 699 ietf-service-assurance and ietf-service-assurance-device data models. 701 module: ietf-service-assurance 702 +--ro assurance-graph-version yang:counter64 703 +--ro assurance-graph-last-change yang:date-and-time 704 +--rw subservices 705 +--rw subservice* [type id] 706 +--rw type identityref 707 +--rw id string 708 +--ro last-change? yang:date-and-time 709 +--ro label? string 710 +--rw under-maintenance? boolean 711 +--rw maintenance-contact string 712 +--rw (parameter)? 713 | +--:(service-instance-parameter) 714 | | +--rw service-instance-parameter 715 | | +--rw service string 716 | | +--rw instance-name string 717 | +--:(sain-device:parameters) 718 | +--rw sain-device:parameters 719 | +--rw sain-device:device string 720 +--ro health-score? union 721 +--ro symptoms-history-start? yang:date-and-time 722 +--rw symptoms 723 | +--ro symptom* [start-date-time id] 724 | +--ro id string 725 | +--ro health-score-weight? uint8 726 | +--ro description? string 727 | +--ro start-date-time yang:date-and-time 728 | +--ro stop-date-time? yang:date-and-time 729 +--rw dependencies 730 +--rw dependency* [type id] 731 +--rw type 732 | -> /subservices/subservice/type 733 +--rw id leafref 734 +--rw dependency-type? identityref 736 4.3. Concepts 738 As the number of subservices will grow over time, the YANG module is 739 designed to be extensible. A new subservice type requires the 740 precise specifications of its type and expected parameters. Let us 741 illustrate the example of the new device subservice type. As the 742 name implies, it monitors and reports the device health, along with 743 some symptoms in case of degradation. 745 For our device subservice definition, the new identity device-idty is 746 specified, as an inheritance from the base identity for subservices. 747 This indicates to the assurance agent that we are now assuring the 748 health of a device. 750 The typical parameter for the configuration of the device subservice 751 is the name of the device that we want to assure. By augmenting the 752 parameter choice from ietf-service-assurance YANG module for the case 753 of the device-idty subservice type, this new parameter is specified. 755 4.4. YANG Module 757 file "ietf-service-assurance-device@2022-04-07.yang" 759 module ietf-service-assurance-device { 760 yang-version 1.1; 761 namespace 762 "urn:ietf:params:xml:ns:yang:ietf-service-assurance-device"; 763 prefix sain-device; 765 import ietf-service-assurance { 766 prefix sain; 767 reference 768 "RFC xxxx: YANG Modules for Service Assurance"; 769 } 771 organization 772 "IETF OPSAWG Working Group"; 773 contact 774 "WG Web: 775 WG List: 776 Author: Benoit Claise 777 Author: Jean Quilbeuf "; 778 description 779 "This module extends the ietf-service-assurance module to add 780 support for the device subservice. 782 Checks whether a network device is healthy. 784 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 785 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 786 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 787 are to be interpreted as described in BCP 14 (RFC 2119) 788 (RFC 8174) when, and only when, they appear in all 789 capitals, as shown here. 791 Copyright (c) 2022 IETF Trust and the persons identified as 792 authors of the code. All rights reserved. 794 Redistribution and use in source and binary forms, with or 795 without modification, is permitted pursuant to, and subject 796 to the license terms contained in, the Revised BSD License 797 set forth in Section 4.c of the IETF Trust's Legal Provisions 798 Relating to IETF Documents 799 (https://trustee.ietf.org/license-info). 800 This version of this YANG module is part of RFC XXXX; see the 801 RFC itself for full legal notices. "; 803 revision 2022-04-07 { 804 description 805 "Fix mandatory in augment error by moving when clause. 806 Shorten prefix. Fix module description. 807 Fix module description"; 808 reference 809 "RFC xxxx: YANG Modules for Service Assurance"; 810 } 811 revision 2021-06-28 { 812 description 813 "Renamed the container for parameters."; 814 reference 815 "RFC xxxx: YANG Modules for Service Assurance"; 816 } 817 revision 2020-01-13 { 818 description 819 "Added the maintenance window concept."; 820 reference 821 "RFC xxxx: YANG Modules for Service Assurance"; 822 } 823 revision 2019-11-16 { 824 description 825 "Initial revision."; 826 reference 827 "RFC xxxx: YANG Modules for Service Assurance"; 828 } 830 identity device-idty { 831 base sain:subservice-idty; 832 description 833 "Network Device is healthy."; 834 } 836 augment "/sain:subservices/sain:subservice/sain:parameter" { 837 when "derived-from-or-self(sain:type, 'device-idty')"; 838 description 839 "Specify the required parameters for a new subservice type"; 840 container parameters { 841 description 842 "Specify the required parameters for the device-idty 843 subservice type"; 844 leaf device { 845 type string; 846 mandatory true; 847 description 848 "The device to monitor."; 849 } 850 } 851 } 852 } 854 856 5. Subservice Extension: ietf-service-assurance-interface YANG module 858 5.1. Tree View 860 The following tree diagram [RFC8340] provides an overview of the 861 ietf-service-assurance-interface data model. 863 module: ietf-service-assurance-interface 865 augment /sain:subservices/sain:subservice/sain:parameter: 866 +--rw parameters 867 +--rw device string 868 +--rw interface string 870 5.2. Complete Tree View 872 The following tree diagram [RFC8340] provides an overview of the 873 ietf-service-assurance, ietf-service-assurance-device, and ietf- 874 service-assurance-interface data models. 876 module: ietf-service-assurance 877 +--ro assurance-graph-version yang:counter64 878 +--ro assurance-graph-last-change yang:date-and-time 879 +--rw subservices 880 +--rw subservice* [type id] 881 +--rw type identityref 882 +--rw id string 883 +--ro last-change? yang:date-and-time 884 +--ro label? string 885 +--rw under-maintenance? boolean 886 +--rw maintenance-contact string 887 +--rw (parameter)? 888 | +--:(service-instance-parameter) 889 | | +--rw service-instance-parameter 890 | | +--rw service string 891 | | +--rw instance-name string 892 | +--:(sain-interface:parameters) 893 | | +--rw sain-interface:parameters 894 | | +--rw sain-interface:device string 895 | | +--rw sain-interface:interface string 896 | +--:(sain-device:parameters) 897 | +--rw sain-device:parameters 898 | +--rw sain-device:device string 899 +--ro health-score? union 900 +--ro symptoms-history-start? yang:date-and-time 901 +--rw symptoms 902 | +--ro symptom* [start-date-time id] 903 | +--ro id string 904 | +--ro health-score-weight? uint8 905 | +--ro description? string 906 | +--ro start-date-time yang:date-and-time 907 | +--ro stop-date-time? yang:date-and-time 908 +--rw dependencies 909 +--rw dependency* [type id] 910 +--rw type 911 | -> /subservices/subservice/type 912 +--rw id leafref 913 +--rw dependency-type? identityref 915 5.3. Concepts 917 For our interface subservice definition, the new interface-idty is 918 specified, as an inheritance from the base identity for subservices. 919 This indicates to the assurance agent that we are now assuring the 920 health of an interface. 922 The typical parameters for the configuration of the interface 923 subservice are the name of the device and, on that specific device, a 924 specific interface. By augmenting the parameter choice from ietf- 925 service-assurance YANG module for the case of the interface-idty 926 subservice type, those two new parameters are specified. 928 5.4. YANG Module 930 file "ietf-service-assurance-interface@2022-04-07.yang" 932 module ietf-service-assurance-interface { 933 yang-version 1.1; 934 namespace 935 "urn:ietf:params:xml:ns:yang:ietf-service-assurance-interface"; 936 prefix sain-interface; 938 import ietf-service-assurance { 939 prefix sain; 940 reference 941 "RFC xxxx: YANG Modules for Service Assurance"; 942 } 944 organization 945 "IETF OPSAWG Working Group"; 946 contact 947 "WG Web: 948 WG List: 949 Author: Benoit Claise 950 Author: Jean Quilbeuf "; 951 description 952 "This module extends the ietf-service-assurance module to add 953 support for the interface subservice. 955 Checks whether an interface is healthy. 957 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 958 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 959 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 960 are to be interpreted as described in BCP 14 (RFC 2119) 961 (RFC 8174) when, and only when, they appear in all 962 capitals, as shown here. 964 Copyright (c) 2022 IETF Trust and the persons identified as 965 authors of the code. All rights reserved. 966 Redistribution and use in source and binary forms, with or 967 without modification, is permitted pursuant to, and subject 968 to the license terms contained in, the Revised BSD License 969 set forth in Section 4.c of the IETF Trust's Legal Provisions 970 Relating to IETF Documents 971 (https://trustee.ietf.org/license-info). 973 This version of this YANG module is part of RFC XXXX; see the 974 RFC itself for full legal notices. "; 976 revision 2022-04-07 { 977 description 978 "Fix mandatory in augment error by moving when clause. 979 Shorten prefix. Fix module description. 980 Fix module description"; 981 reference 982 "RFC xxxx: YANG Modules for Service Assurance"; 983 } 984 revision 2021-06-28 { 985 description 986 "Regroup parameters in a container."; 987 reference 988 "RFC xxxx: YANG Modules for Service Assurance"; 989 } 990 revision 2020-01-13 { 991 description 992 "Initial revision."; 993 reference 994 "RFC xxxx: YANG Modules for Service Assurance"; 995 } 997 identity interface-idty { 998 base sain:subservice-idty; 999 description 1000 "Checks whether an interface is healthy."; 1001 } 1003 augment "/sain:subservices/sain:subservice/sain:parameter" { 1004 when "derived-from-or-self(sain:type, 'interface-idty')"; 1005 description 1006 "Specify the required parameters for the interface-idty 1007 subservice type"; 1008 container parameters { 1009 description 1010 "Required parameters for the interface-idty subservice 1011 type"; 1012 leaf device { 1013 type string; 1014 mandatory true; 1015 description 1016 "Device supporting the interface."; 1017 } 1018 leaf interface { 1019 type string; 1020 mandatory true; 1021 description 1022 "Name of the interface."; 1023 } 1024 } 1025 } 1026 } 1028 1030 6. Security Considerations 1032 The YANG module specified in this document defines a schema for data 1033 that is designed to be accessed via network management protocols such 1034 as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer 1035 is the secure transport layer, and the mandatory-to-implement secure 1036 transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer 1037 is HTTPS, and the mandatory-to-implement secure transport is TLS 1038 [RFC8446]. 1040 The Network Configuration Access Control Model (NACM) [RFC8341] 1041 provides the means to restrict access for particular NETCONF or 1042 RESTCONF users to a preconfigured subset of all available NETCONF or 1043 RESTCONF protocol operations and content. 1045 There are a number of data nodes defined in this YANG module that are 1046 writable/ creatable/deletable (i.e., config true, which is the 1047 default). These data nodes may be considered sensitive or vulnerable 1048 in some network environments. Write operations (e.g., edit-config) 1049 to these data nodes without proper protection can have a negative 1050 effect on network operations. These are the subtrees and data nodes 1051 and their sensitivity/vulnerability: 1053 * /subservices/subservice/type 1055 * /subservices/subservice/id 1057 * /subservices/subservice/under-maintenance 1059 * /subservices/subservice/maintenance-contact 1061 7. IANA Considerations 1062 7.1. The IETF XML Registry 1064 This document registers two URIs in the IETF XML registry [RFC3688]. 1065 Following the format in [RFC3688], the following registrations are 1066 requested: 1068 URI: urn:ietf:params:xml:ns:yang:ietf-service-assurance 1069 Registrant Contact: The NETCONF WG of the IETF. 1070 XML: N/A, the requested URI is an XML namespace. 1072 URI: urn:ietf:params:xml:ns:yang:ietf-service-assurance-device 1073 Registrant Contact: The NETCONF WG of the IETF. 1074 XML: N/A, the requested URI is an XML namespace. 1076 URI: urn:ietf:params:xml:ns:yang:ietf-service-assurance-interface 1077 Registrant Contact: The NETCONF WG of the IETF. 1078 XML: N/A, the requested URI is an XML namespace. 1080 7.2. The YANG Module Names Registry 1082 This document registers three YANG modules in the YANG Module Names 1083 registry [RFC7950]. Following the format in [RFC7950], the the 1084 following registrations are requested: 1086 name: ietf-service-assurance 1087 namespace: urn:ietf:params:xml:ns:yang:ietf-service-assurance 1088 prefix: sain 1089 reference: RFC XXXX 1091 name: ietf-service-assurance-device 1092 namespace: urn:ietf:params:xml:ns:yang:ietf-service-assurance-device 1093 prefix: sain-device 1094 reference: RFC XXXX 1096 name: ietf-service-assurance-interface 1097 namespace: urn:ietf:params:xml:ns:yang:ietf-service-assurance-interface 1098 prefix: sain-interface 1099 reference: RFC XXXX 1101 8. Open Issues 1103 -None 1105 9. References 1107 9.1. Normative References 1109 [I-D.ietf-opsawg-service-assurance-architecture] 1110 Claise, B., Quilbeuf, J., Lopez, D. R., Voyer, D., and T. 1111 Arumugam, "Service Assurance for Intent-based Networking 1112 Architecture", Work in Progress, Internet-Draft, draft- 1113 ietf-opsawg-service-assurance-architecture-03, 7 March 1114 2022, . 1117 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1118 and A. Bierman, Ed., "Network Configuration Protocol 1119 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1120 . 1122 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 1123 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 1124 . 1126 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1127 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1128 . 1130 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1131 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1132 . 1134 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 1135 Access Control Model", STD 91, RFC 8341, 1136 DOI 10.17487/RFC8341, March 2018, 1137 . 1139 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 1140 and R. Wilton, "Network Management Datastore Architecture 1141 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 1142 . 1144 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 1145 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 1146 . 1148 9.2. Informative References 1150 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1151 Requirement Levels", BCP 14, RFC 2119, 1152 DOI 10.17487/RFC2119, March 1997, 1153 . 1155 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1156 DOI 10.17487/RFC3688, January 2004, 1157 . 1159 [RFC7895] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module 1160 Library", RFC 7895, DOI 10.17487/RFC7895, June 2016, 1161 . 1163 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1164 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1165 May 2017, . 1167 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 1168 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 1169 . 1171 Appendix A. Vendor-specific Subservice Extension: example-service- 1172 assurance-device-acme YANG module 1174 A.1. Tree View 1176 The following tree diagram [RFC8340] provides an overview of the 1177 example-service-assurance-device-acme data model. 1179 module: example-service-assurance-device-acme 1181 augment /sain:subservices/sain:subservice/sain:parameter: 1182 +--rw parameters 1183 +--rw device string 1184 +--rw acme-specific-parameter string 1186 A.2. Complete Tree View 1188 The following tree diagram [RFC8340] provides an overview of the 1189 ietf-service-assurance, ietf-service-assurance-device, and example- 1190 service-assurance-device-acme data models. 1192 module: ietf-service-assurance 1193 +--ro assurance-graph-version yang:counter64 1194 +--ro assurance-graph-last-change yang:date-and-time 1195 +--rw subservices 1196 +--rw subservice* [type id] 1197 +--rw type identityref 1198 +--rw id string 1199 +--ro last-change? 1200 | yang:date-and-time 1201 +--ro label? string 1202 +--rw under-maintenance? boolean 1203 +--rw maintenance-contact string 1204 +--rw (parameter)? 1205 | +--:(service-instance-parameter) 1206 | | +--rw service-instance-parameter 1207 | | +--rw service string 1208 | | +--rw instance-name string 1209 | +--:(sain-device:parameters) 1210 | | +--rw sain-device:parameters 1211 | | +--rw sain-device:device string 1212 | +--:(example-device-acme:parameters) 1213 | | +--rw example-device-acme:parameters 1214 | | +--rw example-device-acme:device 1215 | | | string 1216 | | +--rw example-device-acme:acme-specific-parameter 1217 | | string 1218 | +--:(sain-interface:parameters) 1219 | +--rw sain-interface:parameters 1220 | +--rw sain-interface:device string 1221 | +--rw sain-interface:interface string 1222 +--ro health-score? union 1223 +--ro symptoms-history-start? 1224 | yang:date-and-time 1225 +--rw symptoms 1226 | +--ro symptom* [start-date-time id] 1227 | +--ro id string 1228 | +--ro health-score-weight? uint8 1229 | +--ro description? string 1230 | +--ro start-date-time yang:date-and-time 1231 | +--ro stop-date-time? yang:date-and-time 1232 +--rw dependencies 1233 +--rw dependency* [type id] 1234 +--rw type 1235 | -> /subservices/subservice/type 1236 +--rw id leafref 1237 +--rw dependency-type? identityref 1239 A.3. Concepts 1241 Under some circumstances, vendor-specific subservice types might be 1242 required. As an example of this vendor-specific implementation, this 1243 section shows how to augment the ietf-service-assurance-device module 1244 to add custom support for the device subservice, specific to the ACME 1245 Corporation. The specific version adds a new parameter, named acme- 1246 specific-parameter. 1248 A.4. YANG Module 1250 module example-service-assurance-device-acme { 1251 yang-version 1.1; 1252 namespace "urn:example:example-service-assurance-device-acme"; 1253 prefix example-device-acme; 1255 import ietf-service-assurance { 1256 prefix sain; 1257 reference 1258 "RFC xxxx: YANG Modules for Service Assurance"; 1259 } 1260 import ietf-service-assurance-device { 1261 prefix sain-device; 1262 reference 1263 "RFC xxxx: YANG Modules for Service Assurance"; 1264 } 1266 organization 1267 "IETF OPSAWG Working Group"; 1268 contact 1269 "WG Web: 1270 WG List: 1271 Author: Benoit Claise 1272 Author: Jean Quilbeuf "; 1273 description 1274 "This module extends the ietf-service-assurance-device module to 1275 add specific support for devices of ACME Corporation. 1277 ACME Network Device is healthy. 1279 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 1280 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 1281 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 1282 are to be interpreted as described in BCP 14 (RFC 2119) 1283 (RFC 8174) when, and only when, they appear in all 1284 capitals, as shown here. 1286 Copyright (c) 2022 IETF Trust and the persons identified as 1287 authors of the code. All rights reserved. 1289 Redistribution and use in source and binary forms, with or 1290 without modification, is permitted pursuant to, and subject 1291 to the license terms contained in, the Revised BSD License 1292 set forth in Section 4.c of the IETF Trust's Legal Provisions 1293 Relating to IETF Documents 1294 (https://trustee.ietf.org/license-info). 1296 This version of this YANG module is part of RFC XXXX; see the 1297 RFC itself for full legal notices. "; 1299 revision 2022-04-07 { 1300 description 1301 "Fix mandatory in augment error by moving when clause. 1302 Shorten prefix. 1303 Fix module description"; 1304 reference 1305 "RFC xxxx: YANG Modules for Service Assurance"; 1306 } 1307 revision 2021-06-28 { 1308 description 1309 "Renamed the parameters container."; 1310 reference 1311 "RFC xxxx: YANG Modules for Service Assurance"; 1312 } 1313 revision 2020-01-13 { 1314 description 1315 "Added the maintenance window concept."; 1316 reference 1317 "RFC xxxx: YANG Modules for Service Assurance"; 1318 } 1319 revision 2019-11-16 { 1320 description 1321 "Initial revision."; 1322 reference 1323 "RFC xxxx: YANG Modules for Service Assurance"; 1324 } 1326 identity device-acme-idty { 1327 base sain-device:device-idty; 1328 description 1329 "Network Device is healthy."; 1330 } 1332 augment "/sain:subservices/sain:subservice/sain:parameter" { 1333 when "derived-from-or-self(sain:type, 'device-acme-idty')"; 1334 description 1335 "Specify the required parameters for a new subservice type"; 1336 container parameters { 1337 description 1338 "Specify the required parameters for the device-acme-idty 1339 subservice type"; 1340 leaf device { 1341 type string; 1342 mandatory true; 1343 description 1344 "The device to monitor."; 1345 } 1346 leaf acme-specific-parameter { 1347 type string; 1348 mandatory true; 1349 description 1350 "The ACME Corporation sepcific parameter."; 1351 } 1352 } 1353 } 1354 } 1356 Appendix B. Further Extensions: IP Connectivity and IS-IS subservices 1358 In this section, we provide two additional YANG models to completely 1359 cover the example from Figure 2 in 1360 [I-D.ietf-opsawg-service-assurance-architecture]. The complete 1361 normalization of these modules is to be done in future work. 1363 B.1. IP Connectivity Tree View 1365 That subservice represents the unicast connectivity between two IP 1366 addresses located on to different devices. Such a subservice could 1367 report symptoms such as "No route found". The following tree diagram 1368 [RFC8340] provides an overview of the example-service-assurance-ip- 1369 connectivity data model. 1371 module: example-service-assurance-ip-connectivity 1373 augment /sain:subservices/sain:subservice/sain:parameter: 1374 +--rw parameters 1375 +--rw device1 string 1376 +--rw address1 inet:ip-address 1377 +--rw device2 string 1378 +--rw address2 inet:ip-address 1380 To specify the connectivity that we are interested in, we specify two 1381 IP addresses and two devices. The subservice assures that the 1382 connectivity between IP address 1 on device 1 and IP address 2 on 1383 device 2 is healthy. 1385 B.2. IS-IS Tree View 1387 The following tree diagram [RFC8340] provides an overview of the 1388 example-service-assurance-is-is data model. 1390 module: example-service-assurance-is-is 1392 augment /sain:subservices/sain:subservice/sain:parameter: 1393 +--rw parameters 1394 +--rw instance-name string 1396 The parameter of this subservice is the name of the IS-IS instance to 1397 assure. 1399 B.3. Global Tree View 1401 The following tree diagram [RFC8340] provides an overview of the 1402 ietf-service-assurance, ietf-service-assurance-device, example- 1403 service-assurance-device-acme, example-service-assurance-ip- 1404 connectivity and example-service-assurance-is-is data models. 1406 module: ietf-service-assurance 1407 +--ro assurance-graph-version yang:counter64 1408 +--ro assurance-graph-last-change yang:date-and-time 1409 +--rw subservices 1410 +--rw subservice* [type id] 1411 +--rw type identityref 1412 +--rw id string 1413 +--ro last-change? 1414 | yang:date-and-time 1415 +--ro label? string 1416 +--rw under-maintenance? boolean 1417 +--rw maintenance-contact string 1418 +--rw (parameter)? 1419 | +--:(service-instance-parameter) 1420 | | +--rw service-instance-parameter 1421 | | +--rw service string 1422 | | +--rw instance-name string 1423 | +--:(example-ip-connectivity:parameters) 1424 | | +--rw example-ip-connectivity:parameters 1425 | | +--rw example-ip-connectivity:device1 string 1426 | | +--rw example-ip-connectivity:address1 1427 | | | inet:ip-address 1428 | | +--rw example-ip-connectivity:device2 string 1429 | | +--rw example-ip-connectivity:address2 1430 | | inet:ip-address 1431 | +--:(example-is-is:parameters) 1432 | | +--rw example-is-is:parameters 1433 | | +--rw example-is-is:instance-name string 1434 | +--:(sain-device:parameters) 1435 | | +--rw sain-device:parameters 1436 | | +--rw sain-device:device string 1437 | +--:(example-device-acme:parameters) 1438 | | +--rw example-device-acme:parameters 1439 | | +--rw example-device-acme:device 1440 | | | string 1441 | | +--rw example-device-acme:acme-specific-parameter 1442 | | string 1443 | +--:(sain-interface:parameters) 1444 | +--rw sain-interface:parameters 1445 | +--rw sain-interface:device string 1446 | +--rw sain-interface:interface string 1447 +--ro health-score? union 1448 +--ro symptoms-history-start? 1449 | yang:date-and-time 1450 +--rw symptoms 1451 | +--ro symptom* [start-date-time id] 1452 | +--ro id string 1453 | +--ro health-score-weight? uint8 1454 | +--ro description? string 1455 | +--ro start-date-time yang:date-and-time 1456 | +--ro stop-date-time? yang:date-and-time 1457 +--rw dependencies 1458 +--rw dependency* [type id] 1459 +--rw type 1460 | -> /subservices/subservice/type 1461 +--rw id leafref 1462 +--rw dependency-type? identityref 1464 B.4. IP Connectivity YANG Module 1466 module example-service-assurance-ip-connectivity { 1467 yang-version 1.1; 1468 namespace "urn:example:example-service-assurance-ip-connectivity"; 1469 prefix example-ip-connectivity; 1471 import ietf-inet-types { 1472 prefix inet; 1473 reference 1474 "RFC 6991: Common YANG Data Types"; 1475 } 1476 import ietf-service-assurance { 1477 prefix sain; 1478 reference 1479 "RFC xxxx: YANG Modules for Service Assurance"; 1480 } 1482 organization 1483 "IETF OPSAWG Working Group"; 1484 contact 1485 "WG Web: 1486 WG List: 1487 Author: Benoit Claise 1488 Author: Jean Quilbeuf "; 1489 description 1490 "This example module extends the ietf-service-assurance module to 1491 add support for the subservice ip-connectivity. 1493 Checks whether the ip connectivity between two ip addresses 1494 belonging to two network devices is healthy. 1496 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 1497 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 1498 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 1499 are to be interpreted as described in BCP 14 (RFC 2119) 1500 (RFC 8174) when, and only when, they appear in all 1501 capitals, as shown here. 1503 Copyright (c) 2022 IETF Trust and the persons identified as 1504 authors of the code. All rights reserved. 1505 Redistribution and use in source and binary forms, with or 1506 without modification, is permitted pursuant to, and subject 1507 to the license terms contained in, the Revised BSD License 1508 set forth in Section 4.c of the IETF Trust's Legal Provisions 1509 Relating to IETF Documents 1510 (https://trustee.ietf.org/license-info). 1512 This version of this YANG module is part of RFC XXXX; see the 1513 RFC itself for full legal notices. "; 1515 revision 2022-04-07 { 1516 description 1517 "Fix mandatory in augment error by moving when clause. 1518 Shorten prefix. Fix module description. 1519 Fix module description"; 1520 reference 1521 "RFC xxxx: YANG Modules for Service Assurance"; 1523 } 1524 revision 2021-06-28 { 1525 description 1526 "Initial revision."; 1527 reference 1528 "RFC xxxx: YANG Modules for Service Assurance"; 1529 } 1531 identity ip-connectivity-idty { 1532 base sain:subservice-idty; 1533 description 1534 "Checks connectivity between two IP addresses."; 1535 } 1537 augment "/sain:subservices/sain:subservice/sain:parameter" { 1538 when "derived-from-or-self(sain:type, 'ip-connectivity-idty')"; 1539 description 1540 "Specify the required parameters for the ip-connectivity-idty 1541 subservice type"; 1542 container parameters { 1543 description 1544 "Required parameters for the ip-connectivity-idty 1545 subservice type"; 1546 leaf device1 { 1547 type string; 1548 mandatory true; 1549 description 1550 "Device at the first end of the connection."; 1551 } 1552 leaf address1 { 1553 type inet:ip-address; 1554 mandatory true; 1555 description 1556 "Address at the first end of the connection."; 1557 } 1558 leaf device2 { 1559 type string; 1560 mandatory true; 1561 description 1562 "Device at the second end of the connection."; 1563 } 1564 leaf address2 { 1565 type inet:ip-address; 1566 mandatory true; 1567 description 1568 "Address at the second end of the connection."; 1569 } 1570 } 1572 } 1573 } 1575 B.5. IS-IS YANG Module 1577 module example-service-assurance-is-is { 1578 yang-version 1.1; 1579 namespace "urn:example:example-service-assurance-is-is"; 1580 prefix example-is-is; 1582 import ietf-service-assurance { 1583 prefix sain; 1584 reference 1585 "RFC xxxx: YANG Modules for Service Assurance"; 1586 } 1588 organization 1589 "IETF OPSAWG Working Group"; 1590 contact 1591 "WG Web: 1592 WG List: 1593 Author: Benoit Claise 1594 Author: Jean Quilbeuf "; 1595 description 1596 "This module extends the ietf-service-assurance module to 1597 add support for the subservice is-is. 1599 Checks whether an IS-IS instance is healthy. 1601 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 1602 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 1603 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 1604 are to be interpreted as described in BCP 14 (RFC 2119) 1605 (RFC 8174) when, and only when, they appear in all 1606 capitals, as shown here. 1608 Copyright (c) 2022 IETF Trust and the persons identified as 1609 authors of the code. All rights reserved. 1611 Redistribution and use in source and binary forms, with or 1612 without modification, is permitted pursuant to, and subject 1613 to the license terms contained in, the Revised BSD License 1614 set forth in Section 4.c of the IETF Trust's Legal Provisions 1615 Relating to IETF Documents 1616 (https://trustee.ietf.org/license-info). 1617 This version of this YANG module is part of RFC XXXX; see the 1618 RFC itself for full legal notices. "; 1620 revision 2022-04-07 { 1621 description 1622 "Fix mandatory in augment error by moving when clause. 1623 Shorten prefix. Fix module description. 1624 Fix module description"; 1625 reference 1626 "RFC xxxx: YANG Modules for Service Assurance"; 1627 } 1628 revision 2021-06-28 { 1629 description 1630 "Initial revision."; 1631 reference 1632 "RFC xxxx: YANG Modules for Service Assurance"; 1633 } 1635 identity is-is-idty { 1636 base sain:subservice-idty; 1637 description 1638 "Health of IS-IS routing protocol."; 1639 } 1641 augment "/sain:subservices/sain:subservice/sain:parameter" { 1642 when "derived-from-or-self(sain:type, 'is-is-idty')"; 1643 description 1644 "Specify the required parameters for a new subservice 1645 type"; 1646 container parameters { 1647 description 1648 "Specify the required parameters for the IS-IS subservice 1649 type"; 1650 leaf instance-name { 1651 type string; 1652 mandatory true; 1653 description 1654 "The instance to monitor."; 1655 } 1656 } 1657 } 1658 } 1660 Appendix C. Example of YANG instances 1662 This section contains examples of YANG instances that conform to the 1663 YANG modules. The validity of these data instances has been checked 1664 using yangson (https://yangson.labs.nic.cz/). Yangson requires a 1665 YANG library [RFC7895] to define the complete model against which the 1666 data instance must be validated. We provide in Appendix D the JSON 1667 library file, named "ietf-service-assurance-library.json", that we 1668 used for validation. 1670 We provide below the contents of the file 1671 "example_configuration_instance.json" which contains the 1672 configuration data that models the Figure 2 of 1673 [I-D.ietf-opsawg-service-assurance-architecture]. The instance can 1674 be validated with yangson by using the invocation "yangson -v 1675 example_configuration_instance.json ietf-service-assurance- 1676 library.json", assuming all the files (YANG and JSON) defined in this 1677 draft reside in the current folder. 1679 { 1680 "ietf-service-assurance:subservices": { 1681 "subservice": [ 1682 { 1683 "type": "service-instance-idty", 1684 "id": "simple-tunnel/example", 1685 "service-instance-parameter": { 1686 "service": "simple-tunnel", 1687 "instance-name": "example" 1688 }, 1689 "dependencies": { 1690 "dependency": [ 1691 { 1692 "type": "ietf-service-assurance-interface:interface-idty", 1693 "id": "interface/peer1/tunnel0", 1694 "dependency-type": "impacting-dependency" 1695 }, 1696 { 1697 "type": "ietf-service-assurance-interface:interface-idty", 1698 "id": "interface/peer2/tunnel9", 1699 "dependency-type": "impacting-dependency" 1700 }, 1701 { 1702 "type": 1703 "example-service-assurance-ip-connectivity:ip-connectivity-idty", 1704 "id": "connectivity/peer1/2001:db8::1/peer2/2001:db8::2", 1705 "dependency-type": "impacting-dependency" 1706 } 1707 ] 1709 } 1710 }, 1711 { 1712 "type": 1713 "example-service-assurance-ip-connectivity:ip-connectivity-idty", 1714 "id": "connectivity/peer1/2001:db8::1/peer2/2001:db8::2", 1715 "example-service-assurance-ip-connectivity:parameters": { 1716 "device1": "Peer1", 1717 "address1": "2001:db8::1", 1718 "device2": "Peer2", 1719 "address2": "2001:db8::2" 1720 }, 1721 "dependencies": { 1722 "dependency": [ 1723 { 1724 "type": "ietf-service-assurance-interface:interface-idty", 1725 "id": "interface/peer1/physical0", 1726 "dependency-type": "impacting-dependency" 1727 }, 1728 { 1729 "type": "ietf-service-assurance-interface:interface-idty", 1730 "id": "interface/peer2/physical5", 1731 "dependency-type": "impacting-dependency" 1732 }, 1733 { 1734 "type": "example-service-assurance-is-is:is-is-idty", 1735 "id": "is-is/instance1", 1736 "dependency-type": "impacting-dependency" 1737 } 1738 ] 1739 } 1740 }, 1741 { 1742 "type": "example-service-assurance-is-is:is-is-idty", 1743 "id": "is-is/instance1", 1744 "example-service-assurance-is-is:parameters": { 1745 "instance-name": "instance1" 1746 } 1747 }, 1748 { 1749 "type": "ietf-service-assurance-interface:interface-idty", 1750 "id": "interface/peer1/tunnel0", 1751 "ietf-service-assurance-interface:parameters": { 1752 "device": "Peer1", 1753 "interface": "tunnel0" 1754 }, 1755 "dependencies": { 1756 "dependency": [ 1757 { 1758 "type": "ietf-service-assurance-interface:interface-idty", 1759 "id": "interface/peer1/physical0", 1760 "dependency-type": "impacting-dependency" 1761 } 1762 ] 1763 } 1764 }, 1765 { 1766 "type": "ietf-service-assurance-interface:interface-idty", 1767 "id": "interface/peer1/physical0", 1768 "ietf-service-assurance-interface:parameters": { 1769 "device": "Peer1", 1770 "interface": "physical0" 1771 }, 1772 "dependencies": { 1773 "dependency": [ 1774 { 1775 "type": "ietf-service-assurance-device:device-idty", 1776 "id": "interface/peer1", 1777 "dependency-type": "impacting-dependency" 1778 } 1779 ] 1780 } 1781 }, 1782 { 1783 "type": "ietf-service-assurance-device:device-idty", 1784 "id": "interface/peer1", 1785 "ietf-service-assurance-device:parameters": { 1786 "device": "Peer1" 1787 } 1788 }, 1789 { 1790 "type": "ietf-service-assurance-interface:interface-idty", 1791 "id": "interface/peer2/tunnel9", 1792 "ietf-service-assurance-interface:parameters": { 1793 "device": "Peer2", 1794 "interface": "tunnel9" 1795 }, 1796 "dependencies": { 1797 "dependency": [ 1798 { 1799 "type": "ietf-service-assurance-interface:interface-idty", 1800 "id": "interface/peer2/physical5", 1801 "dependency-type": "impacting-dependency" 1802 } 1803 ] 1804 } 1806 }, 1807 { 1808 "type": "ietf-service-assurance-interface:interface-idty", 1809 "id": "interface/peer2/physical5", 1810 "ietf-service-assurance-interface:parameters": { 1811 "device": "Peer2", 1812 "interface": "physical5" 1813 }, 1814 "dependencies": { 1815 "dependency": [ 1816 { 1817 "type": "ietf-service-assurance-device:device-idty", 1818 "id": "interface/peer2", 1819 "dependency-type": "impacting-dependency" 1820 } 1821 ] 1822 } 1823 }, 1824 { 1825 "type": "ietf-service-assurance-device:device-idty", 1826 "id": "interface/peer2", 1827 "ietf-service-assurance-device:parameters": { 1828 "device": "Peer2" 1829 } 1830 } 1831 ] 1832 } 1833 } 1835 Appendix D. YANG Library for Service Assurance 1837 This section provides the JSON encoding of the YANG library [RFC7895] 1838 listing all modules defined in this draft and their dependencies. 1839 This library can be used to validate data instances using yangson, as 1840 explained in the previous section. 1842 { 1843 "ietf-yang-library:modules-state": { 1844 "module-set-id": "ietf-service-assurance@2022-04-07", 1845 "module": [ 1846 { 1847 "name": "ietf-service-assurance", 1848 "namespace": 1849 "urn:ietf:params:xml:ns:yang:ietf-service-assurance", 1850 "revision": "2022-04-07", 1851 "conformance-type": "implement" 1853 }, 1854 { 1855 "name": "ietf-service-assurance-device", 1856 "namespace": 1857 "urn:ietf:params:xml:ns:yang:ietf-service-assurance-device", 1858 "revision": "2022-04-07", 1859 "conformance-type": "implement" 1860 }, 1861 { 1862 "name": "ietf-service-assurance-interface", 1863 "namespace": 1864 "urn:ietf:params:xml:ns:yang:ietf-service-assurance-interface", 1865 "revision": "2022-04-07", 1866 "conformance-type": "implement" 1867 }, 1868 { 1869 "name": "example-service-assurance-device-acme", 1870 "namespace": 1871 "urn:example:example-service-assurance-device-acme", 1872 "revision": "2022-04-07", 1873 "conformance-type": "implement" 1874 }, 1875 { 1876 "name": "example-service-assurance-is-is", 1877 "namespace": "urn:example:example-service-assurance-is-is", 1878 "revision": "2022-04-07", 1879 "conformance-type": "implement" 1880 }, 1881 { 1882 "name": "example-service-assurance-ip-connectivity", 1883 "namespace": 1884 "urn:example:example-service-assurance-ip-connectivity", 1885 "revision": "2022-04-07", 1886 "conformance-type": "implement" 1887 }, 1888 { 1889 "name": "ietf-yang-types", 1890 "namespace": "urn:ietf:params:xml:ns:yang:ietf-yang-types", 1891 "revision": "2021-04-14", 1892 "conformance-type": "import" 1893 }, 1894 { 1895 "name": "ietf-inet-types", 1896 "namespace": "urn:ietf:params:xml:ns:yang:ietf-inet-types", 1897 "revision": "2021-02-22", 1898 "conformance-type": "import" 1899 } 1900 ] 1902 } 1903 } 1905 Appendix E. Changes between revisions 1907 v04 - v05 1909 * Remove Guidelines section 1911 * Move informative parts (examples) to appendix 1913 * Minor text edits and reformulations 1915 v03 - v04 1917 * Fix YANG errors 1919 * Change is-is and ip-connectivity subservices from ietf to example. 1921 * Mention that models are NMDA compliant 1923 * Fix typos, reformulate for clarity 1925 v02 - v03 1927 * Change counter32 to counter64 to avoid resetting too frequently 1929 * Explain why relation between health-score and symptom's health- 1930 score-weight is not defined and how it could be defined 1932 v01 - v02 1934 * Explicitly represent the fact that the health-score could not be 1935 computed (value -1) 1937 v00 - v01 1939 * Added needed subservice to model example from architecture draft 1941 * Added guideline section for naming models 1943 * Added data instance examples and validation procedure 1945 * Added the "parameters" container in the interface YANG module to 1946 correct a bug. 1948 Acknowledgements 1950 The authors would like to thank Jan Lindblad for his help during the 1951 design of these YANG modules. The authors would like to thank 1952 Stephane Litkowski, Charles Eckel, Mohamed Boucadair and Tom Petch 1953 for their reviews. 1955 Authors' Addresses 1957 Benoit Claise 1958 Huawei 1959 Email: benoit.claise@huawei.com 1961 Jean Quilbeuf 1962 Huawei 1963 Email: jean.quilbeuf@huawei.com 1965 Paolo Lucente 1966 NTT 1967 Siriusdreef 70-72 1968 2132 Hoofddorp 1969 Netherlands 1970 Email: paolo@ntt.net 1972 Paolo Fasano 1973 TIM S.p.A 1974 via G. Reiss Romoli, 274 1975 10148 Torino 1976 Italy 1977 Email: paolo2.fasano@telecomitalia.it 1979 Thangam Arumugam 1980 Cisco Systems, Inc. 1981 Milpitas (California), 1982 United States 1983 Email: tarumuga@cisco.com