idnits 2.17.1 draft-ietf-opsawg-service-assurance-yang-03.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 : ---------------------------------------------------------------------------- ** There are 109 instances of too long lines in the document, the longest one being 29 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 183 has weird spacing: '...-change yan...' == Line 196 has weird spacing: '...ce-name str...' == Line 670 has weird spacing: '... device str...' == Line 679 has weird spacing: '...-change yan...' == Line 692 has weird spacing: '...ce-name str...' == (19 more instances...) -- The document date (25 March 2022) is 763 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: 2 errors (**), 0 flaws (~~), 7 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: 26 September 2022 P. Lucente 6 NTT 7 P. Fasano 8 TIM S.p.A 9 T. Arumugam 10 Cisco Systems, Inc. 11 25 March 2022 13 YANG Modules for Service Assurance 14 draft-ietf-opsawg-service-assurance-yang-03 16 Abstract 18 This document proposes YANG modules for the Service Assurance for 19 Intent-based Networking Architecture. 21 Status of This Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at https://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on 26 September 2022. 38 Copyright Notice 40 Copyright (c) 2022 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 45 license-info) in effect on the date of publication of this document. 46 Please review these documents carefully, as they describe your rights 47 and restrictions with respect to this document. Code Components 48 extracted from this document must include Revised BSD License text as 49 described in Section 4.e of the Trust Legal Provisions and are 50 provided without warranty as described in the Revised BSD License. 52 Table of Contents 54 1. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 55 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 56 3. YANG Models Overview . . . . . . . . . . . . . . . . . . . . 3 57 4. Base ietf-service-assurance YANG module . . . . . . . . . . . 4 58 4.1. Tree View . . . . . . . . . . . . . . . . . . . . . . . . 4 59 4.2. Concepts . . . . . . . . . . . . . . . . . . . . . . . . 5 60 4.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 7 61 5. Subservice Extension: ietf-service-assurance-device YANG 62 module . . . . . . . . . . . . . . . . . . . . . . . . . 15 63 5.1. Tree View . . . . . . . . . . . . . . . . . . . . . . . . 15 64 5.2. Complete Tree View . . . . . . . . . . . . . . . . . . . 15 65 5.3. Concepts . . . . . . . . . . . . . . . . . . . . . . . . 16 66 5.4. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 17 67 6. Subservice Extension: ietf-service-assurance-interface YANG 68 module . . . . . . . . . . . . . . . . . . . . . . . . . 19 69 6.1. Tree View . . . . . . . . . . . . . . . . . . . . . . . . 19 70 6.2. Complete Tree View . . . . . . . . . . . . . . . . . . . 19 71 6.3. Concepts . . . . . . . . . . . . . . . . . . . . . . . . 20 72 6.4. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 21 73 7. Vendor-specific Subservice Extension: 74 example-service-assurance-device-acme YANG module . . . . 23 75 7.1. Tree View . . . . . . . . . . . . . . . . . . . . . . . . 23 76 7.2. Complete Tree View . . . . . . . . . . . . . . . . . . . 23 77 7.3. Concepts . . . . . . . . . . . . . . . . . . . . . . . . 25 78 7.4. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 25 79 8. Further Extensions: IP Connectivity and IS-IS subservices . . 27 80 8.1. IP Connectivity Tree View . . . . . . . . . . . . . . . . 27 81 8.2. IS-IS Tree View . . . . . . . . . . . . . . . . . . . . . 27 82 8.3. Global Tree View . . . . . . . . . . . . . . . . . . . . 28 83 8.4. IP Connectivity YANG Module . . . . . . . . . . . . . . . 29 84 8.5. IS-IS YANG Module . . . . . . . . . . . . . . . . . . . . 31 85 9. Guidelines for Specific Subservice Extension . . . . . . . . 33 86 9.1. Module Name . . . . . . . . . . . . . . . . . . . . . . . 33 87 9.2. Module Namespace . . . . . . . . . . . . . . . . . . . . 33 88 9.3. Module Prefix . . . . . . . . . . . . . . . . . . . . . . 34 89 9.4. Subservice Specific Identity . . . . . . . . . . . . . . 34 90 9.5. Parameters . . . . . . . . . . . . . . . . . . . . . . . 34 92 10. Security Considerations . . . . . . . . . . . . . . . . . . . 34 93 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 35 94 11.1. The IETF XML Registry . . . . . . . . . . . . . . . . . 35 95 11.2. The YANG Module Names Registry . . . . . . . . . . . . . 35 96 12. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 36 97 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 36 98 13.1. Normative References . . . . . . . . . . . . . . . . . . 36 99 13.2. Informative References . . . . . . . . . . . . . . . . . 37 100 Appendix A. Example of YANG instances . . . . . . . . . . . . . 37 101 Appendix B. YANG Library for Service Assurance . . . . . . . . . 41 102 Appendix C. Changes between revisions . . . . . . . . . . . . . 42 103 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 43 104 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 43 106 1. Terminology 108 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 109 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 110 "OPTIONAL" in this document are to be interpreted as described in BCP 111 14 [RFC2119] [RFC8174] when, and only when, they appear in all 112 capitals, as shown here. 114 The terms used in this document are defined in 115 [I-D.ietf-opsawg-service-assurance-architecture] 117 2. Introduction 119 The "Service Assurance for Intent-based Networking Architecture" 120 [I-D.ietf-opsawg-service-assurance-architecture], specifies the 121 architecture and all of its components for service assurance. This 122 document complements the architecture by providing open interfaces 123 between components. More specifically, the goal is to provide YANG 124 modules for the purpose of service assurance in a format that is: 126 * machine readable 128 * vendor independent 130 * augmentable 132 3. YANG Models Overview 134 The main YANG module, ietf-service-assurance, defines objects for 135 assuring network services based on their decomposition into so-called 136 subservices. The subservices are hierarchically organised by 137 dependencies. The subservices, along with the dependencies, 138 constitute an assurance graph. This module should be supported by an 139 agent, able to interact with the devices in order to produce a health 140 status and symptoms for each subservice in the assurance graph. This 141 module is intended for the following use cases: 143 * Assurance graph configuration: 145 - Subservices: configure a set of subservices to assure, by 146 specifying their types and parameters. 148 - Dependencies: configure the dependencies between the 149 subservices, along with their type. 151 * Assurance telemetry: export the health status of the subservices, 152 along with the observed symptoms. 154 The second YANG module, ietf-service-assurance-device, extends the 155 ietf-service-assurance module to add support for the subservice 156 DeviceHealthy. Additional subservice types might be added the same 157 way. 159 The third YANG module, ietf-service-assurance-device, is another 160 example that extends the ietf-service-assurance-device module. This 161 extension adds support for the subservice InterfaceHealthy. 163 The fourth YANG module, example-service-assurance-device-acme, 164 extends the ietf-service-assurance-device module as an example to add 165 support for the subservice DeviceHealthy, with specifics for the 166 fictional ACME Corporation. Additional vendor-specific parameters 167 might be added the same way. 169 Finally, the modules ietf-service-assurance-ip-connectivity and ietf- 170 service-assurance-is-is are provided to completely model the example 171 from the SAIN architecture draft 172 [I-D.ietf-opsawg-service-assurance-architecture]. 174 4. Base ietf-service-assurance YANG module 176 4.1. Tree View 178 The following tree diagram [RFC8340] provides an overview of the 179 ietf-service-assurance data model. 181 module: ietf-service-assurance 182 +--ro assurance-graph-version yang:counter64 183 +--ro assurance-graph-last-change yang:date-and-time 184 +--rw subservices 185 +--rw subservice* [type id] 186 +--rw type identityref 187 +--rw id string 188 +--ro last-change? yang:date-and-time 189 +--ro label? string 190 +--rw under-maintenance? boolean 191 +--rw maintenance-contact string 192 +--rw (parameter)? 193 | +--:(service-instance-parameter) 194 | +--rw service-instance-parameter 195 | +--rw service string 196 | +--rw instance-name string 197 +--ro health-score? union 198 +--ro symptoms-history-start? yang:date-and-time 199 +--rw symptoms 200 | +--ro symptom* [start-date-time id] 201 | +--ro id string 202 | +--ro health-score-weight? uint8 203 | +--ro description? string 204 | +--ro start-date-time yang:date-and-time 205 | +--ro stop-date-time? yang:date-and-time 206 +--rw dependencies 207 +--rw dependency* [type id] 208 +--rw type -> /subservices/subservice/type 209 +--rw id -> /subservices/subservice[type=current()/../type]/id 210 +--rw dependency-type? identityref 212 4.2. Concepts 214 The ietf-service-assurance YANG model assumes an identified number of 215 subservices, to be assured independently. A subservice is a feature 216 or a subpart of the network system that a given service instance 217 might depend on. Example of subservices include: 219 * DeviceHealthy: whether a device is healthy, and if not, what are 220 the symptoms. Potential symptoms are "CPU overloaded", "Out of 221 RAM", or "Out of TCAM". 223 * ConnectivityHealthy: given two IP addresses owned by two devices, 224 what is the quality of the connection between them. Potential 225 symptoms are "No route available" or "ECMP Imbalance". 227 The first example is a subservice representing a subpart of the 228 network system, while the second is a subservice representing a 229 feature of the network, In both cases, these subservices might depend 230 on other subservices, for instance, the connectivity might depend on 231 a subservice representing the routing mechanism and on a subservice 232 representing ECMP. 234 The status of each subservice contains a list of symptoms. Each 235 symptom is specified by a unique id and contains a health-score- 236 weight (the impact to the health score incurred by this symptom), a 237 label (text describing what the symptom is), and dates and times at 238 which the symptom was detected and stopped being detected. While the 239 unique id is sufficient as an unique key list, the start-date-time 240 second key help sorting and retrieving relevant symptoms. 242 The relation between the health score and the health-score-weight of 243 the currently active symptoms is not explictely defined in this 244 draft. The only requirement is that a non-maximal score must be 245 explained by at least one symptom. A way to enforce that requirement 246 is to first detect symptoms and then compute the health score based 247 on the health-score-weight of the detected symptoms. As an example, 248 this computation could be to sum the health-score-weight of the 249 active symptoms, substract that value from 100 and change the value 250 to 0 if negative. The relation between health-score and health- 251 score-weight is left to the implementor (of an agent 252 [I-D.ietf-opsawg-service-assurance-architecture]). To consider for 253 implementing this relation: the health-score is mostly for humans, 254 the symptoms are what the closed loop automation can build on. 256 The assurance of a given service instance can be obtained by 257 composing the assurance of the subservices that it depends on, via 258 the dependency relations. 260 A subservice declaration MUST provide: 262 * A type: identity inheriting of the base identity for subservice, 264 * An id: string uniquely identifying the subservice among those with 265 the same identity, 267 * One or more parameters, which should be specified in an augmenting 268 model, as described in the next sections. 270 The type and id uniquely identify a given subservice. They are used 271 to indicate the dependencies. Dependencies have types as well. Two 272 types are specified in the model: 274 * Impacting: such a dependency indicates an impact on the health of 275 the dependent, 277 * Informational: such a dependency might explain why the dependent 278 has issues but does not impact its health. 280 To illustrate the difference between "impacting" and "informational", 281 consider the subservice InterfaceHealthy, representing a network 282 interface. If the device to which the network interface belongs goes 283 down, the network interface will transition to a down state as well. 284 Therefore, the dependency of InterfaceHealthy towards DeviceHealthy 285 is "impacting". On the other hand, as a the dependency towards the 286 ECMPLoad subservice, which checks that the load between ECMP remains 287 ce remains stable throughout time, is only "informational". Indeed, 288 services might be perfectly healthy even if the load distribution 289 between ECMP changed. However, such an instability might be a 290 relevant symptom for diagnosing the root cause of a problem. 292 Service instances MUST be modeled as a particular type of subservice 293 with two parameters, a type and an instance name. The type is the 294 name of the service defined in the network orchestrator, for instance 295 "point-to-point-l2vpn". The instance name is the name assigned to 296 the particular instance that we are assuring, for instance the name 297 of the customer using that instance. 299 The "under-maintenance" and "maintenance-contact" flags inhibit the 300 emission of symptoms for that subservice and subservices that depend 301 on them. See Section 3.7 of 302 [I-D.ietf-opsawg-service-assurance-architecture] for a more detailed 303 discussion. 305 By specifying service instances and their dependencies in terms of 306 subservices, one defines the whole assurance to apply for them. An 307 assurance agent supporting this model should then produce telemetry 308 in return with, for each subservice: a health-status indicating how 309 healthy the subservice is and when the subservice is not healthy, a 310 list of symptoms explaining why the subservice is not healthy. 312 4.3. YANG Module 314 file "ietf-service-assurance@2022-01-04.yang" 316 module ietf-service-assurance { 317 yang-version 1.1; 318 namespace "urn:ietf:params:xml:ns:yang:ietf-service-assurance"; 319 prefix service-assurance; 321 import ietf-yang-types { 322 prefix yang; 323 } 325 organization 326 "IETF NETCONF (Network Configuration) Working Group"; 327 contact 328 "WG Web: 329 WG List: 330 Author: Benoit Claise 331 Author: Jean Quilbeuf "; 332 description 333 "This module defines objects for assuring network services based on 334 their decomposition into so-called subservices, according to the SAIN 335 (Service Assurance for Intent-based Networking) architecture. 337 The subservices hierarchically organised by dependencies constitute an 338 assurance graph. This module should be supported by an assurance agent, 339 able to interact with the devices in order to produce a health status 340 and symptoms for each subservice in the assurance graph. 342 This module is intended for the following use cases: 343 * Assurance graph configuration: 344 * subservices: configure a set of subservices to assure, by specifying 345 their types and parameters. 346 * dependencies: configure the dependencies between the subservices, 347 along with their type. 348 * Assurance telemetry: export the health status of the subservices, along 349 with the observed symptoms. 351 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 352 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 353 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 354 are to be interpreted as described in BCP 14 (RFC 2119) 355 (RFC 8174) when, and only when, they appear in all 356 capitals, as shown here. 358 Copyright (c)2021 IETF Trust and the persons identified as 359 authors of the code. All rights reserved. 361 Redistribution and use in source and binary forms, with or 362 without modification, is permitted pursuant to, and subject 363 to the license terms contained in, the Simplified BSD License 364 set forth in Section 4.c of the IETF Trust's Legal Provisions 365 Relating to IETF Documents 366 (https://trustee.ietf.org/license-info). 368 This version of this YANG module is part of RFC XXXX; see the 369 RFC itself for full legal notices. 371 TO DO: 372 - Better type (IETF or OC) for device-id, interface-id, etc. 373 - Have a YANG module for IETF and one for OC?"; 375 revision 2022-01-04 { 376 description 377 "Explicitely model a missing value"; 378 reference 379 "RFC xxxx: Title to be completed"; 380 } 381 revision 2021-06-28 { 382 description 383 "Made service-instance parameters mandatory."; 384 reference 385 "RFC xxxx: Title to be completed"; 386 } 387 revision 2020-01-13 { 388 description 389 "Added the maintenance window concept."; 390 reference 391 "RFC xxxx: Title to be completed"; 392 } 393 revision 2019-11-16 { 394 description 395 "Initial revision."; 396 reference 397 "RFC xxxx: Title to be completed"; 398 } 400 identity subservice-idty { 401 description 402 "Root identity for all subservice types."; 403 } 405 identity service-instance-idty { 406 base subservice-idty; 407 description 408 "Identity representing a service instance."; 409 } 411 identity dependency-type { 412 description 413 "Base identity for representing dependency types."; 414 } 416 identity informational-dependency { 417 base dependency-type; 418 description 419 "Indicates that symptoms of the dependency might be of interest for the 420 dependent, but the status of the dependency should not have any 421 impact on the dependent."; 422 } 424 identity impacting-dependency { 425 base dependency-type; 426 description 427 "Indicates that the status of the dependency directly impacts the status 428 of the dependent."; 429 } 431 grouping symptom { 432 description 433 "Contains the list of symptoms for a specific subservice."; 434 leaf id { 435 type string; 436 description 437 "A unique identifier for the symptom."; 438 } 439 leaf health-score-weight { 440 type uint8 { 441 range "0 .. 100"; 442 } 443 description 444 "The weight to the health score incurred by this symptom. The higher the 445 value, the more of an impact this symptom has. If a subservice health 446 score is not 100, there must be at least one symptom with a health 447 score weight larger than 0."; 448 } 449 leaf description { 450 type string; 451 description 452 "Description of the symptom, i.e. text describing what the symptom is, to 453 be computer-consumable and be displayed on a human interface. "; 454 } 455 leaf start-date-time { 456 type yang:date-and-time; 457 description 458 "Date and time at which the symptom was detected."; 459 } 460 leaf stop-date-time { 461 type yang:date-and-time; 462 description 463 "Date and time at which the symptom stopped being detected."; 464 } 465 } 466 grouping subservice-dependency { 467 description 468 "Represent a dependency to another subservice."; 469 leaf type { 470 type leafref { 471 path "/subservices/subservice/type"; 472 } 473 description 474 "The type of the subservice to refer to (e.g. DeviceHealthy)."; 475 } 476 leaf id { 477 type leafref { 478 path "/subservices/subservice[type=current()/../type]/id"; 479 } 480 description 481 "The identifier of the subservice to refer to."; 482 } 483 leaf dependency-type { 484 type identityref { 485 base dependency-type; 486 } 487 description 488 "Represents the type of dependency (i.e. informational, impacting)."; 489 } 490 // augment here if more info are needed (i.e. a percentage) depending on the dependency type. 491 } 493 leaf assurance-graph-version { 494 type yang:counter64; 495 config false; 496 mandatory true; 497 description 498 "The assurance graph version, which increases by 1 for each new version, after the changes 499 (dependencies and/or maintenance windows parameters) are applied to the subservice(s)."; 500 } 501 leaf assurance-graph-last-change { 502 type yang:date-and-time; 503 config false; 504 mandatory true; 505 description 506 "Date and time at which the assurance graph last changed after the changes (dependencies 507 and/or maintenance windows parameters) are applied to the subservice(s). These date and time 508 must be more recent or equal compared to the more recent value of any changed subservices 509 last-change"; 510 } 511 container subservices { 512 description 513 "Root container for the subservices."; 515 list subservice { 516 key "type id"; 517 description 518 "List of subservice configured."; 519 leaf type { 520 type identityref { 521 base subservice-idty; 522 } 523 description 524 "Name of the subservice, e.g. DeviceHealthy."; 525 } 526 leaf id { 527 type string; 528 description 529 "Unique identifier of the subservice instance, for each type."; 530 } 531 leaf last-change { 532 type yang:date-and-time; 533 config false; 534 description 535 "Date and time at which the assurance graph for this subservice 536 instance last changed, i.e. dependencies and/or maintenance windows parameters."; 537 } 538 leaf label { 539 type string; 540 config false; 541 description 542 "Label of the subservice, i.e. text describing what the subservice is to 543 be displayed on a human interface."; 544 } 545 leaf under-maintenance { 546 type boolean; 547 default "false"; 548 description 549 "An optional flag indicating whether this particular subservice is under 550 maintenance. Under this circumstance, the subservice symptoms and the 551 symptoms of its dependencies in the assurance graph should not be taken 552 into account. Instead, the subservice should send a 'Under Maintenance' 553 single symptom. 555 The operator changing the under-maintenance value must set the 556 maintenance-contact variable. 558 When the subservice is not under maintenance any longer, the 559 under-maintenance flag must return to its default value and 560 the under-maintenance-owner variable deleted."; 561 } 562 leaf maintenance-contact { 563 when "../under-maintenance = 'true'"; 564 type string; 565 mandatory true; 566 description 567 "A string used to model an administratively assigned name of the 568 resource that changed the under-maintenance value to 'true. 570 It is suggested that this name contain one or more of the following: 571 IP address, management station name, network manager's name, location, 572 or phone number. In some cases the agent itself will be the owner of 573 an entry. In these cases, this string shall be set to a string 574 starting with 'monitor'."; 575 } 576 choice parameter { 577 description 578 "Specify the required parameters per subservice type."; 579 container service-instance-parameter { 580 when "derived-from-or-self(../type, 'service-assurance:service-instance-idty')"; 581 description 582 "Specify the parameters of a service instance."; 583 leaf service { 584 type string; 585 mandatory true; 586 description 587 "Name of the service."; 588 } 589 leaf instance-name { 590 type string; 591 mandatory true; 592 description 593 "Name of the instance for that service."; 594 } 595 } 596 // Other modules can augment their own cases into here 597 } 598 leaf health-score { 599 type union { 600 type uint8 { 601 range "0 .. 100"; 602 } 603 type enumeration { 604 enum missing { 605 value -1; 606 description 607 "Explictly represent the fact that the health score is 608 missing. This could be used when metrics crucial to 609 establish the health score are not collected anymore."; 610 } 612 } 613 } 614 config false; 615 description 616 "Score value of the subservice health. A value of 100 means that 617 subservice is healthy. A value of 0 means that the subservice is 618 broken. A value between 0 and 100 means that the subservice is 619 degraded."; 620 } 621 leaf symptoms-history-start { 622 type yang:date-and-time; 623 config false; 624 description 625 "Date and time at which the symptoms history starts for this 626 subservice instance, either because the subservice instance 627 started at that date and time or because the symptoms before that 628 were removed due to a garbage collection process."; 629 } 630 container symptoms { 631 description 632 "Symptoms for the subservice."; 633 list symptom { 634 key "start-date-time id"; 635 config false; 636 description 637 "List of symptoms the subservice. While the start-date-time key is not 638 necessary per se, this would get the entries sorted by start-date-time 639 for easy consumption."; 640 uses symptom; 641 } 642 } 643 container dependencies { 644 description 645 "configure the dependencies between the subservices, along with their types."; 646 list dependency { 647 key "type id"; 648 description 649 "List of soft dependencies of the subservice."; 650 uses subservice-dependency; 651 } 652 } 653 } 654 } 655 } 657 659 5. Subservice Extension: ietf-service-assurance-device YANG module 661 5.1. Tree View 663 The following tree diagram [RFC8340] provides an overview of the 664 ietf-service-assurance-device data model. 666 module: ietf-service-assurance-device 668 augment /service-assurance:subservices/service-assurance:subservice/service-assurance:parameter: 669 +--rw parameters 670 +--rw device string 672 5.2. Complete Tree View 674 The following tree diagram [RFC8340] provides an overview of the 675 ietf-service-assurance and ietf-service-assurance-device data models. 677 module: ietf-service-assurance 678 +--ro assurance-graph-version yang:counter64 679 +--ro assurance-graph-last-change yang:date-and-time 680 +--rw subservices 681 +--rw subservice* [type id] 682 +--rw type identityref 683 +--rw id string 684 +--ro last-change? yang:date-and-time 685 +--ro label? string 686 +--rw under-maintenance? boolean 687 +--rw maintenance-contact string 688 +--rw (parameter)? 689 | +--:(service-instance-parameter) 690 | | +--rw service-instance-parameter 691 | | +--rw service string 692 | | +--rw instance-name string 693 | +--:(service-assurance-device:parameters) 694 | +--rw service-assurance-device:parameters 695 | +--rw service-assurance-device:device string 696 +--ro health-score? union 697 +--ro symptoms-history-start? yang:date-and-time 698 +--rw symptoms 699 | +--ro symptom* [start-date-time id] 700 | +--ro id string 701 | +--ro health-score-weight? uint8 702 | +--ro description? string 703 | +--ro start-date-time yang:date-and-time 704 | +--ro stop-date-time? yang:date-and-time 705 +--rw dependencies 706 +--rw dependency* [type id] 707 +--rw type -> /subservices/subservice/type 708 +--rw id -> /subservices/subservice[type=current()/../type]/id 709 +--rw dependency-type? identityref 711 5.3. Concepts 713 As the number of subservices will grow over time, the YANG module is 714 designed to be extensible. A new subservice type requires the 715 precise specifications of its type and expected parameters. Let us 716 illustrate the example of the new DeviceHealthy subservice type. As 717 the name implies, it monitors and reports the device health, along 718 with some symptoms in case of degradation. 720 For our DeviceHealthy subservice definition, the new identity device- 721 idty is specified, as an inheritance from the base identity for 722 subservices. This indicates to the assurance agent that we are now 723 assuring the health of a device. 725 The typical parameter for the configuration of the DeviceHealthy 726 subservice is the name of the device that we want to assure. By 727 augmenting the parameter choice from ietf-service-assurance YANG 728 module for the case of the device-idty subservice type, this new 729 parameter is specified. 731 5.4. YANG Module 733 file "ietf-service-assurance-device@2021-06-28.yang" 735 module ietf-service-assurance-device { 736 yang-version 1.1; 737 namespace "urn:ietf:params:xml:ns:yang:ietf-service-assurance-device"; 738 prefix service-assurance-device; 740 import ietf-service-assurance { 741 prefix service-assurance; 742 } 744 organization 745 "IETF NETCONF (Network Configuration) Working Group"; 746 contact 747 "WG Web: 748 WG List: 749 Author: Benoit Claise 750 Author: Jean Quilbeuf "; 751 description 752 "This module extends the ietf-service-assurance module to add 753 support for the subservice DeviceHealthy. 755 Checks whether a network device is healthy. 757 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 758 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 759 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 760 are to be interpreted as described in BCP 14 (RFC 2119) 761 (RFC 8174) when, and only when, they appear in all 762 capitals, as shown here. 764 Copyright (c) 2021 IETF Trust and the persons identified as 765 authors of the code. All rights reserved. 767 Redistribution and use in source and binary forms, with or 768 without modification, is permitted pursuant to, and subject 769 to the license terms contained in, the Simplified BSD License 770 set forth in Section 4.c of the IETF Trust's Legal Provisions 771 Relating to IETF Documents 772 (https://trustee.ietf.org/license-info). 774 This version of this YANG module is part of RFC XXXX; see the 775 RFC itself for full legal notices. "; 777 revision 2021-06-28 { 778 description 779 "Renamed the container for parameters."; 780 reference 781 "RFC xxxx: Title to be completed"; 782 } 783 revision 2020-01-13 { 784 description 785 "Added the maintenance window concept."; 786 reference 787 "RFC xxxx: Title to be completed"; 788 } 789 revision 2019-11-16 { 790 description 791 "Initial revision."; 792 reference 793 "RFC xxxx: Title to be completed"; 794 } 796 identity device-idty { 797 base service-assurance:subservice-idty; 798 description 799 "Network Device is healthy."; 800 } 802 augment "/service-assurance:subservices/service-assurance:subservice/service-assurance:parameter" { 803 description 804 "Specify the required parameters for a new subservice type"; 805 container parameters { 806 when "derived-from-or-self(../service-assurance:type, 'device-idty')"; 807 description 808 "Specify the required parameters for the device-idty subservice type"; 809 leaf device { 810 type string; 811 mandatory true; 812 description 813 "The device to monitor."; 814 } 815 } 816 } 817 } 819 821 6. Subservice Extension: ietf-service-assurance-interface YANG module 823 6.1. Tree View 825 The following tree diagram [RFC8340] provides an overview of the 826 ietf-service-assurance-interface data model. 828 module: ietf-service-assurance-interface 830 augment /service-assurance:subservices/service-assurance:subservice/service-assurance:parameter: 831 +--rw parameters 832 +--rw device string 833 +--rw interface string 835 6.2. Complete Tree View 837 The following tree diagram [RFC8340] provides an overview of the 838 ietf-service-assurance, ietf-service-assurance-device, and ietf- 839 service-assurance-interface data models. 841 module: ietf-service-assurance 842 +--ro assurance-graph-version yang:counter64 843 +--ro assurance-graph-last-change yang:date-and-time 844 +--rw subservices 845 +--rw subservice* [type id] 846 +--rw type identityref 847 +--rw id string 848 +--ro last-change? yang:date-and-time 849 +--ro label? string 850 +--rw under-maintenance? boolean 851 +--rw maintenance-contact string 852 +--rw (parameter)? 853 | +--:(service-instance-parameter) 854 | | +--rw service-instance-parameter 855 | | +--rw service string 856 | | +--rw instance-name string 857 | +--:(service-assurance-interface:parameters) 858 | | +--rw service-assurance-interface:parameters 859 | | +--rw service-assurance-interface:device string 860 | | +--rw service-assurance-interface:interface string 861 | +--:(service-assurance-device:parameters) 862 | +--rw service-assurance-device:parameters 863 | +--rw service-assurance-device:device string 864 +--ro health-score? union 865 +--ro symptoms-history-start? yang:date-and-time 866 +--rw symptoms 867 | +--ro symptom* [start-date-time id] 868 | +--ro id string 869 | +--ro health-score-weight? uint8 870 | +--ro description? string 871 | +--ro start-date-time yang:date-and-time 872 | +--ro stop-date-time? yang:date-and-time 873 +--rw dependencies 874 +--rw dependency* [type id] 875 +--rw type -> /subservices/subservice/type 876 +--rw id -> /subservices/subservice[type=current()/../type]/id 877 +--rw dependency-type? identityref 879 6.3. Concepts 881 For our InterfaceHealthy subservice definition, the new interface- 882 idty is specified, as an inheritance from the base identity for 883 subservices. This indicates to the assurance agent that we are now 884 assuring the health of an interface. 886 The typical parameters for the configuration of the InterfaceHealthy 887 subservice are the name of the device and, on that specific device, a 888 specific interface. By augmenting the parameter choice from ietf- 889 service-assurance YANG module for the case of the interface-idty 890 subservice type, those two new parameter are specified. 892 6.4. YANG Module 894 file "ietf-service-assurance-interface@2021-06-28.yang" 896 module ietf-service-assurance-interface { 897 yang-version 1.1; 898 namespace "urn:ietf:params:xml:ns:yang:ietf-service-assurance-interface"; 899 prefix service-assurance-interface; 901 import ietf-service-assurance { 902 prefix service-assurance; 903 } 905 organization 906 "IETF OPSAWG Working Group"; 907 contact 908 "WG Web: 909 WG List: 910 Author: Benoit Claise 911 Author: Jean Quilbeuf "; 912 description 913 "This module extends the ietf-service-assurance module to add 914 support for the subservice InterfaceHealthy. 916 Checks whether an interface is healthy. 918 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 919 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 920 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 921 are to be interpreted as described in BCP 14 (RFC 2119) 922 (RFC 8174) when, and only when, they appear in all 923 capitals, as shown here. 925 Copyright (c) 2021 IETF Trust and the persons identified as 926 authors of the code. All rights reserved. 927 Redistribution and use in source and binary forms, with or 928 without modification, is permitted pursuant to, and subject 929 to the license terms contained in, the Simplified BSD License 930 set forth in Section 4.c of the IETF Trust's Legal Provisions 931 Relating to IETF Documents 932 (https://trustee.ietf.org/license-info). 934 This version of this YANG module is part of RFC XXXX; see the 935 RFC itself for full legal notices. "; 937 revision 2021-06-28 { 938 description 939 "Regroup parameters in a container."; 940 reference 941 "RFC xxxx: Title to be completed"; 942 } 943 revision 2020-01-13 { 944 description 945 "Initial revision."; 946 reference 947 "RFC xxxx: Title to be completed"; 948 } 950 identity interface-idty { 951 base service-assurance:subservice-idty; 952 description 953 "Checks whether an interface is healthy."; 954 } 956 augment "/service-assurance:subservices/service-assurance:subservice/service-assurance:parameter" { 957 description 958 "Specify the required parameters for the interface-idty subservice type"; 959 container parameters { 960 when "derived-from-or-self(../service-assurance:type, 'interface-idty')"; 961 description 962 "Required parameters for the interface-idty subservice type"; 963 leaf device { 964 type string; 965 mandatory true; 966 description 967 "Device supporting the interface."; 968 } 969 leaf interface { 970 type string; 971 mandatory true; 972 description 973 "Name of the interface."; 974 } 975 } 976 } 977 } 979 981 7. Vendor-specific Subservice Extension: example-service-assurance- 982 device-acme YANG module 984 7.1. Tree View 986 The following tree diagram [RFC8340] provides an overview of the 987 example-service-assurance-device-acme data model. 989 module: example-service-assurance-device-acme 991 augment /service-assurance:subservices/service-assurance:subservice/service-assurance:parameter: 992 +--rw parameters 993 +--rw device string 994 +--rw acme-specific-parameter string 996 7.2. Complete Tree View 998 The following tree diagram [RFC8340] provides an overview of the 999 ietf-service-assurance, ietf-service-assurance-device, and example- 1000 service-assurance-device-acme data models. 1002 module: ietf-service-assurance 1003 +--ro assurance-graph-version yang:counter64 1004 +--ro assurance-graph-last-change yang:date-and-time 1005 +--rw subservices 1006 +--rw subservice* [type id] 1007 +--rw type identityref 1008 +--rw id string 1009 +--ro last-change? yang:date-and-time 1010 +--ro label? string 1011 +--rw under-maintenance? boolean 1012 +--rw maintenance-contact string 1013 +--rw (parameter)? 1014 | +--:(service-instance-parameter) 1015 | | +--rw service-instance-parameter 1016 | | +--rw service string 1017 | | +--rw instance-name string 1018 | +--:(service-assurance-device:parameters) 1019 | | +--rw service-assurance-device:parameters 1020 | | +--rw service-assurance-device:device string 1021 | +--:(example-service-assurance-device-acme:parameters) 1022 | | +--rw example-service-assurance-device-acme:parameters 1023 | | +--rw example-service-assurance-device-acme:device string 1024 | | +--rw example-service-assurance-device-acme:acme-specific-parameter string 1025 | +--:(service-assurance-interface:parameters) 1026 | +--rw service-assurance-interface:parameters 1027 | +--rw service-assurance-interface:device string 1028 | +--rw service-assurance-interface:interface string 1029 +--ro health-score? union 1030 +--ro symptoms-history-start? yang:date-and-time 1031 +--rw symptoms 1032 | +--ro symptom* [start-date-time id] 1033 | +--ro id string 1034 | +--ro health-score-weight? uint8 1035 | +--ro description? string 1036 | +--ro start-date-time yang:date-and-time 1037 | +--ro stop-date-time? yang:date-and-time 1038 +--rw dependencies 1039 +--rw dependency* [type id] 1040 +--rw type -> /subservices/subservice/type 1041 +--rw id -> /subservices/subservice[type=current()/../type]/id 1042 +--rw dependency-type? identityref 1044 7.3. Concepts 1046 Under some circumstances, vendor-specific subservice types might be 1047 required. As an example of this vendor-specific implementation, this 1048 section shows how to augment the ietf-service-assurance-device module 1049 to add support for the subservice DeviceHealthy, specific to the ACME 1050 Corporation. The new parameter is acme-specific-parameter. 1052 7.4. YANG Module 1054 module example-service-assurance-device-acme { 1055 yang-version 1.1; 1056 namespace "urn:example:example-service-assurance-device-acme"; 1057 prefix example-service-assurance-device-acme; 1059 import ietf-service-assurance { 1060 prefix service-assurance; 1061 } 1062 import ietf-service-assurance-device { 1063 prefix service-assurance-device; 1064 } 1066 organization 1067 "IETF NETCONF (Network Configuration) Working Group"; 1068 contact 1069 "WG Web: 1070 WG List: 1071 Author: Benoit Claise 1072 Author: Jean Quilbeuf "; 1073 description 1074 "This module extends the ietf-service-assurance-device module to add 1075 support for the subservice DeviceHealthy, specific to the ACME Corporation. 1077 ACME Network Device is healthy. 1079 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 1080 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 1081 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 1082 are to be interpreted as described in BCP 14 (RFC 2119) 1083 (RFC 8174) when, and only when, they appear in all 1084 capitals, as shown here. 1086 Copyright (c) 2021 IETF Trust and the persons identified as 1087 authors of the code. All rights reserved. 1089 Redistribution and use in source and binary forms, with or 1090 without modification, is permitted pursuant to, and subject 1091 to the license terms contained in, the Simplified BSD License 1092 set forth in Section 4.c of the IETF Trust's Legal Provisions 1093 Relating to IETF Documents 1094 (https://trustee.ietf.org/license-info). 1096 This version of this YANG module is part of RFC XXXX; see the 1097 RFC itself for full legal notices. "; 1099 revision 2021-06-28 { 1100 description 1101 "Renamed the parameters container."; 1102 reference 1103 "RFC xxxx: Title to be completed"; 1104 } 1105 revision 2020-01-13 { 1106 description 1107 "Added the maintenance window concept."; 1108 reference 1109 "RFC xxxx: Title to be completed"; 1110 } 1111 revision 2019-11-16 { 1112 description 1113 "Initial revision."; 1114 reference 1115 "RFC xxxx: Title to be completed"; 1116 } 1118 identity device-acme-idty { 1119 base service-assurance-device:device-idty; 1120 description 1121 "Network Device is healthy."; 1122 } 1124 augment "/service-assurance:subservices/service-assurance:subservice/service-assurance:parameter" { 1125 description 1126 "Specify the required parameters for a new subservice type"; 1127 container parameters { 1128 when "derived-from-or-self(../service-assurance:type, 'device-acme-idty')"; 1129 description 1130 "Specify the required parameters for the device-acme-idty subservice type"; 1131 leaf device { 1132 type string; 1133 mandatory true; 1134 description 1135 "The device to monitor."; 1136 } 1137 leaf acme-specific-parameter { 1138 type string; 1139 mandatory true; 1140 description 1141 "The ACME Corporation sepcific parameter."; 1142 } 1143 } 1144 } 1145 } 1147 8. Further Extensions: IP Connectivity and IS-IS subservices 1149 8.1. IP Connectivity Tree View 1151 The following tree diagram [RFC8340] provides an overview of the 1152 ietf-service-assurance-ip-connectivity data model. 1154 module: ietf-service-assurance-ip-connectivity 1156 augment /service-assurance:subservices/service-assurance:subservice/service-assurance:parameter: 1157 +--rw parameters 1158 +--rw device1 string 1159 +--rw address1 inet:ip-address 1160 +--rw device2 string 1161 +--rw address2 inet:ip-address 1163 To specify the connectivity that we are interested in, we specify two 1164 IP addresses and two devices. The subservice assures that the 1165 connectivity between IP address 1 on device 1 and IP address 2 on 1166 device 2 is healthy. 1168 8.2. IS-IS Tree View 1170 The following tree diagram [RFC8340] provides an overview of the 1171 ietf-service-assurance-is-is data model. 1173 module: ietf-service-assurance-is-is 1175 augment /service-assurance:subservices/service-assurance:subservice/service-assurance:parameter: 1176 +--rw parameters 1177 +--rw instance-name string 1179 The parameter of this subservice is the name of the IS-IS instance to 1180 assure. 1182 8.3. Global Tree View 1184 The following tree diagram [RFC8340] provides an overview of the 1185 ietf-service-assurance, ietf-service-assurance-device, example- 1186 service-assurance-device-acme, ietf-service-assurance-ip-connectivity 1187 and ietf-service-assurance-is-is data models. 1189 module: ietf-service-assurance 1190 +--ro assurance-graph-version yang:counter64 1191 +--ro assurance-graph-last-change yang:date-and-time 1192 +--rw subservices 1193 +--rw subservice* [type id] 1194 +--rw type identityref 1195 +--rw id string 1196 +--ro last-change? yang:date-and-time 1197 +--ro label? string 1198 +--rw under-maintenance? boolean 1199 +--rw maintenance-contact string 1200 +--rw (parameter)? 1201 | +--:(service-instance-parameter) 1202 | | +--rw service-instance-parameter 1203 | | +--rw service string 1204 | | +--rw instance-name string 1205 | +--:(service-assurance-ip-connectivity:parameters) 1206 | | +--rw service-assurance-ip-connectivity:parameters 1207 | | +--rw service-assurance-ip-connectivity:device1 string 1208 | | +--rw service-assurance-ip-connectivity:address1 inet:ip-address 1209 | | +--rw service-assurance-ip-connectivity:device2 string 1210 | | +--rw service-assurance-ip-connectivity:address2 inet:ip-address 1211 | +--:(service-assurance-is-is:parameters) 1212 | | +--rw service-assurance-is-is:parameters 1213 | | +--rw service-assurance-is-is:instance-name string 1214 | +--:(service-assurance-device:parameters) 1215 | | +--rw service-assurance-device:parameters 1216 | | +--rw service-assurance-device:device string 1217 | +--:(example-service-assurance-device-acme:parameters) 1218 | | +--rw example-service-assurance-device-acme:parameters 1219 | | +--rw example-service-assurance-device-acme:device string 1220 | | +--rw example-service-assurance-device-acme:acme-specific-parameter string 1221 | +--:(service-assurance-interface:parameters) 1222 | +--rw service-assurance-interface:parameters 1223 | +--rw service-assurance-interface:device string 1224 | +--rw service-assurance-interface:interface string 1225 +--ro health-score? union 1226 +--ro symptoms-history-start? yang:date-and-time 1227 +--rw symptoms 1228 | +--ro symptom* [start-date-time id] 1229 | +--ro id string 1230 | +--ro health-score-weight? uint8 1231 | +--ro description? string 1232 | +--ro start-date-time yang:date-and-time 1233 | +--ro stop-date-time? yang:date-and-time 1234 +--rw dependencies 1235 +--rw dependency* [type id] 1236 +--rw type -> /subservices/subservice/type 1237 +--rw id -> /subservices/subservice[type=current()/../type]/id 1238 +--rw dependency-type? identityref 1240 8.4. IP Connectivity YANG Module 1242 file "ietf-service-assurance-ip- 1243 connectivity@2021-06-28.yang" 1245 module ietf-service-assurance-ip-connectivity { 1246 yang-version 1.1; 1247 namespace "urn:ietf:params:xml:ns:yang:ietf-service-assurance-ip-connectivity"; 1248 prefix service-assurance-ip-connectivity; 1250 import ietf-inet-types { 1251 prefix inet; 1252 } 1253 import ietf-service-assurance { 1254 prefix service-assurance; 1255 } 1257 organization 1258 "IETF OPSAWG Working Group"; 1259 contact 1260 "WG Web: 1261 WG List: 1262 Author: Benoit Claise 1263 Author: Jean Quilbeuf "; 1264 description 1265 "This module extends the ietf-service-assurance module to add 1266 support for the subservice ip-connectivity. 1268 Checks whether the ip connectivity between two ip addresses 1269 belonging to two network devices is healthy. 1271 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 1272 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 1273 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 1274 are to be interpreted as described in BCP 14 (RFC 2119) 1275 (RFC 8174) when, and only when, they appear in all 1276 capitals, as shown here. 1278 Copyright (c) 2021 IETF Trust and the persons identified as 1279 authors of the code. All rights reserved. 1280 Redistribution and use in source and binary forms, with or 1281 without modification, is permitted pursuant to, and subject 1282 to the license terms contained in, the Simplified BSD License 1283 set forth in Section 4.c of the IETF Trust's Legal Provisions 1284 Relating to IETF Documents 1285 (https://trustee.ietf.org/license-info). 1287 This version of this YANG module is part of RFC XXXX; see the 1288 RFC itself for full legal notices. "; 1290 revision 2021-06-28 { 1291 description 1292 "Initial revision."; 1293 reference 1294 "RFC xxxx: Title to be completed"; 1295 } 1297 identity ip-connectivity-idty { 1298 base service-assurance:subservice-idty; 1299 description 1300 "Checks connectivity between two IP addresses."; 1301 } 1303 augment "/service-assurance:subservices/service-assurance:subservice/service-assurance:parameter" { 1304 description 1305 "Specify the required parameters for the ip-connectivity-idty subservice type"; 1306 container parameters { 1307 when "derived-from-or-self(../service-assurance:type, 'ip-connectivity-idty')"; 1308 description 1309 "Required parameters for the ip-connectivity-idty subservice type"; 1310 leaf device1 { 1311 type string; 1312 mandatory true; 1313 description 1314 "Device at the first end of the connection."; 1315 } 1316 leaf address1 { 1317 type inet:ip-address; 1318 mandatory true; 1319 description 1320 "Address at the first end of the connection."; 1321 } 1322 leaf device2 { 1323 type string; 1324 mandatory true; 1325 description 1326 "Device at the second end of the connection."; 1327 } 1328 leaf address2 { 1329 type inet:ip-address; 1330 mandatory true; 1331 description 1332 "Address at the second end of the connection."; 1333 } 1334 } 1335 } 1336 } 1338 1340 8.5. IS-IS YANG Module 1342 file "ietf-service-assurance-is-is@2021-06-28.yang" 1344 module ietf-service-assurance-is-is { 1345 yang-version 1.1; 1346 namespace "urn:ietf:params:xml:ns:yang:ietf-service-assurance-is-is"; 1347 prefix service-assurance-is-is; 1349 import ietf-service-assurance { 1350 prefix service-assurance; 1351 } 1353 organization 1354 "IETF NETCONF (Network Configuration) Working Group"; 1355 contact 1356 "WG Web: 1357 WG List: 1358 Author: Benoit Claise 1359 Author: Jean Quilbeuf "; 1360 description 1361 "This module extends the ietf-service-assurance module to add 1362 support for the subservice IS-ISHealthy. 1364 Checks whether an IS-IS instance 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) 2021 IETF Trust and the persons identified as 1374 authors of the code. All rights reserved. 1376 Redistribution and use in source and binary forms, with or 1377 without modification, is permitted pursuant to, and subject 1378 to the license terms contained in, the Simplified BSD License 1379 set forth in Section 4.c of the IETF Trust's Legal Provisions 1380 Relating to IETF Documents 1381 (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 2021-06-28 { 1386 description 1387 "Initial revision."; 1388 reference 1389 "RFC xxxx: Title to be completed"; 1390 } 1392 identity is-is-idty { 1393 base service-assurance:subservice-idty; 1394 description 1395 "Health of IS-IS routing protocol."; 1396 } 1398 augment "/service-assurance:subservices/service-assurance:subservice/service-assurance:parameter" { 1399 description 1400 "Specify the required parameters for a new subservice type"; 1401 container parameters { 1402 when "derived-from-or-self(../service-assurance:type, 'is-is-idty')"; 1403 description 1404 "Specify the required parameters for the IS-IS subservice type"; 1405 leaf instance-name { 1406 type string; 1407 mandatory true; 1408 description 1409 "The instance to monitor."; 1410 } 1411 } 1412 } 1413 } 1415 1417 9. Guidelines for Specific Subservice Extension 1419 The base YANG module defined in Section 4.3 only defines a single 1420 type of subservices that represent service instances. As explained 1421 above, this model is meant to be augmented so that a variety of 1422 subservices can be used in the assurance graph. In this section, we 1423 propose some guidelines in order to build theses extensions. 1425 First, the specific subservice must be given an adequate unique short 1426 name that will be used to form longer names (e.g. module name, prefix 1427 ...) appearing in the YANG module. The short name identifies the 1428 type of subpart of feature that the subservice will represent, for 1429 instance if the subservice will assure the health of a network 1430 interafce then "interface" is an adequate short name. If the 1431 subservice will assure the IS-IS routing protocol, then "is-is" is an 1432 adequate short name. The short name must be in kebab-case. 1434 In this section, by subservice YANG module, we mean "YANG module that 1435 extends ieft-service-assurance in order to define a specific 1436 subservice". 1438 9.1. Module Name 1440 For subservice YANG modules vetted by the IETF, the module name 1441 should be "ieft-service-assurance-" followed by the short name. For 1442 instance, "ietf-service-assurance-interface" or "ietf-service- 1443 assurance-is-is". 1445 For subservice YANG module that are directly provided by vendors, we 1446 propose that they use the company in the prefix. For example, the 1447 prefix for the company "acme" would be "acme-assurance-" and the YANG 1448 modules would be "acme-assurance-interface", "acme-assurance-is-is", 1449 etc. 1451 9.2. Module Namespace 1453 For subservice YANG modules vetted by the IETF, the module namespace 1454 should be "urn:ietf:params:xml:ns:yang:ietf-service-assurance-" 1455 followed by the short name. For instance, 1456 "urn:ietf:params:xml:ns:yang:ietf-service-assurance-interface" or 1457 "urn:ietf:params:xml:ns:yang:ietf-service-assurance-is-is". 1459 For subservice YANG module that are directly provided by vendors, a 1460 similar pattern can be used with the prefix being a namespace 1461 controlled by the vendor. 1463 9.3. Module Prefix 1465 For subservice YANG modules vetted by the IETF, the module prefix 1466 should be "service-assurance-" followed by the short name. For 1467 instance, "service-assurance-interface" or "service-assurance-is-is". 1469 For subservice YANG module that are directly provided by vendors, the 1470 same pattern can be used provided it does not conflict with an 1471 imported prefix. 1473 9.4. Subservice Specific Identity 1475 Each auqment specific to a subservice must define an identity 1476 representing the type of subpart or features of the network system 1477 that are assured by the subservice. As required in the "ietf- 1478 service-assurance" module (see Section 4.3), that identity must be 1479 based on the "subservice-idty" identity. 1481 For subservice YANG modules vetted by the IETF, the subservice 1482 specific identity should be the short name of the subservice followed 1483 by "-idty". For instance, "interface-idty" or "is-is-identity". 1485 For subservice YANG module that are directly provided by vendors, the 1486 same pattern can be used. 1488 9.5. Parameters 1490 For subservice YANG modules vetted by the IETF, the parameters 1491 specific to the subservice should be placed in a container named 1492 "parameters". That container must be used to augment the "parameter" 1493 choice from the module "ietf-service-assurance" (see Section 4.3 and 1494 that augment must be guarded so that it is effective only for 1495 subservice instance whose type is the subservice specific identity 1496 from Section 9.4. 1498 For subservice YANG module that are directly provided by vendors, the 1499 same pattern can be used. 1501 10. Security Considerations 1503 The YANG module specified in this document defines a schema for data 1504 that is designed to be accessed via network management protocols such 1505 as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer 1506 is the secure transport layer, and the mandatory-to-implement secure 1507 transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer 1508 is HTTPS, and the mandatory-to-implement secure transport is TLS 1509 [RFC8446]. 1511 The Network Configuration Access Control Model (NACM) [RFC8341] 1512 provides the means to restrict access for particular NETCONF or 1513 RESTCONF users to a preconfigured subset of all available NETCONF or 1514 RESTCONF protocol operations and content. 1516 There are a number of data nodes defined in this YANG module that are 1517 writable/ creatable/deletable (i.e., config true, which is the 1518 default). These data nodes may be considered sensitive or vulnerable 1519 in some network environments. Write operations (e.g., edit-config) 1520 to these data nodes without proper protection can have a negative 1521 effect on network operations. These are the subtrees and data nodes 1522 and their sensitivity/vulnerability: 1524 * /subservices/subservice/type 1526 * /subservices/subservice/id 1528 * /subservices/subservice/under-maintenance 1530 * /subservices/subservice/maintenance-contact 1532 11. IANA Considerations 1534 11.1. The IETF XML Registry 1536 This document registers two URIs in the IETF XML registry [RFC3688]. 1537 Following the format in [RFC3688], the following registrations are 1538 requested: 1540 URI: urn:ietf:params:xml:ns:yang:ietf-service-assurance 1541 Registrant Contact: The NETCONF WG of the IETF. 1542 XML: N/A, the requested URI is an XML namespace. 1544 URI: urn:ietf:params:xml:ns:yang:ietf-service-assurance-device 1545 Registrant Contact: The NETCONF WG of the IETF. 1546 XML: N/A, the requested URI is an XML namespace. 1548 URI: urn:ietf:params:xml:ns:yang:ietf-service-assurance-interface 1549 Registrant Contact: The NETCONF WG of the IETF. 1550 XML: N/A, the requested URI is an XML namespace. 1552 11.2. The YANG Module Names Registry 1554 This document registers three YANG modules in the YANG Module Names 1555 registry [RFC7950]. Following the format in [RFC7950], the the 1556 following registrations are requested: 1558 name: ietf-service-assurance 1559 namespace: urn:ietf:params:xml:ns:yang:ietf-service-assurance 1560 prefix: inc 1561 reference: RFC XXXX 1563 name: ietf-service-assurance-device 1564 namespace: urn:ietf:params:xml:ns:yang:ietf-service-assurance-device 1565 prefix: inc 1566 reference: RFC XXXX 1568 name: ietf-service-assurance-interface 1569 namespace: urn:ietf:params:xml:ns:yang:ietf-service-assurance-interface 1570 prefix: inc 1571 reference: RFC XXXX 1573 12. Open Issues 1575 -None 1577 13. References 1579 13.1. Normative References 1581 [I-D.ietf-opsawg-service-assurance-architecture] 1582 Claise, B.C., Quilbeuf, J.Q., Lopez, D.L., Voyer, D.V., 1583 and T.A. Arumugam, "draft-claise-opsawg-service-assurance- 1584 architecture", 2020. 1586 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1587 and A. Bierman, Ed., "Network Configuration Protocol 1588 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1589 . 1591 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 1592 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 1593 . 1595 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1596 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1597 . 1599 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1600 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1601 . 1603 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 1604 Access Control Model", STD 91, RFC 8341, 1605 DOI 10.17487/RFC8341, March 2018, 1606 . 1608 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 1609 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 1610 . 1612 13.2. Informative References 1614 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1615 Requirement Levels", BCP 14, RFC 2119, 1616 DOI 10.17487/RFC2119, March 1997, 1617 . 1619 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1620 DOI 10.17487/RFC3688, January 2004, 1621 . 1623 [RFC7895] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module 1624 Library", RFC 7895, DOI 10.17487/RFC7895, June 2016, 1625 . 1627 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1628 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1629 May 2017, . 1631 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 1632 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 1633 . 1635 Appendix A. Example of YANG instances 1637 This section contains examples of YANG instances that conform to the 1638 YANG modules. The validity of these data instances has been checked 1639 using yangson (https://yangson.labs.nic.cz/). Yangson requires a 1640 YANG library [RFC7895] to define the complete model against which the 1641 data instance must be validated. We provide in Appendix B the JSON 1642 library file, named "ietf-service-assurance-library.json", that we 1643 used for validation. 1645 We provide below the contents of the file 1646 "example_configuration_instance.json" which contains the 1647 configuration data that models the Figure 2 of 1648 [I-D.ietf-opsawg-service-assurance-architecture]. The instance can 1649 be validated with yangson by using the invocation "yangson -v 1650 example_configuration_instance.json ietf-service-assurance- 1651 library.json", assuming all the files (YANG and JSON) defined in this 1652 draft reside in the current folder. 1654 file "example_configuration_instance.json" 1656 { 1657 "ietf-service-assurance:subservices": { 1658 "subservice": [ 1659 { 1660 "type": "service-instance-idty", 1661 "id": "simple-tunnel/example", 1662 "service-instance-parameter": { 1663 "service": "simple-tunnel", 1664 "instance-name": "example" 1665 }, 1666 "dependencies": { 1667 "dependency": [ 1668 { 1669 "type": "ietf-service-assurance-interface:interface-idty", 1670 "id": "interface/peer1/tunnel0", 1671 "dependency-type": "impacting-dependency" 1672 }, 1673 { 1674 "type": "ietf-service-assurance-interface:interface-idty", 1675 "id": "interface/peer2/tunnel9", 1676 "dependency-type": "impacting-dependency" 1677 }, 1678 { 1679 "type": "ietf-service-assurance-ip-connectivity:ip-connectivity-idty", 1680 "id": "connectivity/peer1/2001:db8::1/peer2/2001:db8::2", 1681 "dependency-type": "impacting-dependency" 1682 } 1683 ] 1684 } 1685 }, 1686 { 1687 "type": "ietf-service-assurance-ip-connectivity:ip-connectivity-idty", 1688 "id": "connectivity/peer1/2001:db8::1/peer2/2001:db8::2", 1689 "ietf-service-assurance-ip-connectivity:parameters": { 1690 "device1": "Peer1", 1691 "address1": "2001:db8::1", 1692 "device2": "Peer2", 1693 "address2": "2001:db8::2" 1694 }, 1695 "dependencies": { 1696 "dependency": [ 1697 { 1698 "type": "ietf-service-assurance-interface:interface-idty", 1699 "id": "interface/peer1/physical0", 1700 "dependency-type": "impacting-dependency" 1701 }, 1702 { 1703 "type": "ietf-service-assurance-interface:interface-idty", 1704 "id": "interface/peer2/physical5", 1705 "dependency-type": "impacting-dependency" 1706 }, 1707 { 1708 "type": "ietf-service-assurance-is-is:is-is-idty", 1709 "id": "is-is/instance1", 1710 "dependency-type": "impacting-dependency" 1711 } 1712 ] 1713 } 1714 }, 1715 { 1716 "type": "ietf-service-assurance-is-is:is-is-idty", 1717 "id": "is-is/instance1", 1718 "ietf-service-assurance-is-is:parameters": { 1719 "instance-name": "instance1" 1720 } 1721 }, 1722 { 1723 "type": "ietf-service-assurance-interface:interface-idty", 1724 "id": "interface/peer1/tunnel0", 1725 "ietf-service-assurance-interface:parameters": { 1726 "device": "Peer1", 1727 "interface": "tunnel0" 1728 }, 1729 "dependencies": { 1730 "dependency": [ 1731 { 1732 "type": "ietf-service-assurance-interface:interface-idty", 1733 "id": "interface/peer1/physical0", 1734 "dependency-type": "impacting-dependency" 1735 } 1736 ] 1737 } 1738 }, 1739 { 1740 "type": "ietf-service-assurance-interface:interface-idty", 1741 "id": "interface/peer1/physical0", 1742 "ietf-service-assurance-interface:parameters": { 1743 "device": "Peer1", 1744 "interface": "physical0" 1745 }, 1746 "dependencies": { 1747 "dependency": [ 1748 { 1749 "type": "ietf-service-assurance-device:device-idty", 1750 "id": "interface/peer1", 1751 "dependency-type": "impacting-dependency" 1752 } 1753 ] 1754 } 1755 }, 1756 { 1757 "type": "ietf-service-assurance-device:device-idty", 1758 "id": "interface/peer1", 1759 "ietf-service-assurance-device:parameters": { 1760 "device": "Peer1" 1761 } 1762 }, 1763 { 1764 "type": "ietf-service-assurance-interface:interface-idty", 1765 "id": "interface/peer2/tunnel9", 1766 "ietf-service-assurance-interface:parameters": { 1767 "device": "Peer2", 1768 "interface": "tunnel9" 1769 }, 1770 "dependencies": { 1771 "dependency": [ 1772 { 1773 "type": "ietf-service-assurance-interface:interface-idty", 1774 "id": "interface/peer2/physical5", 1775 "dependency-type": "impacting-dependency" 1776 } 1777 ] 1778 } 1779 }, 1780 { 1781 "type": "ietf-service-assurance-interface:interface-idty", 1782 "id": "interface/peer2/physical5", 1783 "ietf-service-assurance-interface:parameters": { 1784 "device": "Peer2", 1785 "interface": "physical5" 1786 }, 1787 "dependencies": { 1788 "dependency": [ 1789 { 1790 "type": "ietf-service-assurance-device:device-idty", 1791 "id": "interface/peer2", 1792 "dependency-type": "impacting-dependency" 1793 } 1794 ] 1795 } 1796 }, 1797 { 1798 "type": "ietf-service-assurance-device:device-idty", 1799 "id": "interface/peer2", 1800 "ietf-service-assurance-device:parameters": { 1801 "device": "Peer2" 1802 } 1803 } 1804 ] 1805 } 1806 } 1808 1810 Appendix B. YANG Library for Service Assurance 1812 This section provides the JSON encoding of the YANG library [RFC7895] 1813 listing all modules defined in this draft and their dependencies. 1814 This library can be used to validate data instances using yangson, as 1815 explained in the previous section. 1817 file "ietf-service-assurance-library.json" 1819 { 1820 "ietf-yang-library:modules-state": { 1821 "module-set-id": "ietf-service-assurance@2020-01-13", 1822 "module": [ 1823 { 1824 "name": "ietf-service-assurance", 1825 "namespace": "urn:ietf:params:xml:ns:yang:ietf-service-assurance", 1826 "revision": "2021-06-28", 1827 "conformance-type": "implement" 1828 }, 1829 { 1830 "name": "ietf-service-assurance-device", 1831 "namespace": "urn:ietf:params:xml:ns:yang:ietf-service-assurance-device", 1832 "revision": "2021-06-28", 1833 "conformance-type": "implement" 1834 }, 1835 { 1836 "name": "ietf-service-assurance-interface", 1837 "namespace": "urn:ietf:params:xml:ns:yang:ietf-service-assurance-interface", 1838 "revision": "2021-06-28", 1839 "conformance-type": "implement" 1840 }, 1841 { 1842 "name": "example-service-assurance-device-acme", 1843 "namespace": "urn:example:example-service-assurance-device-acme", 1844 "revision": "2021-06-28", 1845 "conformance-type": "implement" 1846 }, 1847 { 1848 "name": "ietf-service-assurance-is-is", 1849 "namespace": "urn:ietf:payams:xml:ns:yang:ietf-service-assurance-is-is", 1850 "revision": "2021-06-28", 1851 "conformance-type": "implement" 1852 }, 1853 { 1854 "name": "ietf-service-assurance-ip-connectivity", 1855 "namespace": "urn:ietf:payams:xml:ns:yang:ietf-service-assurance-ip-connectivity", 1856 "revision": "2021-06-28", 1857 "conformance-type": "implement" 1858 }, 1859 { 1860 "name": "ietf-yang-types", 1861 "namespace": "urn:ietf:params:xml:ns:yang:ietf-yang-types", 1862 "revision": "2021-04-14", 1863 "conformance-type": "import" 1864 }, 1865 { 1866 "name": "ietf-inet-types", 1867 "namespace": "urn:ietf:params:xml:ns:yang:ietf-inet-types", 1868 "revision": "2021-02-22", 1869 "conformance-type": "import" 1870 } 1871 ] 1872 } 1873 } 1875 1877 Appendix C. Changes between revisions 1879 v02 - v03 1881 * Change counter32 to counter64 to avoid resetting too frequently 1883 * Explain why relation between health-score and symptom's health- 1884 score-weight is not defined and how it could be defined 1886 v01 - v02 1888 * Explicitly represent the fact that the health-score could not be 1889 computed (value -1) 1891 v00 - v01 1893 * Added needed subservice to model example from architecture draft 1895 * Added guideline section for naming models 1897 * Added data instance examples and validation procedure 1899 * Added the "parameters" container in the interface YANG module to 1900 correct a bug. 1902 Acknowledgements 1904 The authors would like to thank Jan Lindblad for his help during the 1905 design of these YANG modules. The authors would like to thank 1906 Stephane Litkowski and Charles Eckel for their reviews. 1908 Authors' Addresses 1910 Benoit Claise 1911 Huawei 1912 Email: benoit.claise@huawei.com 1914 Jean Quilbeuf 1915 Huawei 1916 Email: jean.quilbeuf@huawei.com 1918 Paolo Lucente 1919 NTT 1920 Siriusdreef 70-72 1921 2132 Hoofddorp 1922 Netherlands 1923 Email: paolo@ntt.net 1925 Paolo Fasano 1926 TIM S.p.A 1927 via G. Reiss Romoli, 274 1928 10148 Torino 1929 Italy 1930 Email: paolo2.fasano@telecomitalia.it 1931 Thangam Arumugam 1932 Cisco Systems, Inc. 1933 Milpitas (California), 1934 United States 1935 Email: tarumuga@cisco.com