idnits 2.17.1 draft-verdt-netmod-yang-solutions-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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (July 3, 2019) is 1752 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Unused Reference: 'RFC2119' is defined on line 361, but no explicit reference was found in the text == Unused Reference: 'RFC7950' is defined on line 366, but no explicit reference was found in the text == Unused Reference: 'RFC8049' is defined on line 372, but no explicit reference was found in the text == Unused Reference: 'RFC8199' is defined on line 377, but no explicit reference was found in the text == Unused Reference: 'RFC8299' is defined on line 381, but no explicit reference was found in the text == Outdated reference: A later version (-09) exists of draft-ietf-netmod-yang-versioning-reqs-00 == Outdated reference: A later version (-03) exists of draft-rwilton-netmod-yang-packages-01 == Outdated reference: A later version (-01) exists of draft-verdt-netmod-yang-module-versioning-00 == Outdated reference: A later version (-02) exists of draft-wilton-netmod-yang-ver-selection-00 -- Obsolete informational reference (is this intentional?): RFC 8049 (Obsoleted by RFC 8299) Summary: 0 errors (**), 0 flaws (~~), 11 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group R. Wilton, Ed. 3 Internet-Draft Cisco Systems, Inc. 4 Intended status: Informational July 3, 2019 5 Expires: January 4, 2020 7 YANG Versioning Solution Overview 8 draft-verdt-netmod-yang-solutions-01 10 Abstract 12 This temporary document gives a brief overview of the different 13 drafts that comprise a full solution to the YANG versioning 14 requirements draft. The purpose of this draft is to help readers 15 understand how the discrete parts of the YANG versioning solution fit 16 together during working group development of the solution drafts. 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 January 4, 2020. 35 Copyright Notice 37 Copyright (c) 2019 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. Summary of requirements . . . . . . . . . . . . . . . . . . . 2 54 3. Solution Drafts . . . . . . . . . . . . . . . . . . . . . . . 4 55 3.1. Updated YANG Module Revision Handling . . . . . . . . . . 4 56 3.2. Module semantic version number scheme . . . . . . . . . . 5 57 3.3. Versioned YANG packages . . . . . . . . . . . . . . . . . 5 58 3.4. Protocol operations for package version selection . . . . 6 59 3.5. YANG schema comparison tooling . . . . . . . . . . . . . 6 60 4. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 7 61 5. Security Considerations . . . . . . . . . . . . . . . . . . . 7 62 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 63 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 64 7.1. Normative References . . . . . . . . . . . . . . . . . . 8 65 7.2. Informative References . . . . . . . . . . . . . . . . . 8 66 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 9 68 1. Introduction 70 [I-D.ietf-netmod-yang-versioning-reqs] documents the requirements for 71 any solution to the YANG versioning problem. Chapter 5 lists the 72 formal requirements that a complete solution requires. 74 The aim of this draft is to help readers understand how the different 75 solution drafts fit together, and also which drafts contribute 76 solutions to particular individual requirements. The overall 77 solution comprises five individual drafts: 79 1. [I-D.verdt-netmod-yang-module-versioning] 81 2. Module semantic version number scheme (not yet published) 83 3. [I-D.rwilton-netmod-yang-packages] 85 4. [I-D.wilton-netmod-yang-ver-selection] 87 5. YANG schema comparison tooling (not yet published) 89 Open issues, across all of the solution drafts are tracked at 90 . 92 2. Summary of requirements 94 The requirements are formally documented in section 5 of 95 [I-D.ietf-netmod-yang-versioning-reqs]. A shortened, non normative, 96 summary of each of the requirements (using the same requirement 97 numbers) is provided below to help understand how the solutions 98 drafts address the particular requirements. 100 Req 1.1 - MUST allow nbc updates to a module without breaking 101 imports. 103 Req 1.2 - MUST allow nbc updates to a module without affecting 104 existing client code using only unchanged data nodes. 106 Req 1.3 - MUST support import statement restricted to only some 107 revisions. 109 Req 1.4 - MUST allow for fixes to non-latest published modules. 111 Req 2.1 - MUST be able to determine if two arbitrary versions of 112 any module are backwards-compatible. 114 Req 2.2 - SHOULD be able to determine if two arbitrary versions of 115 any data node are backwards-compatible. 117 Req 3.1 - MUST allow servers to support existing clients. 119 Req 3.2 - MUST allow simultaneously support of clients using 120 different (perhaps restricted) revisions. 122 Req 3.3 - MAY assume clients can handle unexpected instance data 123 gracefully. 125 Req 4.1 - MUST provide a way to indicate if deprecated nodes are 126 implemented. 128 Req 4.2 - MUST be able to document the reason for data node 129 lifecycle changes, and possible alternative data nodes. 131 Req 4.3 - MUST be able to forewarn of future data node lifecycle 132 changes. 134 Req 5.1 - MUST provide guidance on how to use the new scheme. 136 Req 5.2 - MUST provide, and document, an upgrade path from 137 existing YANG/protocols. 139 Req 5.3 - MUST consider the impact of versioning on instance data. 141 3. Solution Drafts 143 The complete solution to the YANG versioning requirements comprises 144 five solution drafts, that are summarized below. 146 3.1. Updated YANG Module Revision Handling 148 In summary, [I-D.verdt-netmod-yang-module-versioning] specifies 149 minimal extensions and updates to the YANG language, YANG Library, 150 and YANG author guidelines to provide more flexible YANG module 151 revision handling. The intent is that these changes and extensions 152 could be folded into future revisions of the updated specifications. 153 The draft provides a solution for all requirements except Req 2.2, 154 Req 3.1 and Req 3.2. 156 The extensions and changes in the draft can be summarized thus: 158 o It defines a YANG extension statement to indicate where non- 159 backwards-compatible changes have occurred in a module's revision 160 history. 162 o It relaxes the rules for the module revision history to allow for 163 a non-linear module revision history. I.e., any given module 164 revision may have multiple revisions directly derived from it. 166 o It defines a new import extension statement that restricts the 167 allowed module revisions that satisfy the import to only those 168 derived from a specified module revision. 170 o It defines a revision label extension statement to allow an 171 informative name to be associated with a particular revision date, 172 and to be used in import statements, YANG module filenames, and is 173 available in YANG library. One example of how the revision label 174 could be used is to associate a semantic versioning scheme to YANG 175 module revisions. 177 o It updates the YANG rules for changes between module revisions 178 that are allowed to be classified as backwards-compatible. In 179 particular, marking a node as obsolete is no longer classified as 180 a backwards compatible change. 182 o It provides updated guidance on how servers handle deprecated and 183 obsolete YANG nodes and augments YANG library with additional 184 leaves to report the server's behavior to clients. 186 o It provides an extension statement to allow a description 187 statement to be associated with a YANG status statement, providing 188 more information about why the status has changed. 190 o It defines how versioning relates to YANG instance data. 192 o It refines the guidelines for updating modules, taking into 193 consideration that non-backwards-compatible changes are sometimes 194 necessary for various pragmatic reasons. 196 3.2. Module semantic version number scheme 198 [TODO - Insert draft ref] defines a semantic versioning scheme 199 derived from the semver.org 2.0.0 specification that can be used in 200 conjunction with the revision label extension statement defined in 201 Section 3.1 to allow semantic version numbers to be used to manage 202 the revision lifecycle of YANG modules. This draft provides an 203 enhanced solution for Req 2.1, but organizations authoring modules 204 are not obliged to use this specific versioning scheme, and could 205 choose a different overlaid versioning scheme, or none at all and 206 rely solely on revision dates. 208 The aims of the YANG semantic versioning scheme are: 210 To generally allow clients to determine whether NBC changes have 211 occurred between two revisions from the version number alone, 212 without having to check the full revision history. 214 To give a more informative identifier for a branched revision 215 history over revision dates alone. 217 To allow revision branches that contain fixes for published non- 218 latest releases. 220 3.3. Versioned YANG packages 222 The two previous drafts address version and revision management of 223 individual modules. [I-D.rwilton-netmod-yang-packages] provides a 224 mechanism to group a set of related YANG modules revisions together, 225 into a construct called a YANG package, and to apply a version scheme 226 to the group. 228 The core part of this draft are YANG module definitions that define a 229 YANG package, that are used as an augmentation to YANG library, and 230 also in YANG instance data documents for offline access. 232 The principle aims of the packages draft are: 234 To provide an alternative simpler mechanism to manage conformance 235 of modules. Rather than checking conformance against a set of 236 individual YANG module revisions, it should be easier to check for 237 conformance against a much smaller set of YANG package versions. 239 To provide an easier mechanism for clients to check conformance 240 with a server. Rather that downloading and comparing all 241 individual module revisions, the client can just check whether the 242 package version is compatible. The package definition could be 243 retrieved and cached from multiple sources. 245 The YANG packages draft does not address any of the versioning 246 requirements directly, but provides the foundation building blocks 247 for the version selection solution, described in Section 3.4, that 248 addresses Reqs 3.1 and 3.2. 250 This draft requires updates to accommodate the split between revision 251 management in [I-D.verdt-netmod-yang-module-versioning] and the 252 semantic versioning scheme. 254 3.4. Protocol operations for package version selection 256 [I-D.wilton-netmod-yang-ver-selection] specifies a solution for 257 requirements 3.1 and 3.2 is via the use of 258 [I-D.rwilton-netmod-yang-packages] and a protocol based version 259 selection scheme that can be used by clients to choose a particular 260 YANG datastore schema from the set of datastore schema that are 261 supported by the server. 263 The version selection optionally allows: 265 Servers to support a single, selectable YANG package at a 266 particular version, that is used for all NETCONF/RESTCONF 267 interactions. 269 Servers to support multiple selectable YANG packages and package 270 versions, with different clients able to concurrently access 271 different packages and different package versions. 273 3.5. YANG schema comparison tooling 275 A tooling based solution is proposed for Req 2.2, that allows two 276 YANG schema versions to be algorithmically compared, with the 277 algorithm reporting the list of differences between the two YANG 278 schema and whether each change is regarded as being backwards- 279 compatible, or non-backwards-compatible. Annotations to the YANG 280 modules, via the use of extension statements, may help improve the 281 accuracy of the comparison algorithm, particularly for statements 282 that are very hard to algorithmically classify the scope of any 283 differences (e.g., a change in the semantic behaviour of a data node 284 defined via modifications to the associated YANG description 285 statement). Given that Req 2.2 is a softer requirement, and 286 practical experience with the tooling is required, it is proposed 287 that this work is deferred at this time. 289 When comparing a module schema, a tool would also be able to take 290 into account enabled features, deviations, and the subset of the 291 schema being used by the client. This would allow a tooling based 292 approach to give a more accurate answer as to whether a client would 293 be affected when upgrading between two software versions, than 294 looking at the revision history, or comparing semantic version 295 numbers. 297 4. Contributors 299 This document grew out of the YANG module versioning design team that 300 started after IETF 101. The following individuals are (or have been) 301 members of that design team and have contributed to defining the 302 problem and specifying the requirements: 304 o Balazs Lengyel 306 o Benoit Claise 308 o Ebben Aries 310 o Jason Sterne 312 o Joe Clarke 314 o Juergen Schoenwaelder 316 o Mahesh Jethanandani 318 o Michael (Wangzitao) 320 o Qin Wu 322 o Reshad Rahman 324 o Rob Wilton 326 o Susan Hares 328 5. Security Considerations 330 The document does not define any new protocol or data model. There 331 is no security impact. 333 6. IANA Considerations 335 None 337 7. References 339 7.1. Normative References 341 [I-D.ietf-netmod-yang-versioning-reqs] 342 Clarke, J., "YANG Module Versioning Requirements", draft- 343 ietf-netmod-yang-versioning-reqs-00 (work in progress), 344 March 2019. 346 [I-D.rwilton-netmod-yang-packages] 347 Wilton, R., "YANG Packages", draft-rwilton-netmod-yang- 348 packages-01 (work in progress), March 2019. 350 [I-D.verdt-netmod-yang-module-versioning] 351 Claise, B., Clarke, J., Rahman, R., Wilton, R., Lengyel, 352 B., Sterne, J., and K. D'Souza, "Updated YANG Module 353 Revision Handling", draft-verdt-netmod-yang-module- 354 versioning-00 (work in progress), July 2019. 356 [I-D.wilton-netmod-yang-ver-selection] 357 Wilton, R. and R. Rahman, "YANG Schema Version Selection", 358 draft-wilton-netmod-yang-ver-selection-00 (work in 359 progress), March 2019. 361 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 362 Requirement Levels", BCP 14, RFC 2119, 363 DOI 10.17487/RFC2119, March 1997, 364 . 366 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 367 RFC 7950, DOI 10.17487/RFC7950, August 2016, 368 . 370 7.2. Informative References 372 [RFC8049] Litkowski, S., Tomotaki, L., and K. Ogaki, "YANG Data 373 Model for L3VPN Service Delivery", RFC 8049, 374 DOI 10.17487/RFC8049, February 2017, 375 . 377 [RFC8199] Bogdanovic, D., Claise, B., and C. Moberg, "YANG Module 378 Classification", RFC 8199, DOI 10.17487/RFC8199, July 379 2017, . 381 [RFC8299] Wu, Q., Ed., Litkowski, S., Tomotaki, L., and K. Ogaki, 382 "YANG Data Model for L3VPN Service Delivery", RFC 8299, 383 DOI 10.17487/RFC8299, January 2018, 384 . 386 Author's Address 388 Robert Wilton (editor) 389 Cisco Systems, Inc. 391 Email: rwilton@cisco.com