Skip to content

NMDA Modelling FAQ

Jump to bottom
Robert Wilton edited this page Sep 7, 2017 · 3 revisions

This page provides answers for common questions related to modelling YANG in an NMDA compliant way.

Table of Contents

  1. Do all top level containers in a NMDA compliant module have to be "config true" containers?
  2. Is an new NMDA compliant module allowed to have a top level "-state" container?
  3. When should a transitional "foo-state" module be generate for NMDA compliant module "foo"?
  4. How do I generate the transitional "foo-state" module for NMDA compliant module "foo"?

Questions

Q 1. Do all top level containers in a NMDA compliant module have to be "config true" containers?

No. If all of the descendant content in a container is currently only operational state data then the entire container hierarchy can be config false.

However, the names of the structural elements (containers, lists, etc) SHOULD be designed as such that the names are still appropriate if they were modified to also hold some configuration in future. The YANG 1.1 module update rules allow a "config false" schema node to be converted to "config true" as a backwards compatible revision update.

Q 2. Is an new NMDA compliant module allowed to have a top level "-state" container?

No, there should be no top level container with a name that ends with "-state", or their name indicates that they only hold state nodes. This answer still applies even if a container only holds operational state information. Also see Question 1

Top level containers shouldn't be called "-state" because either:

  1. they already contain config nodes, in which case they are misnamed, or
  2. they might be revised to contain config nodes in the future, in which case they would end up being misnamed.

The suffix "-state" doesn't generally provide any useful extra information.

Lower down the schema tree, using "state" or "*-state" is OK if it can be known that the leaf/container will always only contain state and never potentially hold configurable nodes in future. Hence it is necessary to be very careful here.

For example, If someone designed a new routing protocol, then for version 1 there might be no explicit neighbor configuration, and hence all of the neighbor information might be put into a container call neighbor-state. However, if a version 2 of that protocol (or vendor extensions) wants to add some per neighbor configuration then the original neighobr-state container name would make it problematic to add new configuration nodes below it. In general, avoiding "-state" in the name of containers seems to be good common sense.

A similar argument applies to using "config" or "-config" in the name of containers, and they should also be avoided if possible.

Q 3. When should a transitional "foo-state" module be generate for NMDA compliant module "foo"?

The "-state" module SHOULD only be generated when it is required, or expected to be required.

The "-state" module is only useful for devices that are not NMDA compatible, and hence do not expose the operational state datastore. The value and meaning of the nodes in the generated "-state" modules is the same as the data nodes held in the operational state datastore of an NMDA compliant server. Even then a generated "-state" module is only useful under the following two scenarios:

  1. The applied configuration is reasonably likely to diverge from the intended configuration and that needs to be exposed on non NMDA compliant devices.
  2. The configured objects may be created by the system without configuration. System created interfaces is a classic example of this scenario, which is why the "interfaces" and "interfaces-state" top level split containers were originally created.

If neither of the two scenarios above apply, then a transitional "foo-state" module does not need to be generated.

Q 4. How do I generate the transitional "foo-state" module for NMDA compliant module "foo"?

The transitional "-state" module can be constructed by hand by making a copy of the original NMDA compliant module in a new YANG file with "-state" appended to the module name. The following changes are then applied to the new "foo-state" file:

  1. The module is renamed by appending "-state" to the original module's name.
  2. The namespace is renamed by appending "-state" to the original namespace value.
  3. The module prefix is renamed by appending "-s" to the original prefix value.
  4. Add an import to the original NMDA module, using the prefix that it defined (e.g. for typedef and identity definitions defined in the original NMDA module).
  5. All top-level schema nodes, and all grouping definitions, are updated to have a "config" statement of value "false".
  6. All top level typedef, identity, extension, or rpc YANG statements are deleted, the ones from the NMDA module are used instead.
  7. Any identifier references to unprefixed typedefs or identifiers defined in the NMDA module are updated to explicitly use the NMDA module prefix. Specifically the arguments to type and base YANG statements must be checked and updated if required.
  8. All "schema node identifiers" and XPath expressions need to be fixed in a following way (e.g. augment, leafref, must, when):
    • All references to nodes in an NMDA module are updated to reference the equivalent node in the NMDA generated "-state" module instead, normally by adding a "-s" to the prefix and importing the necessary generated "-state" module.
    • If the reference is to an already published non NMDA module (e.g. /interfaces in ietf-interfaces.yang) then the path is updated to use the existing "-state" top level container in the published module.
    • Note, it is optional as to whether must statements are removed from the generated "-state" module rather than being updated since a device is not generally expected to enforce them.
Clone this wiki locally