Re: [netmod] rfc6087bis S4.23 replacement text

[Andy Bierman <[e-mail]>]

On Mon, Aug 28, 2017 at 3:11 AM, Juergen Schoenwaelder <
[e-mail]> wrote:

> On Sun, Aug 27, 2017 at 06:08:28PM -0700, Andy Bierman wrote:
> > Hi,
> >
> > Here is the proposed rewrite of 4.23.
> > I changed a few details in the temporary non-NMDA procedure.
> > This module cannot duplicate the NMDA module as read-only.
> > Only the top-level config=false nodes that would have been exposed
> pre-NMDA
> > need to be present.
>
> Thanks for taking the time to produce detailed text. Some comments
> inline.
>
> > 4.23.  Operational State
> >
> >    The management of YANG operational state has been refined over time.
>
> I think you mean:
>
>   The modeling of operational state with YANG has been refied over time.
>
>

fixed



> >    At first, only data that has a "config" statement value of "false"
> >    was considered to be operational state.  This data was not considered
> >    to be part of any datastore, which made YANG XPath definition much
> >    more complicated.
> >
> >    YANG operational state is now modeled according to new NMDA, and is
>
> I think we do not have the term 'YANG operational state'. Hence:
>
>   Operational state is now modeled using YANG according to ...
>
>
fixed



> >    now conceptually contained in the operational datastore, which also
> >    includes the operational values of configuration data.  There is no
> >    longer any need to duplicate data structures to provide separate
> >    configuration and operational data sections.
> >
> >    This section describes some data modeling issues related to
> >    operational state, and guidelines for transitioning YANG data model
> >    design to be NMDA-compatible.
> >
> > 4.23.1.  Combining Operational State and Configuration Data
> >
> >    If possible, operational state SHOULD be combined with its associated
> >    configuration data.  This prevents duplication of key leafs and
> >    ancestor nodes.  It also prevents race conditions for retrieval of
> >    dynamic entries, and allows configuration and operational state to be
> >    retrieved together with minimal message overhead.
> >
> >    Not NMDA-Compliant:
> >
> >       container foo {
> >         ...
> >       }
> >
> >       container foo-state {
> >         config false;
> >         ...
> >       }
> >
> >    NMDA-Compliant:
> >
> >       container foo {
> >         ...
> >         // contains config=true and config=false nodes that have
> >         // no corresponding config=true object (e.g., counters)
> >       }
> >
> > 4.23.2.  Representing Operational Values of Configuration Data
> >
> >    If possible the same data type SHOULD be used to represent the
> >    configured value and the operational value, for a given leaf or leaf-
> >    list object.
> >
> >    Sometimes the configured value set is different than the operational
> >    value set for that object.  For example, the "admin-state" and
> >    "oper-state" leafs in [RFC7223].  In this case a separate object MAY
> >    be used to represent the configured and operational values.
> >
> >    Sometimes the list keys are not identical for configuration data and
> >    the corresponding operational state.  In this case separate lists MAY
> >    be used to represent the configured and operational values.
> >
> >    If it is not possible to combine configuration and operational state,
> >    then the keys used to represent list entries SHOULD be the same type.
> >    The "leafref" data type SHOULD be used in operational state for key
> >    leafs that have corresponding configuration instances.  The
> >    "require-instance" statement MAY be set to "false" (in YANG 1.1
> >    modules only) to indicate instances are allowed in the operational
> >    state that do not exist in the associated configuration data.
> >
> >    If all the data model properties are aligned between configuration
> >    data and operational state, then it can be useful to define the
> >    configuration parameters within a grouping, and then replicate that
> >    grouping within the operational state portion of the data model.
> >
> >        grouping parms {
> >           // do not use config-stmt in any of the nodes
> >           // placed in this grouping
> >        }
> >
> >        container bar { // bar config can exist without bar-state
> >          config true;
> >          uses parms;
> >        }
> >
> >        container bar-state {  // bar-state can exist without bar
> >          status deprecated;
> >          config false;
> >          uses parms;
> >        }
> >
> >    The need to replicate objects or define different operational state
> >    objects depends on the data model.  It is not possible to define one
> >    approach that will be optimal for all data models.
>
> Well, having bar (config true) and bar-state (config false) is what
> NMDA tries to avoid. Even in NMDA, bar can exist in <operational>
> without having <bar> in say <running>. (Example, no IP addresses
> statically configured but IP addresses learned from DHCP or created by
> the system.) I am not sure the discussion starting with "If all the
> data model properties" is needed.
>
>
removed "If all the data" .. through groupings example



> >    Designers SHOULD describe and justify any NMDA exceptions in detail,
> >    such as the use of separate subtrees and/or separate leafs.  The
> >    "description" statements for both the configuration and the
> >    operational state SHOULD be used for this purpose.
> >
> > 4.23.3.  NMDA Transition Guidelines
> >
> >    YANG modules SHOULD be designed assuming they will be used on servers
> >    supporting the operational datastore.  With this in mind, YANG
>
> It is actually called the 'operational state datastore'.
>


Except that we never use that term.
It is always called operational datastore when we talk about it in meetings.
Hence, the new NMDA terms section:

 ** NMDA Terms

The following terms are defined in the
Network Management Datastore Architecture
(NMDA) ^I-D.ietf-netmod-revised-datastores^.
and are not redefined here:

- configuration
- conventional configuration datastore (also called conventional datastore)
- datastore
- operational state
- operational state datastore (also called operational datastore)

IMO these alternates should be put in the RD draft since they reflect the
terms we actually use.


> >    modules SHOULD define config "false" wherever they make sense to the
> >    data model.  Config "false" nodes SHOULD NOT be defined to provide
> >    the operational value for configuration nodes, except when the value
> >    space of a configured and operational values may differ, in which
> >    case a distinct config "false" node SHOULD be defined to hold the
> >    operational value for the configured node.
>
> Perhaps the text needs to say somewhere very clearly that the
> operationally used values of configuration objects are part of the
> operational state datastore and hence config false nodes SHOULD NOT be
> defined to provide the operational value for configuration nodes...
>


I think the text from Lou is OK.


>
> >    The following guidelines are meant to help modelers develop YANG
> >    models that will maximize the utility of the model with both current
> >    and new implementations.
>
> Do we generally talk about YANG modules or YANG models in the guidelines
> document? Are these used as synonyms? Just wondering...
>


changed models to modules. -- here and several other places




>
> >    New models and models that are not concerned with the operational
> >    state of configuration information SHOULD immediately be structured
> >    to be NMDA-compatible, as described in Section 4.23.1.
> >
> >    The remaining are options that MAY be followed during the time that
> >    NMDA mechanisms are being defined.
> >
> >    (a) Models that require immediate support for the NMDA "origin" meta
> >    data, such as "in use" and "system created" information, SHOULD be
> >    structured for NMDA.
>
> Not sure I parsed this correctly. What does 'in use' and 'system
> created' information refer to? I think in general models should follow
> NMDA (once it went through the approval process), no?
>

This is from Lou. I just pasted in his text here, but added the origin
metadata part.
See new fix below.



>
> >    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 appendix.  The use of the non-
> >    NMDA model will allow temporary bridging of the time period until
> >    NMDA implementations are available.
>
> I do not think that it is always a SHOULD to have a non-NMDA model but
> then I did not understand the condition of (a). RFC 8194 for instance
> is NMDA compatible and this is good enough. If an implementation needs
> to expose applied configuration, it will have to implement NMDA.
>

Please do implement it -- especially the client-side, which got much more
complex
because of NMDA.

I think the first sentence refers to the temporary non-NMDA module.

NEW:

(a) Modules that require immediate support for the NMDA features
SHOULD be structured for NMDA.  A temporary 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.



> >    (b) 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.
> >
> >    (c) 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.
> >
> > 4.23.3.1.  Temporary non-NMDA Modules
> >
> >    A temporary non-NMDA module allows a non-NMDA aware client to access
> >    operational state from an NMDA-compliant server.  It contains the
> >    top-level config=false data nodes that would have been defined in a
> >    legacy YANG module (before NMDA).
> >
> >    A server that needs to support both NMDA and non-NMDA clients can
> >    advertise both the new NMDA module and the temporary non-NMDA module.
> >    A non-NMDA client can use separate "foo" and "foo-state" subtrees,
> >    except the "foo-state" subtree is located in a different (temporary)
> >    module.  The NMDA module can be used by a non-NMDA client to access
> >    the conventional datastores, and the deprecated <get> operation to
> >    access nested config=false data nodes.
> >
> >    To create the temporary non-NMDA model from an NMDA model, the
> >    following steps can be taken:
> >
> >    o  Change the module name by appending "-state" to the original
> >       module name
> >
> >    o  Change the namespace by appending "-state" to the original
> >       namespace value
> >
> >    o  Change the prefix by appending "-s" to the original prefix value
> >
> >    o  Add an import to the original module (e.g., for typedef
> >       definitions)
> >
> >    o  Retain or create only the top-level nodes that have a "config"
> >       statement value "false".  These subtrees represent config=false
> >       data nodes that were combined into the configuration subtree, and
> >       therefore not available to non-NMDA aware clients.  Set the
> >       "status" statement to "deprecated" for each new node.
> >
> >    o  The module description SHOULD clearly identify the module as a
> >       temporary non-NMDA module
> >
> > 4.23.3.2.  NMDA Module Examples
> >
> >    Example: Create a New Module
> >
> >    Create an NMDA-compliant module, using combined configuration and
> >    state subtrees, whenever possible.
> >
> >      module example-foo {
> >        namespace "urn:example.com:params:xml:ns:yang:example-foo";
> >        prefix "foo-";
> >
> >        container foo {
> >          // configuration data child nodes
> >          // operational value in operational datastore only
> >          // may contain config=false nodes as needed
> >        }
> >     }
>
> Why would the prefix be "foo-" and not just "foo"?
>
> >    Example: Convert an old Non-NMDA Module
> >
> >    Do not remove non-complaint objects from existing modules.  Instead,
>
> compliant
>
>
fixed



> >    change the status to "deprecated".  At some point, usually after 1
> >    year, the status MAY be changed to "obsolete".
> >
> >    Old Module:
> >
> >      module example-foo {
> >        namespace "urn:example.com:params:xml:ns:yang:example-foo";
> >        prefix "foo";
> >
> >        container foo {
> >          // configuration data child nodes
> >        }
> >
> >        container foo-state {
> >          config false;
> >          // operational state child nodes
> >        }
> >     }
> >
> >    Converted NMDA Module:
> >
> >      module example-foo {
> >        namespace "urn:example.com:params:xml:ns:yang:example-foo";
> >        prefix "foo-";
>
> "foo-" vs "foo"
>

fixed


>
> >        container foo {
> >          // configuration data child nodes
> >          // operational value in operational datastore only
> >          // may contain config=false nodes as needed
> >          // will contain any data nodes from old foo-state
> >        }
> >
> >        // keep original foo-state but change status to deprecated
> >        container foo-state {
> >          config false;
> >          status deprecated;
> >          // operational state child nodes
> >        }
> >     }
> >
> >    Example: Create a Temporary NMDA Module:
> >
> >    Create a new module that contains the top-level operational state
> >    data nodes that would have been available before they were combined
> >    with configuration data nodes (to be NMDA compliant).
> >
> >      module example-foo-state {
> >        namespace "urn:example.com:params:xml:ns:yang:example-foo-state";
> >        prefix "foo-s";
> >
> >        // import new or converted module; not used in this example
> >        import example-foo { prefix foo; }
> >
> >        container foo-state {
> >          config false;
> >          status deprecated;
> >          // operational state child nodes
> >        }
> >     }
>
> Perhaps put the examples in separate sections 4.23.3.2, 4.23.3.3,
> 4.23.3.4 so that they are more clearly separated?
>
>
OK


> >
> > Andy
> >
>



Andy




> >
> >
> > On Fri, Aug 25, 2017 at 12:31 PM, Andy Bierman <[e-mail]>
> wrote:
> >
> > >
> > >
> > > On Fri, Aug 25, 2017 at 12:11 PM, Kent Watsen <[e-mail]>
> wrote:
> > >
> > >>
> > >>
> > >>
> > >>
> > >> On 8/25/17, 2:21 PM, "Andy Bierman" <[e-mail]> wrote:
> > >>
> > >>
> > >>
> > >> > Obviously NMDA cannot be used for objects where the configuration
> value
> > >> set
> > >>
> > >> > and the operstate value set differ, such as with the interface
> > >> admin-status/oper-status.
> > >>
> > >> > Do you want a sentence added that says to use config false leafs as
> > >> needed within the
> > >>
> > >> > configuration entry? A sentence that says operational data is
> embedded
> > >> in the
> > >>
> > >> > configuration entry?
> > >>
> > >>
> > >>
> > >> Yes, and any other general guidelines around using config false.   The
> > >> text I posted
> > >>
> > >> when starting this thread had some of that.  The original RFC6087 text
> > >> might have
> > >>
> > >> some more.
> > >>
> > >>
> > >>
> > >
> > > OK -- I will work on adding in text from -12, your text, and Lou's
> text.
> > >
> > >
> > >>
> > >> > 6087bis was supposed to be a minor update, not a living draft that
> > >> doubles
> > >>
> > >> > as a YANG tutorial and ongoing issues list.
> > >>
> > >>
> > >>
> > >>  ;)
> > >>
> > >>
> > >>
> > >> As much as I like RFCs, I think this content would be better served
> by a
> > >> Wiki.   If
> > >>
> > >> we were starting for scratch (no RFC6087), then that might make sense
> > >> but, given
> > >>
> > >> where we are, not so much.  So, I guess we're committed to frequent
> > >> updates on this
> > >>
> > >> document until YANG settles down.
> > >>
> > >>
> > >>
> > >
> > > It is better to have as few moving targets (and normative references)
> as
> > > possible.
> > > YANG modules in an RFC have to conform to a specific version of the
> YANG
> > > guidelines.
> > >
> > >
> > >>
> > >>
> > >> Kent // contributor
> > >>
> > >>
> > >>
> > >>
> > >>
> > >
> > > Andy
> > >
> > >
>
> --
> Juergen Schoenwaelder           Jacobs University Bremen gGmbH
> Phone: [phone]         Campus Ring 1 | 28759 Bremen | Germany
> Fax:   [phone]         <http://www.jacobs-university.de/>
>