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.
> 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 ...
> 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.
> 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'.
> 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...
> 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...
> 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?
> 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.
> (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
> 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"
> 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?
>
> 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
