idnits 2.17.1 draft-claise-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 : ---------------------------------------------------------------------------- ** There are 77 instances of too long lines in the document, the longest one being 27 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 158 has weird spacing: '...-change yan...' == Line 612 has weird spacing: '...-change yan...' == Line 767 has weird spacing: '...-change yan...' == Line 914 has weird spacing: '...-change yan...' -- The document date (July 27, 2020) is 1363 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) No issues found here. Summary: 1 error (**), 0 flaws (~~), 5 warnings (==), 1 comment (--). 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 Cisco Systems, Inc. 5 Expires: January 28, 2021 P. Lucente 6 NTT 7 P. Fasano 8 TIM S.p.A 9 July 27, 2020 11 YANG Modules for Service Assurance 12 draft-claise-opsawg-service-assurance-yang-05 14 Abstract 16 This document proposes YANG modules for the Service Assurance for 17 Intent-based Networking Architecture. 19 Status of This Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at https://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on January 28, 2021. 36 Copyright Notice 38 Copyright (c) 2020 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (https://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with respect 46 to this document. Code Components extracted from this document must 47 include Simplified BSD License text as described in Section 4.e of 48 the Trust Legal Provisions and are provided without warranty as 49 described in the Simplified BSD License. 51 Table of Contents 53 1. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 2 54 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 55 3. YANG Models Overview . . . . . . . . . . . . . . . . . . . . 3 56 4. Base ietf-service-assurance YANG module . . . . . . . . . . . 4 57 4.1. Tree View . . . . . . . . . . . . . . . . . . . . . . . . 4 58 4.2. Concepts . . . . . . . . . . . . . . . . . . . . . . . . 5 59 4.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 6 60 5. Subservice Extension: ietf-service-assurance-device YANG 61 module . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 62 5.1. Tree View . . . . . . . . . . . . . . . . . . . . . . . . 13 63 5.2. Complete Tree View . . . . . . . . . . . . . . . . . . . 13 64 5.3. Concepts . . . . . . . . . . . . . . . . . . . . . . . . 14 65 5.4. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 15 66 6. Subservice Extension: ietf-service-assurance-interface YANG 67 module . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 68 6.1. Tree View . . . . . . . . . . . . . . . . . . . . . . . . 16 69 6.2. Complete Tree View . . . . . . . . . . . . . . . . . . . 17 70 6.3. Concepts . . . . . . . . . . . . . . . . . . . . . . . . 18 71 6.4. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 18 72 7. Vendor-specific Subservice Extension: example-service- 73 assurance-device-acme YANG module . . . . . . . . . . . . . . 19 74 7.1. Tree View . . . . . . . . . . . . . . . . . . . . . . . . 19 75 7.2. Complete Tree View . . . . . . . . . . . . . . . . . . . 20 76 7.3. Concepts . . . . . . . . . . . . . . . . . . . . . . . . 21 77 7.4. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 22 78 8. Security Considerations . . . . . . . . . . . . . . . . . . . 23 79 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 24 80 9.1. The IETF XML Registry . . . . . . . . . . . . . . . . . . 24 81 9.2. The YANG Module Names Registry . . . . . . . . . . . . . 25 82 10. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 25 83 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 25 84 11.1. Normative References . . . . . . . . . . . . . . . . . . 25 85 11.2. Informative References . . . . . . . . . . . . . . . . . 26 86 Appendix A. Changes between revisions . . . . . . . . . . . . . 26 87 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 27 88 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 27 90 1. Terminology 92 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 93 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 94 "OPTIONAL" in this document are to be interpreted as described in BCP 95 14 [RFC2119] [RFC8174] when, and only when, they appear in all 96 capitals, as shown here. 98 The terms used in this document are defined in draft-claise-opsawg- 99 service-assurance-architecture IETF draft. 101 2. Introduction 103 The "Service Assurance for Intent-based Networking Architecture" 104 draft-claise-opsawg-service-assurance-architecture, specifies the 105 framework and all of its components for service assurance. This 106 document complements the architecture by providing open interfaces 107 between components. More specifically, the goal is to provide YANG 108 modules for the purpose of service assurance in a format that is: 110 o machine readable 112 o vendor independent 114 o augmentable 116 3. YANG Models Overview 118 The main YANG module, ietf-service-assurance, defines objects for 119 assuring network services based on their decomposition into so-called 120 subservices. The subservices are hierarchically organised by 121 dependencies. The subservices, along with the dependencies, 122 constitute an assurance graph. This module should be supported by an 123 agent, able to interact with the devices in order to produce a health 124 status and symptoms for each subservice in the assurance graph. This 125 module is intended for the following use cases: 127 o Assurance graph configuration: 129 * Subservices: configure a set of subservices to assure, by 130 specifying their types and parameters. 132 * Dependencies: configure the dependencies between the 133 subservices, along with their type. 135 o Assurance telemetry: export the health status of the subservices, 136 along with the observed symptoms. 138 The second YANG module, ietf-service-assurance-device, extends the 139 ietf-service-assurance module to add support for the subservice 140 DeviceHealthy. Additional subservice types might be added the same 141 way. 143 The third YANG module, example-service-assurance-device-acme, extends 144 the ietf-service-assurance-device module as an example to add support 145 for the subservice DeviceHealthy, with specifics for the fictional 146 ACME Corporation. Additional vendor-specific parameters might be 147 added the same way. 149 4. Base ietf-service-assurance YANG module 151 4.1. Tree View 153 The following tree diagram [RFC8340] provides an overview of the 154 ietf-service-assurance data model. 156 module: ietf-service-assurance 157 +--ro assurance-graph-version yang:counter32 158 +--ro assurance-graph-last-change yang:date-and-time 159 +--rw subservices 160 +--rw subservice* [type id] 161 +--rw type identityref 162 +--rw id string 163 +--ro last-change? yang:date-and-time 164 +--ro label? string 165 +--rw under-maintenance? boolean 166 +--rw maintenance-contact string 167 +--rw (parameter)? 168 | +--:(service-instance-parameter) 169 | +--rw service-instance-parameter 170 | +--rw service? string 171 | +--rw instance-name? string 172 +--ro health-score? uint8 173 +--ro symptoms-history-start? yang:date-and-time 174 +--rw symptoms 175 | +--ro symptom* [start-date-time id] 176 | +--ro id string 177 | +--ro health-score-weight? uint8 178 | +--ro description? string 179 | +--ro start-date-time yang:date-and-time 180 | +--ro stop-date-time? yang:date-and-time 181 +--rw dependencies 182 +--rw dependency* [type id] 183 +--rw type -> /subservices/subservice/type 184 +--rw id -> /subservices/subservice[type=current()/../type]/id 185 +--rw dependency-type? identityref 187 4.2. Concepts 189 The ietf-service-assurance YANG model assumes an identified number of 190 subservices, to be assured independently. A subservice is a feature 191 or a subpart of the network system that a given service instance 192 might depend on. Example of subservices include: 194 o DeviceHealthy: whether a device is healthy, and if not, what are 195 the symptoms. Potential symptoms are "CPU overloaded", "Out of 196 RAM", or "Out of TCAM". 198 o ConnectivityHealthy: given two IP addresses owned by two devices, 199 what is the quality of the connection between them. Potential 200 symptoms are "No route available" or "ECMP Imbalance". 202 The first example is a subservice representing a subpart of the 203 network system, while the second is a subservice representing a 204 feature of the network, In both cases, these subservices might depend 205 on other subservices, for instance, the connectivity might depend on 206 a subservice representing the routing mechanism and on a subservice 207 representing ECMP. 209 The symptoms are listed for each subservice. Each symptom is 210 specified by a unique id and contains a health-score-weight (the 211 impact to the health score incurred by this symptom), a label (text 212 describing what the symptom is), and dates and times at which the 213 symptom was detected and stopped being detected. While the unique id 214 is sufficient as an unique key list, the start-date-time second key 215 help sorting and retrieving relevant symptoms. 217 The assurance of a given service instance can be obtained by 218 composing the assurance of the subservices that it depends on, via 219 the dependency relations. 221 In order to declare a subservice MUST provide: 223 o A type: identity inheriting of the base identity for subservice, 225 o An id: string uniquely identifying the subservice among those with 226 the same identity, 228 o Some parameters, which should be specified in an augmenting model, 229 as described in the next sections. 231 The type and id uniquely identify a given subservice. They are used 232 to indicate the dependencies. Dependencies have types as well. Two 233 types are specified in the model: 235 o Impacting: such a dependency indicates an impact on the health of 236 the dependent, 238 o Informational: such a dependency might explain why the dependent 239 has issues but does not impact its health. 241 To illustrate the difference between "impacting" and "informational", 242 consider the subservice InterfaceHealthy, representing a network 243 interface. If the device to which the network interface belongs goes 244 down, the network interface will transition to a down state as well. 245 Therefore, the dependency of InterfaceHealthy towards DeviceHealthy 246 is "impacting". On the other hand, as a the dependency towards the 247 ECMPLoad subservice, which checks that the load between ECMP remains 248 ce remains stable throughout time, is only "informational". Indeed, 249 services might be perfectly healthy even if the load distribution 250 between ECMP changed. However, such an instability might be a 251 relevant symptom for diagnosing the root cause of a problem. 253 Service instances MUST be modeled as a particular type of subservice 254 with two parameters, a type and an instance name. The type is the 255 name of the service defined in the network orchestrator, for instance 256 "point-to-point-l2vpn". The instance name is the name assigned to 257 the particular instance that we are assuring, for instance the name 258 of the customer using that instance. 260 The "under-maintenance" and "maintenance-contact" flags inhibit the 261 emission of symptoms for that subservice and subservices that depend 262 on them. See Section 3.7 of 263 [draft-claise-opsawg-service-assurance-architecture] for a more 264 detailed discussion. 266 By specifying service instances and their dependencies in terms of 267 subservices, one defines the whole assurance to apply for them. An 268 assurance agent supporting this model should then produce telemetry 269 in return with, for each subservice: a health-status indicating how 270 healthy the subservice is and when the subservice is not healthy, a 271 list of symptoms explaining why the subservice is not healthy. 273 4.3. YANG Module 275 file "ietf-service-assurance@2020-01-13.yang" 277 module ietf-service-assurance { 278 yang-version 1.1; 279 namespace "urn:ietf:params:xml:ns:yang:ietf-service-assurance"; 280 prefix service-assurance; 282 import ietf-yang-types { 283 prefix yang; 284 } 286 organization 287 "IETF NETCONF (Network Configuration) Working Group"; 288 contact 289 "WG Web: 290 WG List: 291 Author: Benoit Claise 292 Author: Jean Quilbeuf "; 293 description 294 "This module defines objects for assuring network services based on 295 their decomposition into so-called subservices, according to the SAIN 296 (Service Assurance for Intent-based Networking) architecture. 298 The subservices hierarchically organised by dependencies constitute an 299 assurance graph. This module should be supported by an assurance agent, 300 able to interact with the devices in order to produce a health status 301 and symptoms for each subservice in the assurance graph. 303 This module is intended for the following use cases: 304 * Assurance graph configuration: 305 * subservices: configure a set of subservices to assure, by specifying 306 their types and parameters. 307 * dependencies: configure the dependencies between the subservices, 308 along with their type. 309 * Assurance telemetry: export the health status of the subservices, along 310 with the observed symptoms. 312 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 313 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 314 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 315 are to be interpreted as described in BCP 14 (RFC 2119) 316 (RFC 8174) when, and only when, they appear in all 317 capitals, as shown here. 319 Copyright (c)2020 IETF Trust and the persons identified as 320 authors of the code. All rights reserved. 322 Redistribution and use in source and binary forms, with or 323 without modification, is permitted pursuant to, and subject 324 to the license terms contained in, the Simplified BSD License 325 set forth in Section 4.c of the IETF Trust's Legal Provisions 326 Relating to IETF Documents 327 (https://trustee.ietf.org/license-info). 329 This version of this YANG module is part of RFC XXXX; see the 330 RFC itself for full legal notices. 332 TO DO: 333 - Better type (IETF or OC) for device-id, interface-id, etc. 334 - Have a YANG module for IETF and one for OC?"; 336 revision 2020-01-13 { 337 description 338 "Added the maintenance window concept."; 339 reference 340 "RFC xxxx: Title to be completed"; 341 } 343 revision 2019-11-16 { 344 description 345 "Initial revision."; 346 reference 347 "RFC xxxx: Title to be completed"; 348 } 350 identity subservice-idty { 351 description 352 "Root identity for all subservice types."; 353 } 355 identity service-instance-idty { 356 base subservice-idty; 357 description 358 "Identity representing a service instance."; 359 } 361 identity dependency-type { 362 description 363 "Base identity for representing dependency types."; 364 } 366 identity informational-dependency { 367 base dependency-type; 368 description 369 "Indicates that symptoms of the dependency might be of interest for the 370 dependent, but the status of the dependency should not have any 371 impact on the dependent."; 372 } 374 identity impacting-dependency { 375 base dependency-type; 376 description 377 "Indicates that the status of the dependency directly impacts the status 378 of the dependent."; 379 } 380 grouping symptom { 381 description 382 "Contains the list of symptoms for a specific subservice."; 383 leaf id { 384 type string; 385 description 386 "A unique identifier for the symptom."; 387 } 388 leaf health-score-weight { 389 type uint8 { 390 range "0 .. 100"; 391 } 392 description 393 "The weight to the health score incurred by this symptom. The higher the 394 value, the more of an impact this symptom has. If a subservice health 395 score is not 100, there must be at least one symptom with a health 396 score weight larger than 0."; 397 } 398 leaf description { 399 type string; 400 description 401 "Description of the symptom, i.e. text describing what the symptom is, to 402 be computer-consumable and be displayed on a human interface. "; 403 } 404 leaf start-date-time { 405 type yang:date-and-time; 406 description 407 "Date and time at which the symptom was detected."; 408 } 409 leaf stop-date-time { 410 type yang:date-and-time; 411 description 412 "Date and time at which the symptom stopped being detected."; 413 } 414 } 416 grouping subservice-dependency { 417 description 418 "Represent a dependency to another subservice."; 419 leaf type { 420 type leafref { 421 path "/subservices/subservice/type"; 422 } 423 description 424 "The type of the subservice to refer to (e.g. DeviceHealthy)."; 425 } 426 leaf id { 427 type leafref { 428 path "/subservices/subservice[type=current()/../type]/id"; 429 } 430 description 431 "The identifier of the subservice to refer to."; 432 } 433 leaf dependency-type { 434 type identityref { 435 base dependency-type; 436 } 437 description 438 "Represents the type of dependency (i.e. informational, impacting)."; 439 } 440 // augment here if more info are needed (i.e. a percentage) depending on the dependency type. 441 } 443 leaf assurance-graph-version { 444 type yang:counter32; 445 mandatory true; 446 config false; 447 description 448 "The assurance graph version, which increases by 1 for each new version, after the changes 449 (dependencies and/or maintenance windows parameters) are applied to the subservice(s)."; 450 } 451 leaf assurance-graph-last-change { 452 type yang:date-and-time; 453 mandatory true; 454 config false; 455 description 456 "Date and time at which the assurance graph last changed after the changes (dependencies 457 and/or maintenance windows parameters) are applied to the subservice(s). These date and time 458 must be more recent or equal compared to the more recent value of any changed subservices 459 last-change"; 460 } 461 container subservices { 462 description 463 "Root container for the subservices."; 464 list subservice { 465 key "type id"; 466 description 467 "List of subservice configured."; 468 leaf type { 469 type identityref { 470 base subservice-idty; 471 } 472 description 473 "Name of the subservice, e.g. DeviceHealthy."; 474 } 475 leaf id { 476 type string; 477 description 478 "Unique identifier of the subservice instance, for each type."; 479 } 480 leaf last-change { 481 type yang:date-and-time; 482 config false; 483 description 484 "Date and time at which the assurance graph for this subservice 485 instance last changed, i.e. dependencies and/or maintenance windows parameters."; 486 } 487 leaf label { 488 type string; 489 config false; 490 description 491 "Label of the subservice, i.e. text describing what the subservice is to 492 be displayed on a human interface."; 493 } 494 leaf under-maintenance { 495 type boolean; 496 default false; 497 description 498 "An optional flag indicating whether this particular subservice is under 499 maintenance. Under this circumstance, the subservice symptoms and the 500 symptoms of its dependencies in the assurance graph should not be taken 501 into account. Instead, the subservice should send a 'Under Maintenance' 502 single symptom. 504 The operator changing the under-maintenance value must set the 505 maintenance-contact variable. 507 When the subservice is not under maintenance any longer, the 508 under-maintenance flag must return to its default value and 509 the under-maintenance-owner variable deleted."; 510 } 511 leaf maintenance-contact { 512 when "../under-maintenance = 'true'"; 513 type string; 514 mandatory true; 515 description 516 "A string used to model an administratively assigned name of the 517 resource that changed the under-maintenance value to 'true. 519 It is suggested that this name contain one or more of the following: 520 IP address, management station name, network manager's name, location, 521 or phone number. In some cases the agent itself will be the owner of 522 an entry. In these cases, this string shall be set to a string 523 starting with 'monitor'."; 525 } 526 choice parameter { 527 description 528 "Specify the required parameters per subservice type."; 529 container service-instance-parameter { 530 when "derived-from-or-self(../type, 'service-assurance:service-instance-idty')"; 531 description 532 "Specify the parameters of a service instance."; 533 leaf service { 534 type string; 535 description "Name of the service."; 536 } 537 leaf instance-name{ 538 type string; 539 description "Name of the instance for that service."; 540 } 541 } 542 // Other modules can augment their own cases into here 543 } 544 leaf health-score { 545 type uint8 { 546 range "0 .. 100"; 547 } 548 config false; 549 description 550 "Score value of the subservice health. A value of 100 means that 551 subservice is healthy. A value of 0 means that the subservice is 552 broken. A value between 0 and 100 means that the subservice is 553 degraded."; 554 } 555 leaf symptoms-history-start { 556 type yang:date-and-time; 557 config false; 558 description 559 "Date and time at which the symptoms history starts for this 560 subservice instance, either because the subservice instance 561 started at that date and time or because the symptoms before that 562 were removed due to a garbage collection process."; 563 } 564 container symptoms { 565 description 566 "Symptoms for the subservice."; 567 list symptom { 568 key "start-date-time id"; 569 config false; 570 description 571 "List of symptoms the subservice. While the start-date-time key is not 572 necessary per se, this would get the entries sorted by start-date-time 573 for easy consumption."; 574 uses symptom; 575 } 576 } 577 container dependencies { 578 description 579 "configure the dependencies between the subservices, along with their types."; 580 list dependency { 581 key "type id"; 582 description 583 "List of soft dependencies of the subservice."; 584 uses subservice-dependency; 585 } 586 } 587 } 588 } 589 } 591 593 5. Subservice Extension: ietf-service-assurance-device YANG module 595 5.1. Tree View 597 The following tree diagram [RFC8340] provides an overview of the 598 ietf-service-assurance-device data model. 600 module: ietf-service-assurance-device 601 augment /service-assurance:subservices/service-assurance:subservice/service-assurance:parameter: 602 +--rw device-idty 603 +--rw device? string 605 5.2. Complete Tree View 607 The following tree diagram [RFC8340] provides an overview of the 608 ietf-service-assurance and ietf-service-assurance-device data models. 610 module: ietf-service-assurance 611 +--ro assurance-graph-version yang:counter32 612 +--ro assurance-graph-last-change yang:date-and-time 613 +--rw subservices 614 +--rw subservice* [type id] 615 +--rw type identityref 616 +--rw id string 617 +--ro last-change? yang:date-and-time 618 +--ro label? string 619 +--rw under-maintenance? boolean 620 +--rw maintenance-contact string 621 +--rw (parameter)? 622 | +--:(service-instance-parameter) 623 | | +--rw service-instance-parameter 624 | | +--rw service? string 625 | | +--rw instance-name? string 626 | +--:(service-assurance-device:device-idty) 627 | +--rw service-assurance-device:device-idty 628 | +--rw service-assurance-device:device? string 629 +--ro health-score? uint8 630 +--ro symptoms-history-start? yang:date-and-time 631 +--rw symptoms 632 | +--ro symptom* [start-date-time id] 633 | +--ro id string 634 | +--ro health-score-weight? uint8 635 | +--ro description? string 636 | +--ro start-date-time yang:date-and-time 637 | +--ro stop-date-time? yang:date-and-time 638 +--rw dependencies 639 +--rw dependency* [type id] 640 +--rw type -> /subservices/subservice/type 641 +--rw id -> /subservices/subservice[type=current()/../type]/id 642 +--rw dependency-type? identityref 644 5.3. Concepts 646 As the number of subservices will grow over time, the YANG module is 647 designed to be extensible. A new subservice type requires the 648 precise specifications of its type and expected parameters. Let us 649 illustrate the example of the new DeviceHealthy subservice type. As 650 the name implies, it monitors and reports the device health, along 651 with some symptoms in case of degradation. 653 For our DeviceHealthy subservice definition, the new device-idty is 654 specified, as an inheritance from the base identity for subservices. 655 This indicates to the assurance agent that we are now assuring the 656 health of a device. 658 The typical parameter for the configuration of the DeviceHealthy 659 subservice is the name of the device that we want to assure. By 660 augmenting the parameter choice from ietf-service-assurance YANG 661 module for the case of the device-idty subservice type, this new 662 parameter is specified. 664 5.4. YANG Module 666 file "ietf-service-assurance-device@2020-01-13.yang" 668 module ietf-service-assurance-device { 669 yang-version 1.1; 670 namespace "urn:ietf:params:xml:ns:yang:ietf-service-assurance-device"; 671 prefix service-assurance-device; 673 import ietf-service-assurance { 674 prefix "service-assurance"; 675 } 677 organization 678 "IETF NETCONF (Network Configuration) Working Group"; 679 contact 680 "WG Web: 681 WG List: 682 Author: Benoit Claise 683 Author: Jean Quilbeuf "; 684 description 685 "This module extends the ietf-service-assurance module to add 686 support for the subservice DeviceHealthy. 688 Checks whether a network device is healthy. 690 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 691 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 692 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 693 are to be interpreted as described in BCP 14 (RFC 2119) 694 (RFC 8174) when, and only when, they appear in all 695 capitals, as shown here. 697 Copyright (c) 2020 IETF Trust and the persons identified as 698 authors of the code. All rights reserved. 700 Redistribution and use in source and binary forms, with or 701 without modification, is permitted pursuant to, and subject 702 to the license terms contained in, the Simplified BSD License 703 set forth in Section 4.c of the IETF Trust's Legal Provisions 704 Relating to IETF Documents 705 (https://trustee.ietf.org/license-info). 707 This version of this YANG module is part of RFC XXXX; see the 708 RFC itself for full legal notices. "; 710 revision 2020-01-13 { 711 description 712 "Added the maintenance window concept."; 713 reference 714 "RFC xxxx: Title to be completed"; 715 } 717 revision 2019-11-16 { 718 description 719 "Initial revision."; 720 reference 721 "RFC xxxx: Title to be completed"; 722 } 724 identity device-idty { 725 base service-assurance:subservice-idty; 726 description "Network Device is healthy."; 727 } 729 augment /service-assurance:subservices/service-assurance:subservice/service-assurance:parameter { 730 description 731 "Specify the required parameters for a new subservice type"; 732 container device-idty{ 733 when "derived-from-or-self(../service-assurance:type, 'device-idty')"; 734 description 735 "Specify the required parameters for the device-idty subservice type"; 737 leaf device { 738 type string; 739 description "The device to monitor."; 740 } 741 } 742 } 743 } 745 747 6. Subservice Extension: ietf-service-assurance-interface YANG module 749 6.1. Tree View 751 The following tree diagram [RFC8340] provides an overview of the 752 ietf-service-assurance-interface data model. 754 module: ietf-service-assurance-interface 755 augment /service-assurance:subservices/service-assurance:subservice/service-assurance:parameter: 756 +--rw device? string 757 +--rw interface? string 759 6.2. Complete Tree View 761 The following tree diagram [RFC8340] provides an overview of the 762 ietf-service-assurance, ietf-service-assurance-device, and ietf- 763 service-assurance-interface data models. 765 module: ietf-service-assurance 766 +--ro assurance-graph-version yang:counter32 767 +--ro assurance-graph-last-change yang:date-and-time 768 +--rw subservices 769 +--rw subservice* [type id] 770 +--rw type identityref 771 +--rw id string 772 +--ro last-change? yang:date-and-time 773 +--ro label? string 774 +--rw under-maintenance? boolean 775 +--rw maintenance-contact string 776 +--rw (parameter)? 777 | +--:(service-instance-parameter) 778 | | +--rw service-instance-parameter 779 | | +--rw service? string 780 | | +--rw instance-name? string 781 | +--:(service-assurance-device:device-idty) 782 | | +--rw service-assurance-device:device-idty 783 | | +--rw service-assurance-device:device? string 784 | +--:(service-assurance-interface:device) 785 | | +--rw service-assurance-interface:device? string 786 | +--:(service-assurance-interface:interface) 787 | +--rw service-assurance-interface:interface? string 788 +--ro health-score? uint8 789 +--ro symptoms-history-start? yang:date-and-time 790 +--rw symptoms 791 | +--ro symptom* [start-date-time id] 792 | +--ro id string 793 | +--ro health-score-weight? uint8 794 | +--ro description? string 795 | +--ro start-date-time yang:date-and-time 796 | +--ro stop-date-time? yang:date-and-time 797 +--rw dependencies 798 +--rw dependency* [type id] 799 +--rw type -> /subservices/subservice/type 800 +--rw id -> /subservices/subservice[type=current()/../type]/id 801 +--rw dependency-type? identityref 803 6.3. Concepts 805 For our InterafaceHealthy subservice definition, the new interface- 806 idty is specified, as an inheritance from the base identity for 807 subservices. This indicates to the assurance agent that we are now 808 assuring the health of an interface. 810 The typical parameters for the configuration of the InterfaceHealthy 811 subservice are the name of the device and, on that specific device, a 812 specific interface. By augmenting the parameter choice from ietf- 813 service-assurance YANG module for the case of the interface-idty 814 subservice type, those two new parameter are specified. 816 6.4. YANG Module 818 file "ietf-service-assurance-interface@2020-01-13.yang" 820 module ietf-service-assurance-interface { 821 yang-version 1.1; 822 namespace "urn:ietf:params:xml:ns:yang:ietf-service-assurance-interface"; 823 prefix service-assurance-interface; 825 import ietf-service-assurance { 826 prefix "service-assurance"; 827 } 829 organization 830 "IETF OPSAWG Working Group"; 831 contact 832 "WG Web: 833 WG List: 834 Author: Benoit Claise 835 Author: Jean Quilbeuf "; 836 description 837 "This module extends the ietf-service-assurance module to add 838 support for the subservice InterfaceHealthy. 840 Checks whether an interface is healthy. 842 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 843 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 844 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 845 are to be interpreted as described in BCP 14 (RFC 2119) 846 (RFC 8174) when, and only when, they appear in all 847 capitals, as shown here. 849 Copyright (c) 2020 IETF Trust and the persons identified as 850 authors of the code. All rights reserved. 852 Redistribution and use in source and binary forms, with or 853 without modification, is permitted pursuant to, and subject 854 to the license terms contained in, the Simplified BSD License 855 set forth in Section 4.c of the IETF Trust's Legal Provisions 856 Relating to IETF Documents 857 (https://trustee.ietf.org/license-info). 859 This version of this YANG module is part of RFC XXXX; see the 860 RFC itself for full legal notices. "; 862 revision 2020-01-13 { 863 description 864 "Initial revision."; 865 reference 866 "RFC xxxx: Title to be completed"; 867 } 869 identity interface-idty { 870 base service-assurance:subservice-idty; 871 description "Checks whether an interface is healthy."; 872 } 874 augment /service-assurance:subservices/service-assurance:subservice/service-assurance:parameter { 875 when "derived-from-or-self(service-assurance:type, 'interface-idty')"; 876 description 877 "Specify the required parameters for the interface-idty subservice type"; 879 leaf device { 880 type string; 881 description "Device supporting the interface."; 882 } 883 leaf interface { 884 type string; 885 description "Name of the interface."; 886 } 887 } 888 } 890 892 7. Vendor-specific Subservice Extension: example-service-assurance- 893 device-acme YANG module 895 7.1. Tree View 897 The following tree diagram [RFC8340] provides an overview of the 898 example-service-assurance-device-acme data model. 900 module: example-service-assurance-device-acme 901 augment /service-assurance:subservices/service-assurance:subservice/service-assurance:parameter: 902 +--rw acme-device-idty 903 +--rw device? string 904 +--rw acme-specific-parameter? string 906 7.2. Complete Tree View 908 The following tree diagram [RFC8340] provides an overview of the 909 ietf-service-assurance, ietf-service-assurance-device, and example- 910 service-assurance-device-acme data models. 912 module: ietf-service-assurance 913 +--ro assurance-graph-version yang:counter32 914 +--ro assurance-graph-last-change yang:date-and-time 915 +--rw subservices 916 +--rw subservice* [type id] 917 +--rw type identityref 918 +--rw id string 919 +--ro last-change? yang:date-and-time 920 +--ro label? string 921 +--rw under-maintenance? boolean 922 +--rw maintenance-contact string 923 +--rw (parameter)? 924 | +--:(service-instance-parameter) 925 | | +--rw service-instance-parameter 926 | | +--rw service? string 927 | | +--rw instance-name? string 928 | +--:(service-assurance-device:device-idty) 929 | | +--rw service-assurance-device:device-idty 930 | | +--rw service-assurance-device:device? string 931 | +--:(service-assurance-interface:device) 932 | | +--rw service-assurance-interface:device? string 933 | +--:(service-assurance-interface:interface) 934 | | +--rw service-assurance-interface:interface? string 935 | +--:(example-service-assurance-device-acme:acme-device-idty) 936 | +--rw example-service-assurance-device-acme:acme-device-idty 937 | +--rw example-service-assurance-device-acme:device? string 938 | +--rw example-service-assurance-device-acme:acme-specific-parameter? string 939 +--ro health-score? uint8 940 +--ro symptoms-history-start? yang:date-and-time 941 +--rw symptoms 942 | +--ro symptom* [start-date-time id] 943 | +--ro id string 944 | +--ro health-score-weight? uint8 945 | +--ro description? string 946 | +--ro start-date-time yang:date-and-time 947 | +--ro stop-date-time? yang:date-and-time 948 +--rw dependencies 949 +--rw dependency* [type id] 950 +--rw type -> /subservices/subservice/type 951 +--rw id -> /subservices/subservice[type=current()/../type]/id 952 +--rw dependency-type? identityref 954 7.3. Concepts 956 Under some circumstances, vendor-specific subservice types might be 957 required. As an example of this vendor-specific implementation, this 958 section shows how to augment the ietf-service-assurance-device module 959 to add support for the subservice DeviceHealthy, specific to the ACME 960 Corporation. The new parameter is acme-specific-parameter. 962 7.4. YANG Module 964 module example-service-assurance-device-acme { 965 yang-version 1.1; 966 namespace "urn:example:example-service-assurance-device-acme"; 967 prefix example-service-assurance-device-acme; 969 import ietf-service-assurance { 970 prefix "service-assurance"; 971 } 973 import ietf-service-assurance-device { 974 prefix "service-assurance-device"; 975 } 977 organization 978 "IETF NETCONF (Network Configuration) Working Group"; 979 contact 980 "WG Web: 981 WG List: 982 Author: Benoit Claise 983 Author: Jean Quilbeuf "; 984 description 985 "This module extends the ietf-service-assurance-device module to add 986 support for the subservice DeviceHealthy, specific to the ACME Corporation. 988 ACME Network Device is healthy. 990 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 991 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 992 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 993 are to be interpreted as described in BCP 14 (RFC 2119) 994 (RFC 8174) when, and only when, they appear in all 995 capitals, as shown here. 997 Copyright (c) 2019 IETF Trust and the persons identified as 998 authors of the code. All rights reserved. 1000 Redistribution and use in source and binary forms, with or 1001 without modification, is permitted pursuant to, and subject 1002 to the license terms contained in, the Simplified BSD License 1003 set forth in Section 4.c of the IETF Trust's Legal Provisions 1004 Relating to IETF Documents 1005 (https://trustee.ietf.org/license-info). 1007 This version of this YANG module is part of RFC XXXX; see the 1008 RFC itself for full legal notices. "; 1010 revision 2020-01-13 { 1011 description 1012 "Added the maintenance window concept."; 1013 reference 1014 "RFC xxxx: Title to be completed"; 1015 } 1017 revision 2019-11-16 { 1018 description 1019 "Initial revision."; 1020 reference 1021 "RFC xxxx: Title to be completed"; 1022 } 1024 identity device-acme-idty { 1025 base service-assurance-device:device-idty; 1026 description "Network Device is healthy."; 1027 } 1029 augment /service-assurance:subservices/service-assurance:subservice/service-assurance:parameter { 1030 description 1031 "Specify the required parameters for a new subservice type"; 1032 container acme-device-idty{ 1033 when "derived-from-or-self(../service-assurance:type, 'device-acme-idty')"; 1034 description 1035 "Specify the required parameters for the device-acme-idty subservice type"; 1037 leaf device { 1038 type string; 1039 description "The device to monitor."; 1040 } 1042 leaf acme-specific-parameter { 1043 type string; 1044 description "The ACME Corporation sepcific parameter."; 1045 } 1046 } 1047 } 1048 } 1050 8. Security Considerations 1052 The YANG module specified in this document defines a schema for data 1053 that is designed to be accessed via network management protocols such 1054 as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer 1055 is the secure transport layer, and the mandatory-to-implement secure 1056 transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer 1057 is HTTPS, and the mandatory-to-implement secure transport is TLS 1058 [RFC8446]. 1060 The Network Configuration Access Control Model (NACM) [RFC8341] 1061 provides the means to restrict access for particular NETCONF or 1062 RESTCONF users to a preconfigured subset of all available NETCONF or 1063 RESTCONF protocol operations and content. 1065 There are a number of data nodes defined in this YANG module that are 1066 writable/ creatable/deletable (i.e., config true, which is the 1067 default). These data nodes may be considered sensitive or vulnerable 1068 in some network environments. Write operations (e.g., edit-config) 1069 to these data nodes without proper protection can have a negative 1070 effect on network operations. These are the subtrees and data nodes 1071 and their sensitivity/vulnerability: 1073 o /subservices/subservice/type 1075 o /subservices/subservice/id 1077 o /subservices/subservice/under-maintenance 1079 o /subservices/subservice/maintenance-contact 1081 9. IANA Considerations 1083 9.1. The IETF XML Registry 1085 This document registers two URIs in the IETF XML registry [RFC3688]. 1086 Following the format in [RFC3688], the following registrations are 1087 requested: 1089 URI: urn:ietf:params:xml:ns:yang:ietf-service-assurance 1090 Registrant Contact: The NETCONF WG of the IETF. 1091 XML: N/A, the requested URI is an XML namespace. 1093 URI: urn:ietf:params:xml:ns:yang:ietf-service-assurance-device 1094 Registrant Contact: The NETCONF WG of the IETF. 1095 XML: N/A, the requested URI is an XML namespace. 1097 URI: urn:ietf:params:xml:ns:yang:ietf-service-assurance-interface 1098 Registrant Contact: The NETCONF WG of the IETF. 1099 XML: N/A, the requested URI is an XML namespace. 1101 9.2. The YANG Module Names Registry 1103 This document registers three YANG modules in the YANG Module Names 1104 registry [RFC7950]. Following the format in [RFC7950], the the 1105 following registrations are requested: 1107 name: ietf-service-assurance 1108 namespace: urn:ietf:params:xml:ns:yang:ietf-service-assurance 1109 prefix: inc 1110 reference: RFC XXXX 1112 name: ietf-service-assurance-device 1113 namespace: urn:ietf:params:xml:ns:yang:ietf-service-assurance-device 1114 prefix: inc 1115 reference: RFC XXXX 1117 name: ietf-service-assurance-interface 1118 namespace: urn:ietf:params:xml:ns:yang:ietf-service-assurance-interface 1119 prefix: inc 1120 reference: RFC XXXX 1122 10. Open Issues 1124 -None 1126 11. References 1128 11.1. Normative References 1130 [draft-claise-opsawg-service-assurance-architecture] 1131 Claise, B. and J. Quilbeuf, "draft-claise-opsawg-service- 1132 assurance-architecture", 2020. 1134 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1135 and A. Bierman, Ed., "Network Configuration Protocol 1136 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1137 . 1139 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 1140 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 1141 . 1143 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1144 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1145 . 1147 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1148 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1149 . 1151 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 1152 Access Control Model", STD 91, RFC 8341, 1153 DOI 10.17487/RFC8341, March 2018, 1154 . 1156 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 1157 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 1158 . 1160 11.2. Informative References 1162 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1163 Requirement Levels", BCP 14, RFC 2119, 1164 DOI 10.17487/RFC2119, March 1997, 1165 . 1167 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1168 DOI 10.17487/RFC3688, January 2004, 1169 . 1171 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1172 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1173 May 2017, . 1175 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 1176 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 1177 . 1179 Appendix A. Changes between revisions 1181 v04 - v05 1183 o Added the concept of symptoms-history-start 1185 o Changed label to description, under symptoms. This was confusing 1186 as there was two labels in the models 1188 v03 - v04 1190 o Add the interface subservice, with two parameters 1192 v02 - v03 1194 o Added the maintenace window concepts 1195 v01 - v02 1197 o Improved leaf naming 1199 o Clarified some concepts: symptoms, dependency 1201 v00 - v01 1203 o Terminology clarifications 1205 o Provide example of impacting versus impacted dependencies 1207 Acknowledgements 1209 The authors would like to thank Jan Lindblad for his help during the 1210 design of these YANG modules. The authors would like to thank 1211 Stephane Litkowski and Charles Eckel for their reviews. 1213 Authors' Addresses 1215 Benoit Claise 1216 Cisco Systems, Inc. 1217 De Kleetlaan 6a b1 1218 1831 Diegem 1219 Belgium 1221 Email: bclaise@cisco.com 1223 Jean Quilbeuf 1224 Cisco Systems, Inc. 1225 1, rue Camille Desmoulins 1226 92782 Issy Les Moulineaux 1227 France 1229 Email: jquilbeu@cisco.com 1231 Paolo Lucente 1232 NTT 1233 Siriusdreef 70-72 1234 Hoofddorp, WT 2132 1235 Netherlands 1237 Email: paolo@ntt.net 1238 Paolo Fasano 1239 TIM S.p.A 1240 via G. Reiss Romoli, 274 1241 10148 Torino 1242 Italy 1244 Email: paolo2.fasano@telecomitalia.it