On Mon, Aug 28, 2017 at 3:11 AM, Juergen Schoenwaelder <
[email protected]> 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 <[email protected]>
> wrote:
> >
> > >
> > >
> > > On Fri, Aug 25, 2017 at 12:11 PM, Kent Watsen <[email protected]>
> wrote:
> > >
> > >>
> > >>
> > >>
> > >>
> > >> On 8/25/17, 2:21 PM, "Andy Bierman" <[email protected]> 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: +49 421 200 3587 Campus Ring 1 | 28759 Bremen | Germany
> Fax: +49 421 200 3103 <http://www.jacobs-university.de/>
>
_______________________________________________
netmod mailing list
[email protected]
https://www.ietf.org/mailman/listinfo/netmod
