New YANG Module Update Procedure
draft-clacla-netmod-yang-model-update-00

Network Working Group                                          B. Claise
Internet-Draft                                                 J. Clarke
Updates: 7950 (if approved)                          Cisco Systems, Inc.
Intended status: Standards Track                               J. Shakir
Expires: May 3, 2018                                              Google
                                                              J. D'Souza
                                                                    AT&T
                                                        October 30, 2017

                    New YANG Module Update Procedure
                draft-clacla-netmod-yang-model-update-00

Abstract

   This document specifies a new YANG module update procedure in case of
   non backward-compatible changes, as an alternative proposal to the
   YANG 1.1 specifications.  This document updates RFC 7950.

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 May 3, 2018.

Copyright Notice

   Copyright (c) 2017 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
   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

Claise, et al.             Expires May 3, 2018                  [Page 1]
Internet-Draft                YANG Catalog                  October 2017

   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
   2.  The Problems  . . . . . . . . . . . . . . . . . . . . . . . .   3
     2.1.  Slow Standardization  . . . . . . . . . . . . . . . . . .   3
     2.2.  Some YANG Modules are Not Backward Compatible . . . . . .   3
     2.3.  A Zoo of YANG Modules . . . . . . . . . . . . . . . . . .   3
     2.4.  YANG Modules Obsolete Relationship  . . . . . . . . . . .   4
     2.5.  YANG Module Transition Strategy . . . . . . . . . . . . .   5
   3.  The Solution  . . . . . . . . . . . . . . . . . . . . . . . .   6
     3.1.  SEMVER Semantic Versioning  . . . . . . . . . . . . . . .   6
     3.2.  Updating the YANG 1.1 Specifications  . . . . . . . . . .   9
     3.3.  The Derived Semantic Version  . . . . . . . . . . . . . .   9
   4.  Contributors  . . . . . . . . . . . . . . . . . . . . . . . .   9
   5.  Security Considerations . . . . . . . . . . . . . . . . . . .  10
   6.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  10
   7.  References  . . . . . . . . . . . . . . . . . . . . . . . . .  10
     7.1.  Normative References  . . . . . . . . . . . . . . . . . .  10
     7.2.  Informative References  . . . . . . . . . . . . . . . . .  10
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  11

1.  Introduction

   The YANG data modeling language [RFC7950] specifies strict rules for
   updating YANG modules (see section 11 "Updating a Module").  Citing a
   few of the relevant rules for this document:

   1.  "As experience is gained with a module, it may be desirable to
       revise that module.  However, changes to published modules are
       not allowed if they have any potential to cause interoperability
       problems between a client using an original specification and a
       server using an updated specification."

   2.  "Note that definitions contained in a module are available to be
       imported by any other module and are referenced in "import"
       statements via the module name.  Thus, a module name MUST NOT be
       changed.  Furthermore, the "namespace" statement MUST NOT be
       changed, since all XML elements are qualified by the namespace."

   3.  "Otherwise, if the semantics of any previous definition are
       changed (i.e., if a non-editorial change is made to any
       definition other than those specifically allowed above), then
       this MUST be achieved by a new definition with a new identifier."

   What are the consequences?

Claise, et al.             Expires May 3, 2018                  [Page 2]
Internet-Draft                YANG Catalog                  October 2017

   1.  Ideally, the YANG module names should not be changed due the
       importance of not changing the automation code in case of import
       statements or service composition at the orchestrator.

   2.  When the same YANG module name is kept, the new YANG module
       revision must always be updated in a backward-compatible way.

2.  The Problems

   This section lists a series of problems, hopefully listed in a
   logical order, which leads to the solution in the next section.

2.1.  Slow Standardization

   The conclusions drawn in the introduction lead to the logical
   conclusion that the standardized YANG modules have to be perfect day
   one (at least the structure), which in turns, might explain why all
   the IETF YANG modules take so long to standardize.  Shooting for
   perfection (at least the structure) is obviously a noble goal but, if
   the perfect standard comes too late, it doesn't help the industry.

2.2.  Some YANG Modules are Not Backward Compatible

   As we learn from our mistakes, we're going to face more and more non
   backward-compatible YANG modules.  An example is the YANG data model
   for L3VPN service delivery [RFC8049], which, based on implementation
   experience, must be updated in a non backward-compatible way with
   draft-wu-l3sm-rfc8049bis [I-D.wu-l3sm-rfc8049bis].

   While Standardized Development Organization YANG modules are
   obviously better for the industry, we must recognize that many YANG
   modules are actually generated YANG modules (for example, from
   internal database), also known as native YANG modules, or vendor
   modules [RFC8199].  From time to time, the new YANG modules are not
   backward-compatible.

   In such cases, it would be better to indicate how backward-compatible
   YANG modules are.

2.3.  A Zoo of YANG Modules

   Even if we focus on the IETF, we have to observe that many Standard
   Development Organizations, opensource fora, and vendors develop YANG
   modules develop YANG modules.  This should be considered a success
   for an IETF developed technoogy.  However, the operators are faced
   with this problem: how to select the YANG modules to take into
   account for their service developments.

Claise, et al.             Expires May 3, 2018                  [Page 3]
Internet-Draft                YANG Catalog                  October 2017

   The site <https://www.yangcatalog.org> (and the YANG catalog that it
   provides: YANG module for yangcatalog.org,
   [I-D.clacla-netmod-model-catalog]) is an attempt to become a
   reference for all YANG modules available in the industry, for both
   YANG developers to search on what exists already) and for operators
   (to discover the more mature YANG models to automate services).  This
   YANG catalog should not only contain pointers to the YANG modules
   themselves, but also contain metadata related to those YANG modules:
   What is the module type (service model or not?); what is the maturity
   level? (e.g., for the IETF: is this an RFC, a working group document
   or an individual draft?); is this module implemented?; who is the
   contact?; is there open-source code available?  And we expect many
   more in the future.  The industry has begun to understand that the
   metadata related to YANG models become equally important as the YANG
   models themselves.

   The yangcatalog.org instantiation of the catalog provides a means for
   module authors and vendors implementing modules to upload their
   metadata, which is then searchable via an API, as well as using a
   variety of web-based tools.  The instructions for contributing and
   searching for metadata can be found at <https://www.yangcatalog.org/
   contribe.php>.

   The issue is actually the number of YANG modules the operators are
   offered.  At the time of writing these lines, the number of unique
   YANG modules in the catalog is exactly 2596 (and the number keeps
   growing), while the IETF has standardized or is busy standardizing a
   small subset of those.  Therefore, it's important to distinguish the
   relevant YANG modules with the pack and to understand the
   relationship between the YANG modules.

2.4.  YANG Modules Obsolete Relationship

   So the operators use the yangcatalog.org to discover which YANG
   modules they can use NOW.  They base their selection not only on the
   YANG module content, but also on the related metadata.  When faced
   with the zoo of the YANG modules, it's difficult to understand the
   relationship between YANG modules.  As an example: how could an
   operator discovers that a YANG-MODULE-B obsoletes YANG-MODULE-A?
   Indeed, both have different YANG module names.  The only available
   information is an "obsolete" tag in the published RFC containing
   YANG-MODULE-B: this tag would point to YANG-MODULE-A.  In the world
   of automation, going through a published RFC as a level of
   indirection to understand the YANG module obsolete relationship is a
   non starter.  Food for thought: the IETF should stop thinking that
   the metric for success is an RFC number, as opposed to the contained
   YANG module(s).

Claise, et al.             Expires May 3, 2018                  [Page 4]
Internet-Draft                YANG Catalog                  October 2017

   We need an automatic way to discover that a YANG-MODULE-B obsoletes
   YANG-MODULE-A, so that YANG-MODULE-A should not be given any
   attention.

   The following example is not an automatic way.

       description
           "This YANG module defines a generic service configuration
           model for Layer 3 VPNs. This model is common across all
           vendor implementations. This obsoletes the RFC8049 YANG
           module, ietf-l3vpn-svc@2017-01-2";
       revision 2017-09-14 {
           description
           "First revision of RFC8049.";
           reference
           "RFC xxxx: YANG Data Model for L3VPN Service Delivery";

   Along the same lines, going through an offline tool such as the
   yangcatalog.org, in order to discover the obsolete relationship is a
   possible automatic way, but not ideal.

2.5.  YANG Module Transition Strategy

   Let's assume for a moment that we change the YANG module, with the
   specific example of the ietf-routing, which some propose to update to
   ietf-routing-2.

   Here are all the ietf-routing dependent YANG modules (those modules
   that depend on ietf-routing) <https://www.yangcatalog.org/yang-
   search/impact_analysis.php?modules[]=ietf-
   routing&recurse=0&rfcs=1&show_subm=1&show_dir=dependents>.  So many
   YANG modules.

   Let's look at the difference for ietf-routing-2:
   <https://www.yangcatalog.org/yang-search/
   impact_analysis.php?modules[]=ietf-routing-
   2&recurse=0&rfcs=1&show_subm=1&show_dir=dependents>.

   Changing the module name from ietf-routing to ietf-routing-2 implies
   that the we have to warn all draft authors of ietf-routing YANG
   dependent modules.  Firstly, to make sure they are aware of ietf-
   routing-2 (publishing a RFC8022bis mentioning in the module
   description that this module is not compatible with the NMDA
   architecture, and providing a pointer to ietf-routing-2 ... is not an
   automatic way... so barely useful).  And secondly, to ask them to
   change their import (or service composition) to ietf-routing-2.
   Hopefully, in the ietf-routing case, all dependent YANG modules are
   part of the IETF, so the communication is a manageable.

Claise, et al.             Expires May 3, 2018                  [Page 5]
Internet-Draft                YANG Catalog                  October 2017

   Changing the ietf-interfaces YANG module name would be a different
   challenge, as it's used throughout the industry:
   <https://www.yangcatalog.org/yang-search/
   impact_analysis.php?modules[]=ietf-
   interfaces&recurse=0&rfcs=1&show_subm=1&show_dir=dependents>

3.  The Solution

   The solution is composed of two mandator aspects, a semantic
   versioning YANG extension and an update to RFC7950.  An optional
   additional check, validating the semantic versioning from a syntact
   point of view, can either assist in determining the correct semantic
   versioning values, or can help in determining the values for YANG
   modules that don't support this extension.

3.1.  SEMVER Semantic Versioning

   The semantic versioning solution proposed here as already been
   proposed in [I-D.openconfig-netmod-model-catalog] (cut/paste here
   with the authors permission)which itself is based on
   [openconfigsemver].  The goal is to indicate the YANG module
   backwards (in)compatibility, following semver.org semantic versioning
   [semver]:

      MAJOR is incremented when the new version of the specification is
      incompatible with previous versions.

      MINOR is incremented when new functionality is added in a manner
      that is backward-compatible with previous versions.

      PATCH is incremented when bug fixes are made in a backward-
      compatible manner.

Claise, et al.             Expires May 3, 2018                  [Page 6]
Internet-Draft                YANG Catalog                  October 2017

    // extension statements
     extension openconfig-version {
       argument "semver" {
         yin-element false;
       }
       description
         "The OpenConfig version number for the module. This is
         expressed as a semantic version number of the form:
           x.y.z
         where:
           * x corresponds to the major version,
           * y corresponds to a minor version,
           * z corresponds to a patch version.
         This version corresponds to the model file within which it is
         defined, and does not cover the whole set of OpenConfig models.
         Where several modules are used to build up a single block of
         functionality, the same module version is specified across each
         file that makes up the module.

         A major version number of 0 indicates that this model is still
         in development (whether within OpenConfig or with industry
         partners), and is potentially subject to change.

         Following a release of major version 1, all modules will
         increment major revision number where backwards incompatible
         changes to the model are made.

         The minor version is changed when features are added to the
         model that do not impact current clients use of the model.

         The patch-level version is incremented when non-feature changes
         (such as bugfixes or clarifications to human-readable
         descriptions that do not impact model functionality) are made
         that maintain backwards compatibility.

         The version number is stored in the module meta-data.";
     }

   The extension would typically be used this way:

Claise, et al.             Expires May 3, 2018                  [Page 7]
Internet-Draft                YANG Catalog                  October 2017

       module yang-module-name {

         yang-version "1";
         namespace "name-space";
         prefix "prefix-name";

         import openconfig-extensions { prefix "oc-ext"; }

         organization
           "to be completed";

         contact
           "to be completed";

         description
           "to be completed";

         oc-ext:openconfig-version "1.1.2";

         revision 2017-10-30 {
           description
             "Change the module structure";
           reference "1.1.2";
         }

         revision 2017-07-30 {
           description
             "Fixed unprintable character";
           reference "0.1.2";
         }

         revision 2017-04-03 {
           description
             "Update copyright notice.";
           reference "0.1.1";
         }

         revision 2017-01-26 {
           description
             "Initial module for inet types";
           reference "0.1.0";
         }

         //YANG module definition starts here

   See also "Semantic Versioning and Structure for IETF Specifications"
   [I-D.claise-semver] for a mechanism to combine the semantic

Claise, et al.             Expires May 3, 2018                  [Page 8]
Internet-Draft                YANG Catalog                  October 2017

   versioning, the github tools, and a potential change to the IETF
   process.

3.2.  Updating the YANG 1.1 Specifications

   RFC 7950 section 11, must be updated to express:

   "As experience is gained with a module, it may be desirable to revise
   that module.  Changes to published modules are allowed, even if they
   have some potential to cause interoperability problems, at the
   condition that the semantic versioning change are clearly indicated
   based on the SEMVER YANG extension."

3.3.  The Derived Semantic Version

   The YANG catalog contains not only the most up-to-date YANG module
   revision of a given module, but keeps all previous revisions as well.
   With APIs in mind, it's important to understand whether different
   YANG module revisions are backward compatible (this is specifically
   imported for native YANG modules, i.e. the ones where generated-from
   = native), even for the YANG modules that don't support the YANG
   extension specified in this document.

   Two distinct leaves in the YANG module
   [I-D.clacla-netmod-model-catalog] contains this semver semantic:

      the semantic-version leaf contains the value reported as metadata
      by a specific YANG module.

      the derived-semantic-version leaf is established by examining the
      the YANG module themselves.  As such, only the YANG syntax, as
      opposed to the implementation changes that lead some some semantic
      changes.

   The derived-semantic-version is based on "pyang --check-update-from",
   which checks the backward compatibility from a syntax point of view.

   Note that the absolute numbers in the semantic-version and derived-
   semantic-version are actually meaningless: the difference between two
   YANG module semver fields should be looked at.

4.  Contributors

   Anees Shaikh, Google

Claise, et al.             Expires May 3, 2018                  [Page 9]
Internet-Draft                YANG Catalog                  October 2017

5.  Security Considerations

   To be completed

6.  IANA Considerations

   No IANA action is requested.

7.  References

7.1.  Normative References

   [RFC7950]  Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
              RFC 7950, DOI 10.17487/RFC7950, August 2016,
              <https://www.rfc-editor.org/info/rfc7950>.

7.2.  Informative References

   [I-D.clacla-netmod-model-catalog]
              Clarke, J. and B. Claise, "YANG module for
              yangcatalog.org", draft-clacla-netmod-model-catalog-02
              (work in progress), October 2017.

   [I-D.claise-semver]
              Claise, B., Barnes, R., and J. Clarke, "Semantic
              Versioning and Structure for IETF Specifications", draft-
              claise-semver-01 (work in progress), July 2017.

   [I-D.openconfig-netmod-model-catalog]
              Shaikh, A., Shakir, R., and K. D'Souza, "Catalog and
              registry for YANG models", draft-openconfig-netmod-model-
              catalog-02 (work in progress), March 2017.

   [I-D.wu-l3sm-rfc8049bis]
              Wu, Q., Litkowski, S., Tomotaki, L., and K. Ogaki, "YANG
              Data Model for L3VPN Service Delivery", draft-wu-l3sm-
              rfc8049bis-09 (work in progress), October 2017.

   [openconfigsemver]
              "Semantic Versioning for Openconfig Models",
              <http://www.openconfig.net/docs/semver/>.

   [RFC8049]  Litkowski, S., Tomotaki, L., and K. Ogaki, "YANG Data
              Model for L3VPN Service Delivery", RFC 8049,
              DOI 10.17487/RFC8049, February 2017,
              <https://www.rfc-editor.org/info/rfc8049>.

Claise, et al.             Expires May 3, 2018                 [Page 10]
Internet-Draft                YANG Catalog                  October 2017

   [RFC8199]  Bogdanovic, D., Claise, B., and C. Moberg, "YANG Module
              Classification", RFC 8199, DOI 10.17487/RFC8199, July
              2017, <https://www.rfc-editor.org/info/rfc8199>.

   [semver]   "Semantic Versioning 2.0.0", <https://www.semver.org>.

Authors' Addresses

   Benoit Claise
   Cisco Systems, Inc.
   De Kleetlaan 6a b1
   1831 Diegem
   Belgium

   Phone: +32 2 704 5622
   Email: bclaise@cisco.com

   Joe Clarke
   Cisco Systems, Inc.
   7200-12 Kit Creek Rd
   Research Triangle Park, North Carolina
   United States of America

   Phone: +1-919-392-2867
   Email: jclarke@cisco.com

   Rob Shakir
   Google
   1600 Amphitheatre Pkwy
   Mountain View, CA  94043
   United States of America

   Email: rjs@rob.sh

   Kevin D'Souza
   AT&T
   200 S. Laurel Ave
   Middletown, NJ
   United States of America

   Email: kd6913@att.com

Claise, et al.             Expires May 3, 2018                 [Page 11]