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.
4.23. Operational State
The management of YANG operational state has been refined 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
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.
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
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.
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.
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. 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.
(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
}
}
Example: Convert an old Non-NMDA Module
Do not remove non-complaint objects from existing modules. Instead,
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-";
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
}
}
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
>
>
_______________________________________________
netmod mailing list
[email protected]
https://www.ietf.org/mailman/listinfo/netmod
