NETMOD Working Group M. Wang Internet-Draft Q. Wu Intended status: Standards Track Huawei Expires: August 16, 2018 February 12, 2018 A YANG Data Model for module revision management draft-wang-netmod-module-revision-management-00 Abstract This document defines a YANG Data Model for module revision management. It is intended this model be used by vendors who support multiple revisions of the same YANG module in their systems but implement one revision of a module. In addition, this document introduces a new generic mechanism based on RPC, denoted as module- revision-change, that allow to report discrepancy information of a YANG module with two or multiple revisions that is defined in design time., e.g.,identifies a place in the node hierarchy where data node gets changed or new data gets inserted and indicate whether the change to the data node is backward compatible. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on August 16, 2018. Copyright Notice Copyright (c) 2018 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents Wang & Wu Expires August 16, 2018 [Page 1] Internet-Draft Module Revision Management February 2018 carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 2. Terminologies . . . . . . . . . . . . . . . . . . . . . . . . 3 3. Design of YANG data model for module revision management . . 3 3.1. yang-modules . . . . . . . . . . . . . . . . . . . . . . 4 3.1.1. yang-modules/module . . . . . . . . . . . . . . . . . 5 3.1.2. yang-modules/change-log . . . . . . . . . . . . . . . 5 3.2. RPC definition for module revision change . . . . . . . . 5 3.2.1. Usage Example . . . . . . . . . . . . . . . . . . . . 5 4. Library Augmentation . . . . . . . . . . . . . . . . . . . . 7 5. Multiple revisions module management . . . . . . . . . . . . 7 6. Yang Data Model Definition . . . . . . . . . . . . . . . . . 8 7. Security Considerations . . . . . . . . . . . . . . . . . . . 15 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 16 10. Normative References . . . . . . . . . . . . . . . . . . . . 16 Appendix A. Example of Module Revision Management . . . . . . . 17 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 19 1. Introduction The revised Network Management Datastore Architecture (NMDA) defines a set of new datastores that each hold YANG-defined data [RFC7950] and represent a different "viewpoint" on the data that is maintained by a server. To support the NMDA, many modules may need to be updated or restructured especially for some published non-NMDA modules, the model should be republished with an NMDA-compatible structure, deprecating non-NMDA constructs [I-D.ietf-netmod-rfc6087bis]. Therefore, how to support hackward- compatible and indicate the module's changes is an issue. As described in RFC7950, a module name MUST NOT be changed when definitions contained in a module are available to be imported by any other module and are referenced in "import" statements via the module name. In some case, when we make non-backward compatible updates, the module name might be forced to change. In order to provide an easy way to indicate how backward-compatible a given YANG module actually is, This document defines a YANG Data Model for module revision management. It is intended this model be used by vendors who support multiple revisions of the same YANG Wang & Wu Expires August 16, 2018 [Page 2] Internet-Draft Module Revision Management February 2018 module in their systems but implement one revision of a module. In addition, this document introduces a new generic mechanism based on RPC, denoted as module-revision-change, that allow to report discrepancy information of a YANG module with two or multiple revisions that is defined in design time., e.g.,identifies a place in the node hierarchy where data node gets changed or new data gets inserted and indicate whether the change to the data node is backward compatible. 2. Terminologies The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14, [RFC2119]. The following terms are defined in [RFC6241] and are not redefined here: o client o notification o server The following terms are defined in [RFC7950] and are not redefined here: action container list operation 3. Design of YANG data model for module revision management The "ietf-module-revision-management" module provides per revision the module discrepancy information used by a server. This module is defined using YANG version 1.1, but it supports the description of YANG modules written in any revision of YANG. All data nodes in "ietf-module-revision-management" are "config false", and thus accessible in the operational state datastore. Following is the YANG Tree Diagram for the "ietf-module-revision- management" module: Wang & Wu Expires August 16, 2018 [Page 3] Internet-Draft Module Revision Management February 2018 module: ietf-module-revision +--ro yang-modules +--ro module* [name revision] +--ro name yang:yang-identifier +--ro revision yanglib:revision-identifier +--ro backward-compatible? boolean +--ro module-change-log* [index] +--ro index uint32 +--ro change-operation identityref +--ro (update-blocks)? +--:(data-definition-statement) | +--ro data-definition | +--ro target-node yang:xpath1.0 | +--ro location-point? yang:xpath1.0 | +--ro where? enumeration | +--ro data-definition? +--:(other-statement) +--ro other-statement +--ro statement-name? identityref +--ro statement-definition? +--ro substatements* [statement-name] +--ro statement-name identityref +--ro substatement-definition? augment /yanglib:yang-library/yanglib:module-set/yanglib:module: +--ro backward-compatible? boolean augment /yanglib:yang-library/yanglib:module-set/yanglib:module/yanglib:submodule: +--ro backward-compatible? boolean rpcs: +---x module-revision-change +---w input | +---w module-name yang:yang-identifier | +---w source-revision? yanglib:revision-identifier | +---w target-revision? yanglib:revision-identifier +--ro output +--ro data-nodes* [data-node-name] +--ro data-node-name string +--ro is-new-node? boolean +--ro change-operation? identityref 3.1. yang-modules This container holds all per revision the module discrepancy information used by a server. Wang & Wu Expires August 16, 2018 [Page 4] Internet-Draft Module Revision Management February 2018 3.1.1. yang-modules/module This mandatory list contains one entry for each revision of each YANG module that is used by the server. It is possible for multiple revisions of the same module to be imported, in addition to an entry for the revision that is implemented by the server. Multiple revisions of the same module are either backward-compatible or non backward-compatible. 3.1.2. yang-modules/change-log This list contains one entry for each schema node change from previous revision known by the server, and identifies schema node change path,location, operation and associated with corresponding schema node in the "change-log" list. Each revision of the YANG module has multiple entries. A change log is an ordered collection of changes that are applied to one revision of YANG module. Each change is identified by an "index", and it has an change operation ("create", "delete","move", "modify") that is applied to the target resource. Each change can be applied to a sub-resource "target" within the target resource. If the operation is "move", then the "where" parameter indicates how the node is moved. For values "before" and "after", the "point" parameter specifies the data node insertion point. Each entry within a change log MUST identify exactly one data definition change or other statement change. 3.2. RPC definition for module revision change The "module-revision-change" rpc statement is defined to retrieve the schema data node changes between any two revisions of the same module, i.e. the data node that get updated or newly added during module revision change. This rpc statement takes module identification information as input, and provides the list of data nodes that make changes or are newly added in the later revision. 3.2.1. Usage Example For example, there are two revisions of the same module, the yang codes are shown as below: module example-a{ yang-version 1.1; namespace "urn:example:a"; prefix "a"; Wang & Wu Expires August 16, 2018 [Page 5] Internet-Draft Module Revision Management February 2018 organization "foo."; contact "fo@example.com"; description "foo."; revision 2017-12-01 { description "Initial revision."; } container system { leaf host-name { type string; description "Hostname for this system."; } } } module example-a{ yang-version 1.1; namespace "urn:example:a"; prefix "a"; organization "foo."; contact "fo@example.com"; description "foo."; revision 2017-12-20{ description "Initial revision."; } container system { leaf host-name { type string; description "Hostname for this system."; } leaf b { type string; description "foo"; } } If we initiate a "module-revision-change" RPC to retrieve the changes between two revisions of module "a", the NETCONF XML example are shown as below: Wang & Wu Expires August 16, 2018 [Page 6] Internet-Draft Module Revision Management February 2018 example-a 1.0.0 2.0.0 0001 b true major-change 4. Library Augmentation Backward compatibility for each revision of YANG module can also be read using the yang library [I-D.ietf-netconf-rfc7895bis] if a server supports both YANG library and the augmentation defined below. If a server supports indication of backward compatibility forone revision of and the YANG module, it SHOULD also support the "ietf-module- revision" module. The tree associated with the defined augmentation is: module: ietf-module-revisions augment /yanglib:yang-library/yanglib:modules/yanglib:module: +--ro backward-compatible? bool augment /yanglib:yanglibrary/yanglib:modules/yanglib:module /yanglib:submodule: +--ro backward-compatible? bool 5. Multiple revisions module management As experience is gained with a module, it may be desirable to support multiple revisions of that module in their systems but implement one revision of a module at each time. To indicate the details changes of that module, e.g., identifies schema node change path,location, operation and associated with corresponding schema node, it will be desirable to use 'ietf-module-revision' defined in this document to manage all the revisions of that module and keep track of module Wang & Wu Expires August 16, 2018 [Page 7] Internet-Draft Module Revision Management February 2018 change discrepancy in different revision, especially when the new revision is not backward compatible with previous revision. 6. Yang Data Model Definition file "ietf-module-revision@2018-02-11.yang" module ietf-module-revision { yang-version 1.1; namespace "urn:ietf:params:xml:ns:yang:ietf-module-revision"; prefix ml; import ietf-yang-library { prefix yanglib; } import ietf-yang-types { prefix yang; } organization "IETF Network Modeling (NETMOD) Working Group"; contact "WG Web: WG List: Author: Qin Wu Zitao Wang "; description "This YANG module defines an module log."; revision 2018-02-11 { description "Initial revision."; reference "RFC XXXX: Using Metadata with YANG for Module revisions"; } identity operation-type { description "Abstract base identity for the operation type "; } identity create { base operation-type; description "Denotes create new data nodes"; Wang & Wu Expires August 16, 2018 [Page 8] Internet-Draft Module Revision Management February 2018 } identity delete { base operation-type; description "Denotes delete the target node"; } identity move { base operation-type; description "Denote move the target node."; } identity modify { base operation-type; description "Denote modify the target data node."; } identity statement-type { description "Base identity for statement type"; } identity feature-statement { base statement-type; description "feature statement, if this type be chose, it means that the feature or if-feature statement been modified"; } identity identity-statement { base statement-type; description "identity statement, if this type be chose, it means that the identity statement been modified, for example, add new identity, etc."; } identity grouping-statement { base statement-type; description "grouping statement, if this type be chose, it means that the grouping statement been modified."; } identity typedef-statement { base statement-type; Wang & Wu Expires August 16, 2018 [Page 9] Internet-Draft Module Revision Management February 2018 description "typedef statement, if this type be chose, it means that the typedef statement been modified."; } identity augment-statement { base statement-type; description "augment statement, if this type be chose, it means that the augment statement been modified."; } identity rpc-statement { base statement-type; description "rpc statement, if this type be chose, it means that the rpc statement been modified."; } identity notification-statement { base statement-type; description "notification statement, if this type be chose, it means that the notification statement been modified."; } grouping data-definition { container data-definition { leaf target-node { type yang:xpath1.0; mandatory true; description "Identifies the target data node for update. Notice that, if the update-type equal to move or delete, this target-node must point to the data node of old version. \t For example, suppose the target node is a YANG leaf named a, and the previous version is: \t container foo { leaf a { type string; } leaf b { type int32; } } \t the new version is: container foo { leaf b {type int32;} } Wang & Wu Expires August 16, 2018 [Page 10] Internet-Draft Module Revision Management February 2018 \t Therefore, the targe-node should be /foo/a."; } leaf location-point { type yang:xpath1.0; description "Identifies the location point where the updates happened."; } leaf where { when "derived-from-or-self(../../change-operation, 'move')" { description "This leaf only applies for 'move' updates."; } type enumeration { enum "before" { description "Insert or move a data node before the data resource identified by the 'point' parameter."; } enum "after" { description "Insert or move a data node after the data resource identified by the 'point' parameter."; } enum "first" { description "Insert or move a data node so it becomes ordered as the first entry."; } enum "last" { description "Insert or move a data node so it becomes ordered as the last entry."; } } default "last"; description "Identifies where a data resource will be inserted or moved."; } anydata data-definition { when "derived-from-or-self(../../change-operation, 'modify')" { description "This nodes only be present when the 'change-operation' equal to 'modify'."; } description Wang & Wu Expires August 16, 2018 [Page 11] Internet-Draft Module Revision Management February 2018 "This nodes used for present the definitions before updated. And this nodes only be present when the 'change-operation' equal to 'modify'."; } description "Container for data statement"; } description "Grouping for data definition"; } grouping other-statement { container other-statement { leaf statement-name { type identityref { base statement-type; } description "Statement name, for example, identity, feature, typedef, etc."; } anydata statement-definition { description "This nodes used for present new the definitions."; } list substatements { key "statement-name"; leaf statement-name { type identityref { base statement-type; } description "Statement name, for example, identity, feature, typedef, etc."; } anydata substatement-definition { description "This nodes used for present new the definitions."; } description "List for substatements updates"; } description "Container for header statement updates"; } description "Grouping for header statement"; } grouping change-log { Wang & Wu Expires August 16, 2018 [Page 12] Internet-Draft Module Revision Management February 2018 list module-change-log { key "index"; leaf index { type uint32; description "Index for module change log"; } leaf change-operation { type identityref { base operation-type; } mandatory true; description "This leaf indicate the change operation, such as create, move, delete, modify, etc."; } choice blocks-update { description "Choice for update block, this nodes can explicit present the update blocks"; case data-definition-statement { uses data-definition; } case other-statement { uses other-statement; } } description "List for module change log"; } description "Grouping for module updated log"; } container yang-modules { config false; list module { key "name revision"; leaf name { type yang:yang-identifier; description "The YANG module or submodule name."; } leaf revision { type yanglib:revision-identifier; description "The YANG module or submodule revision date. If no revision statement is present in the YANG module or submodule, this leaf is not instantiated."; } Wang & Wu Expires August 16, 2018 [Page 13] Internet-Draft Module Revision Management February 2018 leaf backward-compatible { type boolean; description "Indicates whether it is a backward compatible version. If this parameter is set to true, it means that this version is a backwards compatible version"; } uses change-log; description "List for module updated log"; } description "This container present the modules updated log."; } augment "/yanglib:yang-library/yanglib:module-set/yanglib:module" { description "Augment the yang library with backward compatibility indication."; leaf backward-compatible { type boolean; description "backward compatibility indication."; } } augment "/yanglib:yang-library/yanglib:module-set/yanglib:module/yanglib:submodule" { description "Augment the yang library with backward compatibility indication."; leaf backward-compatible { type boolean; description "backward compatibility indication."; } } rpc module-revision-change { description "Module Node change query operation."; input { leaf module-name { type yang:yang-identifier; mandatory true; description "The YANG module or submodule name."; } leaf source-revision { type yanglib:revision-identifier; description "The Source YANG module revision date. If no revision statement is present in the YANG module or submodule, this leaf is not instantiated."; Wang & Wu Expires August 16, 2018 [Page 14] Internet-Draft Module Revision Management February 2018 } leaf target-revision { type yanglib:revision-identifier; description "The target YANG module revision date. If no revision statement is present in the YANG module or submodule, this leaf is not instantiated."; } } output { list data-nodes { key "data-node-name"; description "Each entry represents a data node of a given module that have been changed from source revision of a module to target revision of the module."; leaf data-node-name { type string; description "a data node name of a given module that has been changed."; } leaf is-new-node { type boolean; description "indicate the data node is newly introduced node in the target revision."; } leaf change-operation { type identityref { base operation-type; } description "This leaf indicate the change operation, such as create, move, delete, modify, etc."; } } } } } 7. Security Considerations This document defines a mechanism that is put at a place in the node hierarchy where data node gets changed or new data gets inserted and indicate whether the change to the data node is backward compatible and as such doesn't introduce new security issues. Wang & Wu Expires August 16, 2018 [Page 15] Internet-Draft Module Revision Management February 2018 8. IANA Considerations This document registers a URI in the IETF XML registry [RFC3688]. Following the format in [RFC3688], the following registration is requested to be made: --------------------------------------------------------------------- URI: urn:ietf:params:xml:ns:yang:ietf-module-revision Registrant Contact: The NETMOD WG of the IETF. XML: N/A, the requested URI is an XML namespace. --------------------------------------------------------------------- This document registers a YANG module in the YANG Module Names registry [RFC6020]. --------------------------------------------------------------------- Name: ietf-module-revision Namespace: urn:ietf:params:xml:ns:yang:ietf-module-revision Prefix: md Reference: RFC xxxx --------------------------------------------------------------------- 9. Acknowledgements This work is motivated from the discussions of module version in IETF 100 Singapore meeting. Thanks to Juergen Schoenwaelder and Adrian Farrel for useful comments on this work. 10. Normative References [I-D.ietf-netconf-rfc7895bis] Bierman, A., Bjorklund, M., Schoenwaelder, J., Watsen, K., and R. Wilton, "YANG Library", draft-ietf-netconf- rfc7895bis-04 (work in progress), January 2018. [I-D.ietf-netmod-rfc6087bis] Bierman, A., "Guidelines for Authors and Reviewers of YANG Data Model Documents", draft-ietf-netmod-rfc6087bis-15 (work in progress), December 2017. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", March 1997. [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, DOI 10.17487/RFC3688, January 2004, . Wang & Wu Expires August 16, 2018 [Page 16] Internet-Draft Module Revision Management February 2018 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)", RFC 6020, DOI 10.17487/RFC6020, October 2010, . [RFC7223] Bjorklund, M., "A YANG Data Model for Interface Management", RFC 7223, DOI 10.17487/RFC7223, May 2014, . [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", RFC 7950, DOI 10.17487/RFC7950, August 2016, . [RFC7952] Lhotka, L., "Defining and Using Metadata with YANG", RFC 7952, DOI 10.17487/RFC7952, August 2016, . Appendix A. Example of Module Revision Management This section provides an example to generate XML snippet of ietf- module-revision based on the changes between the new revision of interface model as specified in [draft-ietf-netmod-rfc7223bis] and the old revision of interface model as specified in [RFC7223]. ietf-interfaces 2018-01-09 false 0001 delete /if:interfaces-state 0002 create feature-statement Wang & Wu Expires August 16, 2018 [Page 17] Internet-Draft Module Revision Management February 2018 feature if-mib { description "This feature indicates that the device implements the IF-MIB."; reference "RFC 2863: The Interfaces Group MIB"; } 0003 modify /if:interfaces/if:interface/if:link-up-down-trap-enable leaf link-up-down-trap-enable { if-feature if-mib; // add if-feature statement type enumeration { .... 0004 move /if:interfaces-state/if:interface/if:admin-status /if:interfaces/if:interface/link-up-down-trap-enable after Wang & Wu Expires August 16, 2018 [Page 18] Internet-Draft Module Revision Management February 2018 0005 move /if:interfaces-state/if:interface/if:statistics /if:interfaces/if:interface/if:speed after ....... Authors' Addresses Michael Wang Huawei Technologies,Co.,Ltd 101 Software Avenue, Yuhua District Nanjing 210012 China Email: wangzitao@huawei.com Qin Wu Huawei 101 Software Avenue, Yuhua District Nanjing, Jiangsu 210012 China Email: bill.wu@huawei.com Wang & Wu Expires August 16, 2018 [Page 19]