idnits 2.17.1 draft-dsdt-nmda-guidelines-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (May 9, 2017) is 2542 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Outdated reference: A later version (-10) exists of draft-ietf-netmod-revised-datastores-01 -- Obsolete informational reference (is this intentional?): RFC 7223 (Obsoleted by RFC 8343) Summary: 0 errors (**), 0 flaws (~~), 3 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Bjorklund 3 Internet-Draft Tail-f Systems 4 Intended status: Informational J. Schoenwaelder 5 Expires: November 10, 2017 Jacobs University 6 P. Shafer 7 K. Watsen 8 Juniper Networks 9 R. Wilton 10 Cisco Systems 11 May 9, 2017 13 Guidelines for YANG Module Authors (NMDA) 14 draft-dsdt-nmda-guidelines-01 16 Abstract 18 The "Network Management Datastore Architecture" (NMDA) adds the 19 ability to inspect the current operational values for configuration, 20 allowing clients to use identical paths for retrieving the configured 21 values and the operational values. This change will simplify models 22 and help modelers, but will create a period of transition as NMDA 23 becomes a standard and is widely implemented. During that interim, 24 the guidelines given in this document should help modelers find an 25 optimal path forward. 27 Status of This Memo 29 This Internet-Draft is submitted in full conformance with the 30 provisions of BCP 78 and BCP 79. 32 Internet-Drafts are working documents of the Internet Engineering 33 Task Force (IETF). Note that other groups may also distribute 34 working documents as Internet-Drafts. The list of current Internet- 35 Drafts is at http://datatracker.ietf.org/drafts/current/. 37 Internet-Drafts are draft documents valid for a maximum of six months 38 and may be updated, replaced, or obsoleted by other documents at any 39 time. It is inappropriate to use Internet-Drafts as reference 40 material or to cite them other than as "work in progress." 42 This Internet-Draft will expire on November 10, 2017. 44 Copyright Notice 46 Copyright (c) 2017 IETF Trust and the persons identified as the 47 document authors. All rights reserved. 49 This document is subject to BCP 78 and the IETF Trust's Legal 50 Provisions Relating to IETF Documents 51 (http://trustee.ietf.org/license-info) in effect on the date of 52 publication of this document. Please review these documents 53 carefully, as they describe your rights and restrictions with respect 54 to this document. Code Components extracted from this document must 55 include Simplified BSD License text as described in Section 4.e of 56 the Trust Legal Provisions and are provided without warranty as 57 described in the Simplified BSD License. 59 Table of Contents 61 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 62 1.1. Keywords . . . . . . . . . . . . . . . . . . . . . . . . 2 63 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 2 64 1.3. Executive Summary . . . . . . . . . . . . . . . . . . . . 3 65 1.4. Background . . . . . . . . . . . . . . . . . . . . . . . 3 66 1.5. Network Management Datastores Architecture . . . . . . . 5 67 2. Guidelines for YANG Modelers . . . . . . . . . . . . . . . . 5 68 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 69 4. Security Considerations . . . . . . . . . . . . . . . . . . . 8 70 5. Informative References . . . . . . . . . . . . . . . . . . . 8 71 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 9 73 1. Introduction 75 This document provides advice and guidelines to help modelers plan 76 for the emerging "Network Management Datastore Architecture" (NMDA) 77 [I-D.ietf-netmod-revised-datastores]. This architecture provides an 78 architectural framework for datastores as they are used by network 79 management protocols such as NETCONF [RFC6241], RESTCONF [RFC8040] 80 and the YANG [RFC7950] data modeling language. Datastores are a 81 fundamental concept binding network management data models to network 82 management protocols, enabling data models to be written in a network 83 management protocol agnostic way. 85 1.1. Keywords 87 The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 88 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 89 "OPTIONAL" in this document are to be interpreted as described in BCP 90 14, [RFC2119]. 92 1.2. Terminology 94 This document uses the terminology defined by the NMDA 95 [I-D.ietf-netmod-revised-datastores]. 97 1.3. Executive Summary 99 The Network Management Datastore Architecture (NMDA) addresses the so 100 called "OpState problem" that has been the subject of much discussion 101 in the IETF. NMDA is still in development and there will be a 102 transition period before NMDA solutions are universally available. 104 These guidelines are aimed to enable the creation of models that can 105 take advantage of the NMDA, while pragmatically allowing those models 106 to be used with the existing network configuration protocol 107 implementations. 109 It is the strong recommendation that models SHOULD move as quickly as 110 possible to the NMDA. The specific approach to be taken for models 111 being developed now and during the NMDA transition period should be 112 based on both the expected usage and the maturity of the data model. 114 1. New models and models that are not concerned with the operational 115 state of configuration information SHOULD immediately be 116 structured to be NMDA-compatible. 118 2. Models that require immediate support for "in use" and "system 119 created" information SHOULD be structured for NMDA. A non-NMDA 120 version of these models SHOULD also be published, using either an 121 existing model or a model created either by hand or with suitable 122 tools that support current modeling strategies. Both the NMDA 123 and the non-NMDA modules SHOULD be published in the same 124 document, with NMDA modules in the document main body and the 125 non-NMDA modules in a non-normative appendix. The use of the 126 non-NMDA model will allow temporary bridging of the time period 127 until NMDA implementations are available. 129 Additional details on these guidelines can be found below, notably in 130 Section 2. 132 1.4. Background 134 NETCONF ([RFC6241]) was developed with a focus on configuration data, 135 and has unfortunate gaps in its treatment of operational data. The 136 operation can return configuration data (defined as 137 nodes with "config true") stored in . This data is 138 typically the only data created by CLI users and NETCONF clients. 139 The operation is defined as returning all the data on the 140 device, including the contents of , as well as any 141 operational state data. While the NETCONF design envisioned models 142 merging "config false" nodes with the contents of running, there are 143 two issues involved. 145 First, the desire of clients to see the true operational ("in use") 146 value of configuration data resulted in the need for data models to 147 have two distinct leafs, one to show the configured value and the 148 other to show the operational value. An example would be the speed 149 of an interface, where the configured value may not be the value that 150 is currently used. 152 Second, devices often have "system created" resources that exist as 153 operational data even when there is no corresponding configuration 154 data. An example would be built-in networking interfaces that always 155 appear in operational data. 157 A similar situation to the second issue discussed above exists while 158 the device is processing configuration data changes. When 159 configuration data is deleted, the operational data will continue to 160 exist during the time period in which the device is releasing 161 resources associated with the data. An example would be deleting a 162 BGP peer, where the peer continues to exist in operational data until 163 the connection is closed and any other resources are released. 165 To address these issues without requiring a protocol modification, 166 two distinct strategies have been adopted in YANG model design: 168 The first strategy makes two distinct top-level containers, one for 169 configuration and one for state. These are sometimes referred to as 170 "/foo" and "/foo-state". An example would be the interface model 171 defined in [RFC7223]. These models require two completely distinct 172 set of nodes, with repetition of both the interior containers, lists, 173 and key nodes, but also repetition of many other nodes to allow 174 visibility of the operational values of configured nodes. This leads 175 to over-use of YANG groupings in ways that affect the readability of 176 the models, as well as creating opportunities to incorrectly mirror 177 the model's hierarchies. Also this "stitching together" of data from 178 the two trees is merely a convention, not a formal relationship. 180 The second strategy uses two sibling containers, named "config" and 181 "state", placed deeper within the model node hierarchy. The "config" 182 container holds the configured values, while the "state" container 183 holds the operational values. The duplication of interior nodes in 184 the hierarchies is removed, but the duplication of leafs representing 185 configuration remains. Groupings can be used to avoid the repetition 186 of the leafs in the YANG file, but at the expense of readability. In 187 addition, this strategy does not handle the existence of operational 188 data for which there is no configuration data, such as the system- 189 created data and deleted peers scenarios discussed above. 191 1.5. Network Management Datastores Architecture 193 The Network Management Datastores Architecture (NMDA) addresses the 194 problems mentioned above by creating an architectural framework which 195 includes a distinct datastore for operational data, called 196 . This datastore is defined as containing both config 197 true and config false nodes, with the formal understanding that the 198 "in use" values are returned for the config true nodes. This allows 199 modelers to use a single hierarchy for all configuration and 200 operational data, which both improves readability and reduces the 201 possibility of modeling inconsistencies that might impact 202 programmatic access. 204 In addition, another datastore named is defined to provide 205 a complete view of the configuration data, even in the presence of 206 device-specific features that expand or remove configuration data. 207 While such mechanisms are currently non-standard, the NMDA recognizes 208 they exist and need to be handled appropriately. In the future, such 209 mechanisms may become standardized. 211 The NMDA allows the deprecation of NETCONF's operation, 212 removing the source of these issues. The new operations 213 and will support a parameter indicating the target 214 datastore. Similar changes are planned for RESTCONF ([RFC8040]). 216 2. Guidelines for YANG Modelers 218 The following guidelines are meant to help modelers develop YANG 219 models that will maximize the utility of the model with both current 220 implementations and NMDA-capable implementations. Any questions 221 regarding these guidelines can be sent to yang-doctors@ietf.org. 223 The direction taken should be based on both the maturity of the data 224 model, along with the number of concrete implementations of the 225 model. The intent is not to destabilize the IETF modeling community, 226 but to create models that can take advantage of the NMDA, while 227 pragmatically allowing those models to be used with the existing 228 network configuration protocol implementations. 230 It is the strong recommendation that models SHOULD move as quickly as 231 possible to the NMDA. This is key to the future of these models. 232 The NETMOD WG will rework existing models to this architecture. 233 Given the permanence and gravity of work published by the IETF, 234 creating future-proof data models is vital. 236 The two current strategies ("/foo-state" and "config"/"state" 237 containers) mix data retrieval details into the data model, 238 complicating the models and impairing their readability. Rather than 239 maintain these details inside the data model, models can be post- 240 processed to add this derivative information, either manually or 241 using tools. 243 Tools can automatically produce the required derived modules. The 244 suggested approach is to produce a "state" version of the module with 245 a distinct namespace, rather than using the "/foo-state" top-level 246 container. Since the contents are identical, constraints in the data 247 model such as "must" statements should not need to change. Only the 248 model name, namespace, and prefix should need to change. This 249 simplifies the tooling needed to generate the derived model, as well 250 as reducing changes needed in client applications when transitioning 251 to the NMDA model. 253 These derived models use distinct module names and namespaces, 254 allowing servers to announce their support for the base or derived 255 models. 257 Consider the following trivial model: 259 module example-thermostat { 260 namespace "tag:ietf:example:thermostat"; 261 prefix "thermo"; 263 container thermostat { 264 leaf high-temperature { 265 description "High temperature threshold"; 266 type int; 267 } 268 leaf low-temperature { 269 description "Low temperature threshold"; 270 type int; 271 } 272 leaf current-temperature { 273 description "Current temperature reading"; 274 type int; 275 config false; 276 } 277 } 278 } 280 In the derived model, the contents mirror the NMDA data model, but 281 are marked as "config false", and the module name and namespace 282 values have a "-state" suffix: 284 module example-thermostat-state { 285 namespace "tag:ietf:example:thermostat-state"; 286 prefix "thermo-state"; 288 container thermostat { 289 config false; 290 leaf high-temperature { 291 description "High temperature threshold"; 292 type int; 293 } 294 leaf low-temperature { 295 description "Low temperature threshold"; 296 type int; 297 } 298 leaf current-temperature { 299 description "Current temperature reading"; 300 type int; 301 } 302 } 303 } 305 By adopting a tools-based solution for supporting models that are 306 currently under development, models can be quickly restructured to be 307 NMDA-compatible while giving continuity to their community of 308 developers. When NMDA-capable implementations become available, the 309 base data models can be used directly. 311 Modelers and reviewers can view the simple data model, published in 312 the body of document. Tools can generate any required derived 313 models, and those models can be published in a non-normative appendix 314 to allow interoperability. 316 It is critical to consider the following guidelines, understanding 317 that our goal is to make models that will see continued use in the 318 long term, balancing short term needs against a desire for 319 consistent, usable models in the future: 321 (a) New models and models that are not concerned with the operational 322 state of configuration information SHOULD immediately be structured 323 to be NMDA-compatible. 325 (b) Models that require immediate support for "in use" and "system 326 created" information SHOULD be structured for NMDA. A non-NMDA 327 version of these models SHOULD exist, either an existing model or a 328 model created either by hand or with suitable tools that mirror the 329 current modeling strategies. Both the NMDA and the non-NMDA modules 330 SHOULD be published in the same document, with NMDA modules in the 331 document main body and the non-NMDA modules in a non-normative 332 appendix. The use of the non-NMDA model will allow temporary 333 bridging of the time period until NMDA implementations are available. 335 (c) For published models, the model should be republished with an 336 NMDA-compatible structure, deprecating non-NMDA constructs. For 337 example, the "ietf-interfaces" model in [RFC7223] will be 338 restructured as an NMDA-compatible model. The "/interfaces-state" 339 hierarchy will be marked "status deprecated". Models that mark their 340 "/foo-state" hierarchy with "status deprecated" will allow NMDA- 341 capable implementations to avoid the cost of duplicating the state 342 nodes, while enabling non-NMDA-capable implementations to utilize 343 them for access to the operational values. 345 (d) For models that augment models which have not been structured 346 with the NMDA, the modeler will have to consider the structure of the 347 base model and the guidelines listed above. Where possible, such 348 models should move to new revisions of the base model that are NMDA- 349 compatible. When that is not possible, augmenting "state" containers 350 SHOULD be avoided, with the expectation that the base model will be 351 re-released with the state containers marked as deprecated. It is 352 RECOMMENDED to augment only the "/foo" hierarchy of the base model. 353 Where this recommendation cannot be followed, then any new "state" 354 elements SHOULD be included in their own module. 356 3. IANA Considerations 358 This document has no actions for IANA. 360 4. Security Considerations 362 This document has no security considerations. 364 5. Informative References 366 [I-D.ietf-netmod-revised-datastores] 367 Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 368 and R. Wilton, "Network Management Datastore 369 Architecture", draft-ietf-netmod-revised-datastores-01 370 (work in progress), March 2017. 372 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 373 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 374 RFC2119, March 1997, 375 . 377 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 378 and A. Bierman, Ed., "Network Configuration Protocol 379 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 380 . 382 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 383 Management", RFC 7223, DOI 10.17487/RFC7223, May 2014, 384 . 386 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 387 RFC 7950, DOI 10.17487/RFC7950, August 2016, 388 . 390 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 391 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 392 . 394 Authors' Addresses 396 Martin Bjorklund 397 Tail-f Systems 399 Email: mbj@tail-f.com 401 Juergen Schoenwaelder 402 Jacobs University 404 Email: j.schoenwaelder@jacobs-university.de 406 Phil Shafer 407 Juniper Networks 409 Email: phil@juniper.net 411 Kent Watsen 412 Juniper Networks 414 Email: kwatsen@juniper.net 416 Rob Wilton 417 Cisco Systems 419 Email: rwilton@cisco.com