idnits 2.17.1 draft-clacla-netmod-yang-model-update-02.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 3 instances of too long lines in the document, the longest one being 18 characters in excess of 72. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 87: '...name. Thus, a module name MUST NOT be...' RFC 2119 keyword, line 88: '... the "namespace" statement MUST NOT be...' RFC 2119 keyword, line 94: '... this MUST be achieved by a new ...' Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (November 11, 2017) is 2357 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-03) exists of draft-clacla-netmod-model-catalog-02 == Outdated reference: A later version (-02) exists of draft-claise-semver-01 == Outdated reference: A later version (-11) exists of draft-wu-l3sm-rfc8049bis-09 -- Obsolete informational reference (is this intentional?): RFC 8049 (Obsoleted by RFC 8299) Summary: 2 errors (**), 0 flaws (~~), 4 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group B. Claise 3 Internet-Draft J. Clarke 4 Updates: 7950 (if approved) Cisco Systems, Inc. 5 Intended status: Standards Track K. D'Souza 6 Expires: May 15, 2018 AT&T 7 November 11, 2017 9 New YANG Module Update Procedure 10 draft-clacla-netmod-yang-model-update-02 12 Abstract 14 This document specifies a new YANG module update procedure in case of 15 backward-incompatible changes, as an alternative proposal to the YANG 16 1.1 specifications. This document updates RFC 7950. 18 Status of This Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at http://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on May 15, 2018. 35 Copyright Notice 37 Copyright (c) 2017 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (http://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 53 2. The Problems . . . . . . . . . . . . . . . . . . . . . . . . 3 54 2.1. Slow Standardization . . . . . . . . . . . . . . . . . . 3 55 2.2. Some YANG Modules are Not Backward Compatible . . . . . . 3 56 2.3. A Zoo of YANG Modules . . . . . . . . . . . . . . . . . . 3 57 2.4. YANG Modules Obsolete Relationship . . . . . . . . . . . 4 58 2.5. YANG Module Transition Strategy . . . . . . . . . . . . . 5 59 3. The Solution . . . . . . . . . . . . . . . . . . . . . . . . 6 60 3.1. SEMVER Semantic Versioning . . . . . . . . . . . . . . . 6 61 3.2. Updating the YANG 1.1 Specifications . . . . . . . . . . 9 62 3.3. The Derived Semantic Version . . . . . . . . . . . . . . 9 63 4. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 10 64 5. Semantic Version Extension Module . . . . . . . . . . . . . . 11 65 6. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 12 66 7. Security Considerations . . . . . . . . . . . . . . . . . . . 12 67 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 68 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 13 69 9.1. Normative References . . . . . . . . . . . . . . . . . . 13 70 9.2. Informative References . . . . . . . . . . . . . . . . . 13 71 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 13 73 1. Introduction 75 The YANG data modeling language [RFC7950] specifies strict rules for 76 updating YANG modules (see section 11 "Updating a Module"). Citing a 77 few of the relevant rules for this document: 79 1. "As experience is gained with a module, it may be desirable to 80 revise that module. However, changes to published modules are 81 not allowed if they have any potential to cause interoperability 82 problems between a client using an original specification and a 83 server using an updated specification." 85 2. "Note that definitions contained in a module are available to be 86 imported by any other module and are referenced in "import" 87 statements via the module name. Thus, a module name MUST NOT be 88 changed. Furthermore, the "namespace" statement MUST NOT be 89 changed, since all XML elements are qualified by the namespace." 91 3. "Otherwise, if the semantics of any previous definition are 92 changed (i.e., if a non-editorial change is made to any 93 definition other than those specifically allowed above), then 94 this MUST be achieved by a new definition with a new identifier." 96 What are the consequences? 97 1. Ideally, the YANG module names should not be changed due the 98 importance of not changing the automation code in case of import 99 statements or service composition at the orchestration layer. 101 2. When the same YANG module name is kept, the new YANG module 102 revision must always be updated in a backward-compatible way. 104 2. The Problems 106 This section lists a series of problems, hopefully listed in a 107 logical order, which leads to the solution in the next section. 109 2.1. Slow Standardization 111 The conclusions drawn in the introduction lead to the logical 112 conclusion that the standardized YANG modules have to be perfect on 113 day one (at least the structure), which in turn might explain why all 114 the IETF YANG modules take so long to standardize. Shooting for 115 perfection (at least in structure) is obviously a noble goal, but if 116 the perfect standard comes too late, it doesn't help the industry. 118 2.2. Some YANG Modules are Not Backward Compatible 120 As we learn from our mistakes, we're going to face more and more 121 backward-incompatible YANG modules. An example is the YANG data 122 model for L3VPN service delivery [RFC8049], which, based on 123 implementation experience, must be updated in a backward-incompatible 124 way with draft-wu-l3sm-rfc8049bis [I-D.wu-l3sm-rfc8049bis]. 126 While Standards Development Organization (SDO) YANG modules are 127 obviously better for the industry, we must recognize that many YANG 128 modules are actually generated YANG modules (for example, from 129 internal databases), also known as native YANG modules, or vendor 130 modules [RFC8199]. From time to time, the new YANG modules are not 131 backward-compatible. 133 In such cases, it would be better to indicate how backward-compatible 134 a given YANG module actually is. 136 2.3. A Zoo of YANG Modules 138 Even if we focus on the IETF, we have to observe that many SDOs, 139 opensource fora, and vendors develop YANG modules develop YANG 140 modules. This should be considered a success for an IETF developed 141 technoogy. However, the operators are faced with this problem: how 142 to select the YANG modules to take into account for their service 143 developments. 145 The site (and the YANG catalog that it 146 provides: YANG module for yangcatalog.org, 147 [I-D.clacla-netmod-model-catalog]) is an attempt to become a 148 reference for all YANG modules available in the industry, for both 149 YANG developers to search on what exists already) and for operators 150 (to discover the more mature YANG models to automate services). This 151 YANG catalog should not only contain pointers to the YANG modules 152 themselves, but also contain metadata related to those YANG modules: 153 What is the module type (service model or not?); what is the maturity 154 level? (e.g., for the IETF: is this an RFC, a working group document 155 or an individual draft?); is this module implemented?; who is the 156 contact?; is there open-source code available? And we expect many 157 more in the future. The industry has begun to understand that the 158 metadata related to YANG models become equally important as the YANG 159 models themselves. 161 The yangcatalog.org instantiation of the catalog provides a means for 162 module authors and vendors implementing modules to upload their 163 metadata, which is then searchable via an API, as well as using a 164 variety of web-based tools. The instructions for contributing and 165 searching for metadata can be found at . 168 The issue is actually the number of YANG modules the operators are 169 offered. At the time of writing this document, the number of unique 170 YANG modules in the catalog is exactly 2596 (and that number keeps 171 growing), while the IETF has standardized or is busy standardizing a 172 small subset of those. Therefore, it's important to distinguish the 173 relevant YANG modules with the pack and to understand the 174 relationship between the YANG modules. 176 2.4. YANG Modules Obsolete Relationship 178 So the operators use the yangcatalog.org to discover which YANG 179 modules they can use NOW. They base their selection not only on the 180 YANG module content, but also on the related metadata. When faced 181 with the zoo of the YANG modules, it's difficult to understand the 182 relationship between YANG modules. As an example: how could an 183 operator discovers that a YANG-MODULE-B obsoletes YANG-MODULE-A? 184 Indeed, both have different YANG module names. The only available 185 information is an "obsolete" tag in the published RFC containing 186 YANG-MODULE-B: this tag would point to YANG-MODULE-A. In the world 187 of automation, going through a published RFC as a level of 188 indirection to understand the YANG module obsolete relationship is a 189 non starter. Food for thought: the IETF should stop thinking that 190 the metric for success is an RFC number, as opposed to the contained 191 YANG module(s). 193 We need an automatic way to discover that a YANG-MODULE-B obsoletes 194 YANG-MODULE-A, so that YANG-MODULE-A should not be given any 195 attention. 197 The following example is not an automatic way. 199 description 200 "This YANG module defines a generic service configuration 201 model for Layer 3 VPNs. This model is common across all 202 vendor implementations. This obsoletes the RFC8049 YANG 203 module, ietf-l3vpn-svc@2017-01-2"; 204 revision 2017-09-14 { 205 description 206 "First revision of RFC8049."; 207 reference 208 "RFC xxxx: YANG Data Model for L3VPN Service Delivery"; 210 Along the same lines, going through an out-of-band tool such as the 211 yangcatalog.org in order to discover the obsolete relationship is a 212 possible automatic way, but not ideal. 214 2.5. YANG Module Transition Strategy 216 Let's assume for a moment that we change the YANG module, with the 217 specific example of the ietf-routing, which some propose to update to 218 ietf-routing-2. 220 Here are all the ietf-routing dependent YANG modules (those modules 221 that depend on ietf-routing) . So many 224 YANG modules. 226 Let's look at the difference for ietf-routing-2: 227 . 231 Changing the module name from ietf-routing to ietf-routing-2 implies 232 that the we have to warn all draft authors of ietf-routing YANG 233 dependent modules. Firstly, to make sure they are aware of ietf- 234 routing-2 (publishing a RFC8022bis mentioning in the module 235 description that this module is not compatible with the NMDA 236 architecture, and providing a pointer to ietf-routing-2 ... is not an 237 automatic way... so barely useful). And secondly, to ask them to 238 change their import (or service composition) to ietf-routing-2. 239 Hopefully, in the ietf-routing case, all dependent YANG modules are 240 part of the IETF, so the communication is a manageable. 242 Changing the ietf-interfaces YANG module name would be a different 243 challenge, as it's used throughout the industry: 244 248 3. The Solution 250 The solution is composed of two mandator aspects, a semantic 251 versioning YANG extension and an update to RFC7950. An optional 252 additional check, validating the semantic versioning from a syntact 253 point of view, can either assist in determining the correct semantic 254 versioning values, or can help in determining the values for YANG 255 modules that don't support this extension. 257 3.1. SEMVER Semantic Versioning 259 The semantic versioning solution proposed here as already been 260 proposed in [I-D.openconfig-netmod-model-catalog] (cut/paste here 261 with the authors permission)which itself is based on 262 [openconfigsemver]. The goal is to indicate the YANG module 263 backwards (in)compatibility, following semver.org semantic versioning 264 [semver]: 266 MAJOR is incremented when the new version of the specification is 267 incompatible with previous versions. 269 MINOR is incremented when new functionality is added in a manner 270 that is backward-compatible with previous versions. 272 PATCH is incremented when bug fixes are made in a backward- 273 compatible manner. 275 // extension statements 276 extension openconfig-version { 277 argument "semver" { 278 yin-element false; 279 } 280 description 281 "The OpenConfig version number for the module. This is 282 expressed as a semantic version number of the form: 283 x.y.z 284 where: 285 * x corresponds to the major version, 286 * y corresponds to a minor version, 287 * z corresponds to a patch version. 288 This version corresponds to the model file within which it is 289 defined, and does not cover the whole set of OpenConfig models. 290 Where several modules are used to build up a single block of 291 functionality, the same module version is specified across each 292 file that makes up the module. 294 A major version number of 0 indicates that this model is still 295 in development (whether within OpenConfig or with industry 296 partners), and is potentially subject to change. 298 Following a release of major version 1, all modules will 299 increment major revision number where backwards incompatible 300 changes to the model are made. 302 The minor version is changed when features are added to the 303 model that do not impact current clients use of the model. 305 The patch-level version is incremented when non-feature changes 306 (such as bugfixes or clarifications to human-readable 307 descriptions that do not impact model functionality) are made 308 that maintain backwards compatibility. 310 The version number is stored in the module meta-data."; 311 } 313 Along these lines, we propose the following YANG 1.1 extension for a 314 more generic semantic version. The formal definition is found at the 315 end of this document. 317 extension module-version { 318 argument "semver" { 319 yin-element false; 320 } 321 } 323 The extension would typically be used this way: 325 module yang-module-name { 327 yang-version "1"; 328 namespace "name-space"; 329 prefix "prefix-name"; 331 import ietf-semver-extension { prefix "semver-ext"; } 333 organization 334 "to be completed"; 336 contact 337 "to be completed"; 339 description 340 "to be completed"; 342 semver-ext:module-version "1.1.2"; 344 revision 2017-10-30 { 345 description 346 "Change the module structure"; 347 reference "1.1.2"; 348 } 350 revision 2017-07-30 { 351 description 352 "Fixed unprintable character"; 353 reference "0.1.2"; 354 } 356 revision 2017-04-03 { 357 description 358 "Update copyright notice."; 359 reference "0.1.1"; 360 } 362 revision 2017-01-26 { 363 description 364 "Initial module for inet types"; 365 reference "0.1.0"; 366 } 368 //YANG module definition starts here 370 See also "Semantic Versioning and Structure for IETF Specifications" 371 [I-D.claise-semver] for a mechanism to combine the semantic 372 versioning, the github tools, and a potential change to the IETF 373 process. 375 3.2. Updating the YANG 1.1 Specifications 377 RFC 7950 section 11, must be updated to express: 379 "As experience is gained with a module, it may be desirable to revise 380 that module. Changes to published modules are allowed, even if they 381 have some potential to cause interoperability problems, at the 382 condition that the semantic versioning change are clearly indicated 383 based on the SEMVER YANG extension." 385 3.3. The Derived Semantic Version 387 The YANG catalog contains not only the most up-to-date YANG module 388 revision of a given module, but keeps all previous revisions as well. 389 With APIs in mind, it's important to understand whether different 390 YANG module revisions are backward compatible (this is specifically 391 imported for native YANG modules, i.e. the ones where generated-from 392 = native), even for the YANG modules that don't support the YANG 393 extension specified in this document. 395 Two distinct leaves in the YANG module 396 [I-D.clacla-netmod-model-catalog] contain this semver notation: 398 the semantic-version leaf contains the value embedded within a 399 YANG module (if it is available). 401 the derived-semantic-version leaf is established by examining the 402 the YANG module themselves. As such derived-semantic-version only 403 takes syntax into account as opposed to the meaning of various 404 elements when it computes the semantic version. 406 The algorithm used to produce the derived-semantic-version is as 407 follows: 409 1. Order all modules of the same name by revision from oldest to 410 newest. 412 2. If module A, revision N+1 has failed compilation, bump its 413 derived semantic MAJOR version. 415 3. Else, run "pyang --check-update-from" on module A, revision N 416 and revision N+1 to see if backward-incompatible changes 417 exist. 419 4. If backward-incompatible changes exist, bump module A, 420 revision N+1's derived MAJOR semantic version. 422 5. If no backward-incompatible changes exist, compare the pyang 423 trees of module A, revision N and revision N+1. 425 6. If there are structural differences (e.g., new nodes), bump 426 module A, revision N+1's derived MINOR semantic version. 428 7. If no structural differences exist, bump module A, revision 429 N+1's derived PATCH semantic version. 431 Note that the absolute numbers in the semantic-version and derived- 432 semantic-version are actually meaningless by themselves. That is, 433 one must compare two different semver values for a given module to 434 understand the compatibility between them. 436 4. Open Issues 438 More work is needed in order to fully flesh out the semantic version 439 requirements for YANG modules. These include the following. 441 A new kind of import is required. Today, we have import by 442 revision (though this is seldomly used). There should also be an 443 import by module-version (i.e., the semantic version). This 444 import will not simply be a copy of import by revision. 445 Consideration needs to be given to expressions such as, 446 "version==X", "version>=X", "major version==X", "major 447 version>=X", etc. 449 Similarly to import-by-version, we may also require a new naming 450 convention for modules. Today, modules are named in 451 module@revision.yang notation. Re-using the '@' for version is 452 not ideal. Perhaps a new character such as '%' is needed (i.e., 453 module%version.yang). In this manner, both version and revision 454 could be used. 456 Taking another page from Openconfig, the notion of a module bundle 457 should be considered. That is, there may need to be a way to 458 enumerate modules that are part of a bundle and are known to 459 interoperate. This may not be as critical if a rich import-by- 460 version is defined. 462 Similarly, the concept of a feature bundle should be considered. 463 Typically, operators combine and test YANG modules to build value- 464 add services. These bundles form releases for specific features 465 or services, and it is critical to ensure as the modules evolve, 466 the bundles can coherently evolve with them. 468 More work is needed in order to fully flesh out the semantic version 469 requirements for YANG modules (ultimately, a choice needs to be made 470 as to what the next item is on which to focus). 472 5. Semantic Version Extension Module 474 The extension described in this module is defined in the YANG module 475 below. 477 file "ietf-semver-extension@2017-11-10.yang" 478 module ietf-semver-extension { 479 yang-version 1.1; 480 namespace "urn:ietf:params:xml:ns:yang:ietf-semver-extension"; 481 prefix semver-ext; 483 organization 484 "IETF NETMOD (Network Modeling) Working Group"; 485 contact 486 "WG Web: 487 WG List: 489 Author: Benoit Claise 490 492 Author: Joe Clarke 493 495 Author: Kevin D'Souza 496 "; 497 description 498 "This module contains a defintion for a YANG 1.1 extension to 499 express the semantic version of YANG modules."; 501 revision 2017-11-10 { 502 description 503 "Initial revision."; 504 reference "draft-clacla-netmod-yang-model-update: New YANG Module Update Procedure"; 505 } 507 extension module-version { 508 argument semver; 509 description 510 "The version number for the module. This is 511 expressed as a semantic version number of the form: 512 x.y.z 513 where: 514 * x corresponds to the major version, 515 * y corresponds to a minor version, 516 * z corresponds to a patch version. 517 This version corresponds to the model file within which it is 518 defined. 520 A major version number of 0 indicates that this model is still 521 in development, and is potentially subject to change. 523 Following a release of major version 1, all modules will 524 increment major revision number where backwards incompatible 525 changes to the model are made. 527 The minor version is changed when features are added to the 528 model that do not impact current clients use of the model. 530 The patch-level version is incremented when non-feature changes 531 (such as bugfixes or clarifications to human-readable 532 descriptions that do not impact model functionality) are made 533 that maintain backwards compatibility. 535 The version number is stored in the module meta-data. 537 By comparing the module-version between two revisions of a given 538 module, one can know if revision N+1 is backwards compatible or 539 not relative to revision N, as well as whether or not new features 540 have been added to revision N+1."; 541 reference "http://semver.org/ : Semantic Versioning 2.0.0"; 542 } 543 } 544 546 6. Contributors 548 Anees Shaikh, Google 550 Rob Shakir, Google 552 7. Security Considerations 554 To be completed 556 8. IANA Considerations 558 No IANA action is requested. 560 9. References 562 9.1. Normative References 564 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 565 RFC 7950, DOI 10.17487/RFC7950, August 2016, 566 . 568 9.2. Informative References 570 [I-D.clacla-netmod-model-catalog] 571 Clarke, J. and B. Claise, "YANG module for 572 yangcatalog.org", draft-clacla-netmod-model-catalog-02 573 (work in progress), October 2017. 575 [I-D.claise-semver] 576 Claise, B., Barnes, R., and J. Clarke, "Semantic 577 Versioning and Structure for IETF Specifications", draft- 578 claise-semver-01 (work in progress), July 2017. 580 [I-D.openconfig-netmod-model-catalog] 581 Shaikh, A., Shakir, R., and K. D'Souza, "Catalog and 582 registry for YANG models", draft-openconfig-netmod-model- 583 catalog-02 (work in progress), March 2017. 585 [I-D.wu-l3sm-rfc8049bis] 586 Wu, Q., Litkowski, S., Tomotaki, L., and K. Ogaki, "YANG 587 Data Model for L3VPN Service Delivery", draft-wu-l3sm- 588 rfc8049bis-09 (work in progress), October 2017. 590 [openconfigsemver] 591 "Semantic Versioning for Openconfig Models", 592 . 594 [RFC8049] Litkowski, S., Tomotaki, L., and K. Ogaki, "YANG Data 595 Model for L3VPN Service Delivery", RFC 8049, 596 DOI 10.17487/RFC8049, February 2017, . 599 [RFC8199] Bogdanovic, D., Claise, B., and C. Moberg, "YANG Module 600 Classification", RFC 8199, DOI 10.17487/RFC8199, July 601 2017, . 603 [semver] "Semantic Versioning 2.0.0", . 605 Authors' Addresses 606 Benoit Claise 607 Cisco Systems, Inc. 608 De Kleetlaan 6a b1 609 1831 Diegem 610 Belgium 612 Phone: +32 2 704 5622 613 Email: bclaise@cisco.com 615 Joe Clarke 616 Cisco Systems, Inc. 617 7200-12 Kit Creek Rd 618 Research Triangle Park, North Carolina 619 United States of America 621 Phone: +1-919-392-2867 622 Email: jclarke@cisco.com 624 Kevin D'Souza 625 AT&T 626 200 S. Laurel Ave 627 Middletown, NJ 628 United States of America 630 Email: kd6913@att.com