idnits 2.17.1 draft-clacla-netmod-yang-model-update-01.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 : ---------------------------------------------------------------------------- ** 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 85: '...name. Thus, a module name MUST NOT be...' RFC 2119 keyword, line 86: '... the "namespace" statement MUST NOT be...' RFC 2119 keyword, line 92: '... 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 (October 30, 2017) is 2370 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: 1 error (**), 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 J. D'Souza 6 Expires: May 3, 2018 AT&T 7 October 30, 2017 9 New YANG Module Update Procedure 10 draft-clacla-netmod-yang-model-update-01 12 Abstract 14 This document specifies a new YANG module update procedure in case of 15 non backward-compatible changes, as an alternative proposal to the 16 YANG 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 https://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 3, 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 (https://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. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 9 64 5. Security Considerations . . . . . . . . . . . . . . . . . . . 10 65 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 66 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 67 7.1. Normative References . . . . . . . . . . . . . . . . . . 10 68 7.2. Informative References . . . . . . . . . . . . . . . . . 10 69 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 11 71 1. Introduction 73 The YANG data modeling language [RFC7950] specifies strict rules for 74 updating YANG modules (see section 11 "Updating a Module"). Citing a 75 few of the relevant rules for this document: 77 1. "As experience is gained with a module, it may be desirable to 78 revise that module. However, changes to published modules are 79 not allowed if they have any potential to cause interoperability 80 problems between a client using an original specification and a 81 server using an updated specification." 83 2. "Note that definitions contained in a module are available to be 84 imported by any other module and are referenced in "import" 85 statements via the module name. Thus, a module name MUST NOT be 86 changed. Furthermore, the "namespace" statement MUST NOT be 87 changed, since all XML elements are qualified by the namespace." 89 3. "Otherwise, if the semantics of any previous definition are 90 changed (i.e., if a non-editorial change is made to any 91 definition other than those specifically allowed above), then 92 this MUST be achieved by a new definition with a new identifier." 94 What are the consequences? 95 1. Ideally, the YANG module names should not be changed due the 96 importance of not changing the automation code in case of import 97 statements or service composition at the orchestrator. 99 2. When the same YANG module name is kept, the new YANG module 100 revision must always be updated in a backward-compatible way. 102 2. The Problems 104 This section lists a series of problems, hopefully listed in a 105 logical order, which leads to the solution in the next section. 107 2.1. Slow Standardization 109 The conclusions drawn in the introduction lead to the logical 110 conclusion that the standardized YANG modules have to be perfect day 111 one (at least the structure), which in turns, might explain why all 112 the IETF YANG modules take so long to standardize. Shooting for 113 perfection (at least the structure) is obviously a noble goal but, if 114 the perfect standard comes too late, it doesn't help the industry. 116 2.2. Some YANG Modules are Not Backward Compatible 118 As we learn from our mistakes, we're going to face more and more non 119 backward-compatible YANG modules. An example is the YANG data model 120 for L3VPN service delivery [RFC8049], which, based on implementation 121 experience, must be updated in a non backward-compatible way with 122 draft-wu-l3sm-rfc8049bis [I-D.wu-l3sm-rfc8049bis]. 124 While Standardized Development Organization YANG modules are 125 obviously better for the industry, we must recognize that many YANG 126 modules are actually generated YANG modules (for example, from 127 internal database), also known as native YANG modules, or vendor 128 modules [RFC8199]. From time to time, the new YANG modules are not 129 backward-compatible. 131 In such cases, it would be better to indicate how backward-compatible 132 YANG modules are. 134 2.3. A Zoo of YANG Modules 136 Even if we focus on the IETF, we have to observe that many Standard 137 Development Organizations, opensource fora, and vendors develop YANG 138 modules develop YANG modules. This should be considered a success 139 for an IETF developed technoogy. However, the operators are faced 140 with this problem: how to select the YANG modules to take into 141 account for their service developments. 143 The site (and the YANG catalog that it 144 provides: YANG module for yangcatalog.org, 145 [I-D.clacla-netmod-model-catalog]) is an attempt to become a 146 reference for all YANG modules available in the industry, for both 147 YANG developers to search on what exists already) and for operators 148 (to discover the more mature YANG models to automate services). This 149 YANG catalog should not only contain pointers to the YANG modules 150 themselves, but also contain metadata related to those YANG modules: 151 What is the module type (service model or not?); what is the maturity 152 level? (e.g., for the IETF: is this an RFC, a working group document 153 or an individual draft?); is this module implemented?; who is the 154 contact?; is there open-source code available? And we expect many 155 more in the future. The industry has begun to understand that the 156 metadata related to YANG models become equally important as the YANG 157 models themselves. 159 The yangcatalog.org instantiation of the catalog provides a means for 160 module authors and vendors implementing modules to upload their 161 metadata, which is then searchable via an API, as well as using a 162 variety of web-based tools. The instructions for contributing and 163 searching for metadata can be found at . 166 The issue is actually the number of YANG modules the operators are 167 offered. At the time of writing these lines, the number of unique 168 YANG modules in the catalog is exactly 2596 (and the number keeps 169 growing), while the IETF has standardized or is busy standardizing a 170 small subset of those. Therefore, it's important to distinguish the 171 relevant YANG modules with the pack and to understand the 172 relationship between the YANG modules. 174 2.4. YANG Modules Obsolete Relationship 176 So the operators use the yangcatalog.org to discover which YANG 177 modules they can use NOW. They base their selection not only on the 178 YANG module content, but also on the related metadata. When faced 179 with the zoo of the YANG modules, it's difficult to understand the 180 relationship between YANG modules. As an example: how could an 181 operator discovers that a YANG-MODULE-B obsoletes YANG-MODULE-A? 182 Indeed, both have different YANG module names. The only available 183 information is an "obsolete" tag in the published RFC containing 184 YANG-MODULE-B: this tag would point to YANG-MODULE-A. In the world 185 of automation, going through a published RFC as a level of 186 indirection to understand the YANG module obsolete relationship is a 187 non starter. Food for thought: the IETF should stop thinking that 188 the metric for success is an RFC number, as opposed to the contained 189 YANG module(s). 191 We need an automatic way to discover that a YANG-MODULE-B obsoletes 192 YANG-MODULE-A, so that YANG-MODULE-A should not be given any 193 attention. 195 The following example is not an automatic way. 197 description 198 "This YANG module defines a generic service configuration 199 model for Layer 3 VPNs. This model is common across all 200 vendor implementations. This obsoletes the RFC8049 YANG 201 module, ietf-l3vpn-svc@2017-01-2"; 202 revision 2017-09-14 { 203 description 204 "First revision of RFC8049."; 205 reference 206 "RFC xxxx: YANG Data Model for L3VPN Service Delivery"; 208 Along the same lines, going through an offline tool such as the 209 yangcatalog.org, in order to discover the obsolete relationship is a 210 possible automatic way, but not ideal. 212 2.5. YANG Module Transition Strategy 214 Let's assume for a moment that we change the YANG module, with the 215 specific example of the ietf-routing, which some propose to update to 216 ietf-routing-2. 218 Here are all the ietf-routing dependent YANG modules (those modules 219 that depend on ietf-routing) . So many 222 YANG modules. 224 Let's look at the difference for ietf-routing-2: 225 . 229 Changing the module name from ietf-routing to ietf-routing-2 implies 230 that the we have to warn all draft authors of ietf-routing YANG 231 dependent modules. Firstly, to make sure they are aware of ietf- 232 routing-2 (publishing a RFC8022bis mentioning in the module 233 description that this module is not compatible with the NMDA 234 architecture, and providing a pointer to ietf-routing-2 ... is not an 235 automatic way... so barely useful). And secondly, to ask them to 236 change their import (or service composition) to ietf-routing-2. 237 Hopefully, in the ietf-routing case, all dependent YANG modules are 238 part of the IETF, so the communication is a manageable. 240 Changing the ietf-interfaces YANG module name would be a different 241 challenge, as it's used throughout the industry: 242 246 3. The Solution 248 The solution is composed of two mandator aspects, a semantic 249 versioning YANG extension and an update to RFC7950. An optional 250 additional check, validating the semantic versioning from a syntact 251 point of view, can either assist in determining the correct semantic 252 versioning values, or can help in determining the values for YANG 253 modules that don't support this extension. 255 3.1. SEMVER Semantic Versioning 257 The semantic versioning solution proposed here as already been 258 proposed in [I-D.openconfig-netmod-model-catalog] (cut/paste here 259 with the authors permission)which itself is based on 260 [openconfigsemver]. The goal is to indicate the YANG module 261 backwards (in)compatibility, following semver.org semantic versioning 262 [semver]: 264 MAJOR is incremented when the new version of the specification is 265 incompatible with previous versions. 267 MINOR is incremented when new functionality is added in a manner 268 that is backward-compatible with previous versions. 270 PATCH is incremented when bug fixes are made in a backward- 271 compatible manner. 273 // extension statements 274 extension openconfig-version { 275 argument "semver" { 276 yin-element false; 277 } 278 description 279 "The OpenConfig version number for the module. This is 280 expressed as a semantic version number of the form: 281 x.y.z 282 where: 283 * x corresponds to the major version, 284 * y corresponds to a minor version, 285 * z corresponds to a patch version. 286 This version corresponds to the model file within which it is 287 defined, and does not cover the whole set of OpenConfig models. 288 Where several modules are used to build up a single block of 289 functionality, the same module version is specified across each 290 file that makes up the module. 292 A major version number of 0 indicates that this model is still 293 in development (whether within OpenConfig or with industry 294 partners), and is potentially subject to change. 296 Following a release of major version 1, all modules will 297 increment major revision number where backwards incompatible 298 changes to the model are made. 300 The minor version is changed when features are added to the 301 model that do not impact current clients use of the model. 303 The patch-level version is incremented when non-feature changes 304 (such as bugfixes or clarifications to human-readable 305 descriptions that do not impact model functionality) are made 306 that maintain backwards compatibility. 308 The version number is stored in the module meta-data."; 309 } 311 The extension would typically be used this way: 313 module yang-module-name { 315 yang-version "1"; 316 namespace "name-space"; 317 prefix "prefix-name"; 319 import openconfig-extensions { prefix "oc-ext"; } 321 organization 322 "to be completed"; 324 contact 325 "to be completed"; 327 description 328 "to be completed"; 330 oc-ext:openconfig-version "1.1.2"; 332 revision 2017-10-30 { 333 description 334 "Change the module structure"; 335 reference "1.1.2"; 336 } 338 revision 2017-07-30 { 339 description 340 "Fixed unprintable character"; 341 reference "0.1.2"; 342 } 344 revision 2017-04-03 { 345 description 346 "Update copyright notice."; 347 reference "0.1.1"; 348 } 350 revision 2017-01-26 { 351 description 352 "Initial module for inet types"; 353 reference "0.1.0"; 354 } 356 //YANG module definition starts here 358 See also "Semantic Versioning and Structure for IETF Specifications" 359 [I-D.claise-semver] for a mechanism to combine the semantic 360 versioning, the github tools, and a potential change to the IETF 361 process. 363 3.2. Updating the YANG 1.1 Specifications 365 RFC 7950 section 11, must be updated to express: 367 "As experience is gained with a module, it may be desirable to revise 368 that module. Changes to published modules are allowed, even if they 369 have some potential to cause interoperability problems, at the 370 condition that the semantic versioning change are clearly indicated 371 based on the SEMVER YANG extension." 373 3.3. The Derived Semantic Version 375 The YANG catalog contains not only the most up-to-date YANG module 376 revision of a given module, but keeps all previous revisions as well. 377 With APIs in mind, it's important to understand whether different 378 YANG module revisions are backward compatible (this is specifically 379 imported for native YANG modules, i.e. the ones where generated-from 380 = native), even for the YANG modules that don't support the YANG 381 extension specified in this document. 383 Two distinct leaves in the YANG module 384 [I-D.clacla-netmod-model-catalog] contains this semver semantic: 386 the semantic-version leaf contains the value reported as metadata 387 by a specific YANG module. 389 the derived-semantic-version leaf is established by examining the 390 the YANG module themselves. As such, only the YANG syntax, as 391 opposed to the implementation changes that lead some some semantic 392 changes. 394 The derived-semantic-version is based on "pyang --check-update-from", 395 which checks the backward compatibility from a syntax point of view. 397 Note that the absolute numbers in the semantic-version and derived- 398 semantic-version are actually meaningless: the difference between two 399 YANG module semver fields should be looked at. 401 4. Contributors 403 Anees Shaikh, Google 405 Rob Shakir, Google 407 5. Security Considerations 409 To be completed 411 6. IANA Considerations 413 No IANA action is requested. 415 7. References 417 7.1. Normative References 419 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 420 RFC 7950, DOI 10.17487/RFC7950, August 2016, 421 . 423 7.2. Informative References 425 [I-D.clacla-netmod-model-catalog] 426 Clarke, J. and B. Claise, "YANG module for 427 yangcatalog.org", draft-clacla-netmod-model-catalog-02 428 (work in progress), October 2017. 430 [I-D.claise-semver] 431 Claise, B., Barnes, R., and J. Clarke, "Semantic 432 Versioning and Structure for IETF Specifications", draft- 433 claise-semver-01 (work in progress), July 2017. 435 [I-D.openconfig-netmod-model-catalog] 436 Shaikh, A., Shakir, R., and K. D'Souza, "Catalog and 437 registry for YANG models", draft-openconfig-netmod-model- 438 catalog-02 (work in progress), March 2017. 440 [I-D.wu-l3sm-rfc8049bis] 441 Wu, Q., Litkowski, S., Tomotaki, L., and K. Ogaki, "YANG 442 Data Model for L3VPN Service Delivery", draft-wu-l3sm- 443 rfc8049bis-09 (work in progress), October 2017. 445 [openconfigsemver] 446 "Semantic Versioning for Openconfig Models", 447 . 449 [RFC8049] Litkowski, S., Tomotaki, L., and K. Ogaki, "YANG Data 450 Model for L3VPN Service Delivery", RFC 8049, 451 DOI 10.17487/RFC8049, February 2017, 452 . 454 [RFC8199] Bogdanovic, D., Claise, B., and C. Moberg, "YANG Module 455 Classification", RFC 8199, DOI 10.17487/RFC8199, July 456 2017, . 458 [semver] "Semantic Versioning 2.0.0", . 460 Authors' Addresses 462 Benoit Claise 463 Cisco Systems, Inc. 464 De Kleetlaan 6a b1 465 1831 Diegem 466 Belgium 468 Phone: +32 2 704 5622 469 Email: bclaise@cisco.com 471 Joe Clarke 472 Cisco Systems, Inc. 473 7200-12 Kit Creek Rd 474 Research Triangle Park, North Carolina 475 United States of America 477 Phone: +1-919-392-2867 478 Email: jclarke@cisco.com 480 Kevin D'Souza 481 AT&T 482 200 S. Laurel Ave 483 Middletown, NJ 484 United States of America 486 Email: kd6913@att.com