Network Working Group                                       M. Bjorklund
Internet-Draft                                            Tail-f Systems
Intended status: Informational                          J. Schoenwaelder
Expires: November 10, 2017                             Jacobs University
                                                               P. Shafer
                                                               K. Watsen
                                                        Juniper Networks
                                                               R. Wilton
                                                           Cisco Systems
                                                             May 9, 2017


               Guidelines for YANG Module Authors (NMDA)
                     draft-dsdt-nmda-guidelines-01

Abstract

   The "Network Management Datastore Architecture" (NMDA) adds the
   ability to inspect the current operational values for configuration,
   allowing clients to use identical paths for retrieving the configured
   values and the operational values.  This change will simplify models
   and help modelers, but will create a period of transition as NMDA
   becomes a standard and is widely implemented.  During that interim,
   the guidelines given in this document should help modelers find an
   optimal path forward.

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 http://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 November 10, 2017.

Copyright Notice

   Copyright (c) 2017 IETF Trust and the persons identified as the
   document authors.  All rights reserved.




Bjorklund, et al.       Expires November 10, 2017               [Page 1]


Internet-Draft                                                  May 2017


   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (http://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
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
     1.1.  Keywords  . . . . . . . . . . . . . . . . . . . . . . . .   2
     1.2.  Terminology . . . . . . . . . . . . . . . . . . . . . . .   2
     1.3.  Executive Summary . . . . . . . . . . . . . . . . . . . .   3
     1.4.  Background  . . . . . . . . . . . . . . . . . . . . . . .   3
     1.5.  Network Management Datastores Architecture  . . . . . . .   5
   2.  Guidelines for YANG Modelers  . . . . . . . . . . . . . . . .   5
   3.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   8
   4.  Security Considerations . . . . . . . . . . . . . . . . . . .   8
   5.  Informative References  . . . . . . . . . . . . . . . . . . .   8
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .   9

1.  Introduction

   This document provides advice and guidelines to help modelers plan
   for the emerging "Network Management Datastore Architecture" (NMDA)
   [I-D.ietf-netmod-revised-datastores].  This architecture provides an
   architectural framework for datastores as they are used by network
   management protocols such as NETCONF [RFC6241], RESTCONF [RFC8040]
   and the YANG [RFC7950] data modeling language.  Datastores are a
   fundamental concept binding network management data models to network
   management protocols, enabling data models to be written in a network
   management protocol agnostic way.

1.1.  Keywords

   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].

1.2.  Terminology

   This document uses the terminology defined by the NMDA
   [I-D.ietf-netmod-revised-datastores].




Bjorklund, et al.       Expires November 10, 2017               [Page 2]


Internet-Draft                                                  May 2017


1.3.  Executive Summary

   The Network Management Datastore Architecture (NMDA) addresses the so
   called "OpState problem" that has been the subject of much discussion
   in the IETF.  NMDA is still in development and there will be a
   transition period before NMDA solutions are universally available.

   These guidelines are aimed to enable the creation of models that can
   take advantage of the NMDA, while pragmatically allowing those models
   to be used with the existing network configuration protocol
   implementations.

   It is the strong recommendation that models SHOULD move as quickly as
   possible to the NMDA.  The specific approach to be taken for models
   being developed now and during the NMDA transition period should be
   based on both the expected usage and the maturity of the data model.

   1.  New models and models that are not concerned with the operational
       state of configuration information SHOULD immediately be
       structured to be NMDA-compatible.

   2.  Models that require immediate support for "in use" and "system
       created" information SHOULD be structured for NMDA.  A non-NMDA
       version of these models SHOULD also be published, using either an
       existing model or a model created either by hand or with suitable
       tools that support current modeling strategies.  Both the NMDA
       and the non-NMDA modules SHOULD be published in the same
       document, with NMDA modules in the document main body and the
       non-NMDA modules in a non-normative appendix.  The use of the
       non-NMDA model will allow temporary bridging of the time period
       until NMDA implementations are available.

   Additional details on these guidelines can be found below, notably in
   Section 2.

1.4.  Background

   NETCONF ([RFC6241]) was developed with a focus on configuration data,
   and has unfortunate gaps in its treatment of operational data.  The
   <get-config> operation can return configuration data (defined as
   nodes with "config true") stored in <running>.  This data is
   typically the only data created by CLI users and NETCONF clients.
   The <get> operation is defined as returning all the data on the
   device, including the contents of <running>, as well as any
   operational state data.  While the NETCONF design envisioned models
   merging "config false" nodes with the contents of running, there are
   two issues involved.




Bjorklund, et al.       Expires November 10, 2017               [Page 3]


Internet-Draft                                                  May 2017


   First, the desire of clients to see the true operational ("in use")
   value of configuration data resulted in the need for data models to
   have two distinct leafs, one to show the configured value and the
   other to show the operational value.  An example would be the speed
   of an interface, where the configured value may not be the value that
   is currently used.

   Second, devices often have "system created" resources that exist as
   operational data even when there is no corresponding configuration
   data.  An example would be built-in networking interfaces that always
   appear in operational data.

   A similar situation to the second issue discussed above exists while
   the device is processing configuration data changes.  When
   configuration data is deleted, the operational data will continue to
   exist during the time period in which the device is releasing
   resources associated with the data.  An example would be deleting a
   BGP peer, where the peer continues to exist in operational data until
   the connection is closed and any other resources are released.

   To address these issues without requiring a protocol modification,
   two distinct strategies have been adopted in YANG model design:

   The first strategy makes two distinct top-level containers, one for
   configuration and one for state.  These are sometimes referred to as
   "/foo" and "/foo-state".  An example would be the interface model
   defined in [RFC7223].  These models require two completely distinct
   set of nodes, with repetition of both the interior containers, lists,
   and key nodes, but also repetition of many other nodes to allow
   visibility of the operational values of configured nodes.  This leads
   to over-use of YANG groupings in ways that affect the readability of
   the models, as well as creating opportunities to incorrectly mirror
   the model's hierarchies.  Also this "stitching together" of data from
   the two trees is merely a convention, not a formal relationship.

   The second strategy uses two sibling containers, named "config" and
   "state", placed deeper within the model node hierarchy.  The "config"
   container holds the configured values, while the "state" container
   holds the operational values.  The duplication of interior nodes in
   the hierarchies is removed, but the duplication of leafs representing
   configuration remains.  Groupings can be used to avoid the repetition
   of the leafs in the YANG file, but at the expense of readability.  In
   addition, this strategy does not handle the existence of operational
   data for which there is no configuration data, such as the system-
   created data and deleted peers scenarios discussed above.






Bjorklund, et al.       Expires November 10, 2017               [Page 4]


Internet-Draft                                                  May 2017


1.5.  Network Management Datastores Architecture

   The Network Management Datastores Architecture (NMDA) addresses the
   problems mentioned above by creating an architectural framework which
   includes a distinct datastore for operational data, called
   <operational>.  This datastore is defined as containing both config
   true and config false nodes, with the formal understanding that the
   "in use" values are returned for the config true nodes.  This allows
   modelers to use a single hierarchy for all configuration and
   operational data, which both improves readability and reduces the
   possibility of modeling inconsistencies that might impact
   programmatic access.

   In addition, another datastore named <intended> is defined to provide
   a complete view of the configuration data, even in the presence of
   device-specific features that expand or remove configuration data.
   While such mechanisms are currently non-standard, the NMDA recognizes
   they exist and need to be handled appropriately.  In the future, such
   mechanisms may become standardized.

   The NMDA allows the deprecation of NETCONF's <get> operation,
   removing the source of these issues.  The new operations <get-data>
   and <edit-data> will support a parameter indicating the target
   datastore.  Similar changes are planned for RESTCONF ([RFC8040]).

2.  Guidelines for YANG Modelers

   The following guidelines are meant to help modelers develop YANG
   models that will maximize the utility of the model with both current
   implementations and NMDA-capable implementations.  Any questions
   regarding these guidelines can be sent to yang-doctors@ietf.org.

   The direction taken should be based on both the maturity of the data
   model, along with the number of concrete implementations of the
   model.  The intent is not to destabilize the IETF modeling community,
   but to create models that can take advantage of the NMDA, while
   pragmatically allowing those models to be used with the existing
   network configuration protocol implementations.

   It is the strong recommendation that models SHOULD move as quickly as
   possible to the NMDA.  This is key to the future of these models.
   The NETMOD WG will rework existing models to this architecture.
   Given the permanence and gravity of work published by the IETF,
   creating future-proof data models is vital.

   The two current strategies ("/foo-state" and "config"/"state"
   containers) mix data retrieval details into the data model,
   complicating the models and impairing their readability.  Rather than



Bjorklund, et al.       Expires November 10, 2017               [Page 5]


Internet-Draft                                                  May 2017


   maintain these details inside the data model, models can be post-
   processed to add this derivative information, either manually or
   using tools.

   Tools can automatically produce the required derived modules.  The
   suggested approach is to produce a "state" version of the module with
   a distinct namespace, rather than using the "/foo-state" top-level
   container.  Since the contents are identical, constraints in the data
   model such as "must" statements should not need to change.  Only the
   model name, namespace, and prefix should need to change.  This
   simplifies the tooling needed to generate the derived model, as well
   as reducing changes needed in client applications when transitioning
   to the NMDA model.

   These derived models use distinct module names and namespaces,
   allowing servers to announce their support for the base or derived
   models.

   Consider the following trivial model:

       module example-thermostat {
           namespace "tag:ietf:example:thermostat";
           prefix "thermo";

           container thermostat {
               leaf high-temperature {
                   description "High temperature threshold";
                   type int;
               }
               leaf low-temperature {
                   description "Low temperature threshold";
                   type int;
               }
               leaf current-temperature {
                   description "Current temperature reading";
                   type int;
                   config false;
               }
           }
       }

   In the derived model, the contents mirror the NMDA data model, but
   are marked as "config false", and the module name and namespace
   values have a "-state" suffix:







Bjorklund, et al.       Expires November 10, 2017               [Page 6]


Internet-Draft                                                  May 2017


       module example-thermostat-state {
           namespace "tag:ietf:example:thermostat-state";
           prefix "thermo-state";

           container thermostat {
               config false;
               leaf high-temperature {
                   description "High temperature threshold";
                   type int;
               }
               leaf low-temperature {
                   description "Low temperature threshold";
                   type int;
               }
               leaf current-temperature {
                   description "Current temperature reading";
                   type int;
               }
           }
       }

   By adopting a tools-based solution for supporting models that are
   currently under development, models can be quickly restructured to be
   NMDA-compatible while giving continuity to their community of
   developers.  When NMDA-capable implementations become available, the
   base data models can be used directly.

   Modelers and reviewers can view the simple data model, published in
   the body of document.  Tools can generate any required derived
   models, and those models can be published in a non-normative appendix
   to allow interoperability.

   It is critical to consider the following guidelines, understanding
   that our goal is to make models that will see continued use in the
   long term, balancing short term needs against a desire for
   consistent, usable models in the future:

   (a) New models and models that are not concerned with the operational
   state of configuration information SHOULD immediately be structured
   to be NMDA-compatible.

   (b) Models that require immediate support for "in use" and "system
   created" information SHOULD be structured for NMDA.  A non-NMDA
   version of these models SHOULD exist, either an existing model or a
   model created either by hand or with suitable tools that mirror the
   current modeling strategies.  Both the NMDA and the non-NMDA modules
   SHOULD be published in the same document, with NMDA modules in the
   document main body and the non-NMDA modules in a non-normative



Bjorklund, et al.       Expires November 10, 2017               [Page 7]


Internet-Draft                                                  May 2017


   appendix.  The use of the non-NMDA model will allow temporary
   bridging of the time period until NMDA implementations are available.

   (c) For published models, the model should be republished with an
   NMDA-compatible structure, deprecating non-NMDA constructs.  For
   example, the "ietf-interfaces" model in [RFC7223] will be
   restructured as an NMDA-compatible model.  The "/interfaces-state"
   hierarchy will be marked "status deprecated".  Models that mark their
   "/foo-state" hierarchy with "status deprecated" will allow NMDA-
   capable implementations to avoid the cost of duplicating the state
   nodes, while enabling non-NMDA-capable implementations to utilize
   them for access to the operational values.

   (d) For models that augment models which have not been structured
   with the NMDA, the modeler will have to consider the structure of the
   base model and the guidelines listed above.  Where possible, such
   models should move to new revisions of the base model that are NMDA-
   compatible.  When that is not possible, augmenting "state" containers
   SHOULD be avoided, with the expectation that the base model will be
   re-released with the state containers marked as deprecated.  It is
   RECOMMENDED to augment only the "/foo" hierarchy of the base model.
   Where this recommendation cannot be followed, then any new "state"
   elements SHOULD be included in their own module.

3.  IANA Considerations

   This document has no actions for IANA.

4.  Security Considerations

   This document has no security considerations.

5.  Informative References

   [I-D.ietf-netmod-revised-datastores]
              Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K.,
              and R. Wilton, "Network Management Datastore
              Architecture", draft-ietf-netmod-revised-datastores-01
              (work in progress), March 2017.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/
              RFC2119, March 1997,
              <http://www.rfc-editor.org/info/rfc2119>.







Bjorklund, et al.       Expires November 10, 2017               [Page 8]


Internet-Draft                                                  May 2017


   [RFC6241]  Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
              and A. Bierman, Ed., "Network Configuration Protocol
              (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011,
              <http://www.rfc-editor.org/info/rfc6241>.

   [RFC7223]  Bjorklund, M., "A YANG Data Model for Interface
              Management", RFC 7223, DOI 10.17487/RFC7223, May 2014,
              <http://www.rfc-editor.org/info/rfc7223>.

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

   [RFC8040]  Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
              Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
              <http://www.rfc-editor.org/info/rfc8040>.

Authors' Addresses

   Martin Bjorklund
   Tail-f Systems

   Email: mbj@tail-f.com


   Juergen Schoenwaelder
   Jacobs University

   Email: j.schoenwaelder@jacobs-university.de


   Phil Shafer
   Juniper Networks

   Email: phil@juniper.net


   Kent Watsen
   Juniper Networks

   Email: kwatsen@juniper.net


   Rob Wilton
   Cisco Systems

   Email: rwilton@cisco.com




Bjorklund, et al.       Expires November 10, 2017               [Page 9]