-
Notifications
You must be signed in to change notification settings - Fork 3
/
draft-ietf-netmod-yang-versioning-reqs.xml
398 lines (385 loc) · 25.4 KB
/
draft-ietf-netmod-yang-versioning-reqs.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!ENTITY RFC6020 SYSTEM "reference.RFC.6020.xml">
<!ENTITY RFC7895 SYSTEM "reference.RFC.7895.xml">
<!ENTITY RFC7950 SYSTEM "reference.RFC.7950.xml">
<!ENTITY RFC8199 SYSTEM "reference.RFC.8199.xml">
<!ENTITY RFC8299 SYSTEM "reference.RFC.8299.xml">
<!ENTITY RFC8049 SYSTEM "reference.RFC.8049.xml">
<!ENTITY RFC2119 SYSTEM "reference.RFC.2119.xml">
]>
<?xml-stylesheet type="text/xsl" href="rfc2629.xslt" ?>
<?rfc toc="yes"?>
<?rfc tocompact="yes"?>
<?rfc tocdepth="4"?>
<?rfc tocindent="yes"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
<?rfc comments="yes"?>
<?rfc inline="yes"?>
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<rfc category="info" ipr="trust200902" docName="draft-ietf-netmod-yang-versioning-reqs-02">
<front>
<title abbrev="YANG Versioning Requirements">YANG Module Versioning Requirements</title>
<author initials="J." surname="Clarke" fullname="Joe Clarke" role="editor">
<organization>Cisco Systems, Inc.</organization>
<address>
<postal>
<street>7200-12 Kit Creek Rd</street>
<city>Research Triangle Park</city>
<region>North Carolina</region>
<country>United States of America</country>
</postal>
<phone>+1-919-392-2867</phone>
<email>jclarke@cisco.com</email>
</address>
</author>
<date/>
<abstract>
<t>
This document describes the problems that can arise because of the YANG language module update rules, that require all updates to YANG module preserve strict backwards compatibility. It also defines the requirements on any solution designed to solve the stated problems. This document does not consider possible solutions, nor endorse any particular solution.
</t>
</abstract>
</front>
<middle>
<section anchor="intro" title="Introduction">
<t>
This requirements document initially considers some of the existing YANG module update rules, then describes the problems that arise due to those rules embracing strict backwards compatibility, and finally defines requirements on any solution that may be designed to solve these problems by providing an alternative YANG versioning strategy.
</t>
</section>
<section anchor="background" title="Background">
<t>
The YANG data modeling language
<xref target="RFC7950"/>
specifies strict rules for updating YANG modules (see section 11 "Updating a Module"). Citing a few of the relevant rules:
<list style="numbers">
<t>
"As experience is gained with a module, it may be desirable to revise that module. However, changes to published modules are not allowed if they have any potential to cause interoperability problems between a client using an original specification and a server using an updated specification."
</t>
<t>"Note that definitions contained in a module are available to be imported by any other module and are referenced in "import" statements via the module name. Thus, a module name MUST NOT be changed. Furthermore, the "namespace" statement MUST NOT be changed, since all XML elements are qualified by the namespace."
</t>
<t>"Otherwise, if the semantics of any previous definition are changed (i.e., if a non-editorial change is made to any definition other than those specifically allowed above), then this MUST be achieved by a new definition with a new identifier."
</t>
<t>
"deprecated indicates an obsolete definition, but it permits new/continued implementation in order to foster interoperability with older/existing implementations."
</t>
</list>
The rules described above, along with other similar rules, causes various problems, as described in the following sections:
</t>
<section anchor="slow_standardization" title="Striving for model perfection">
<t>
The points made above lead to the logical conclusion that the standardized YANG modules have to be perfect on day one (at least the structure and meaning), which in turn might explain why IETF YANG modules take so long to standardize.
Shooting for perfection is obviously a noble goal, but if the perfect standard comes too late, it doesn't help the industry.
</t>
</section>
<section anchor="some_YANG_modules_are_not_backward_compatible" title="Some YANG Modules Are Not Backwards-Compatible">
<t>
As we learn from our mistakes, we're going to face more and more non-backwards-compatible YANG modules. An example is the YANG data model for L3VPN service delivery
<xref target="RFC8049"/>, which, based on implementation experience, has been updated in a non-backwards-compatible way by
<xref target="RFC8299"/>.
</t>
<t>
While Standards Development Organization (SDO) YANG modules are obviously better for the industry, we must recognize that many YANG modules are actually generated YANG modules (for example, from internal databases),
which is sometimes the case for vendor modules
<xref target="RFC8199"/>. From time to time, the new YANG modules are not backwards-compatible.
</t>
<t>
Old module parts that are no longer needed, no longer supported, or are not used by consumers need to be removed from modules. It is often hard to decide which parts are no longer needed/used; still the need and practice of removing old parts exist.
While it is rare in standard modules it is more common in vendor YANG modules where the usage of modules is more controlled.
</t>
<t>
The problems described in
<xref target="clear_indication_of_node_support"/>
may also result in incompatible changes.
</t>
<t>
In such cases, it would be better to indicate how backwards-compatible a given YANG module actually is.
</t>
<t>As modules are sometimes updated in an incompatible way the current assumption that once a YANG module is defined all further revisions can be freely used as they are compatible is not valid.</t>
</section>
<section title="Non-Backwards-Compatible Errors">
<t>
Sometimes small errors force us to make non-backwards-compatible updates. As an example imagine that we have a string with a complex pattern (e.g., an IP address). Let's assume the initial pattern incorrectly allows IP addresses to start with 355. In
the next version this is corrected to disallow addresses starting with 355. Formally this is a non-backwards-compatible change as the value space of the string is decreased. In reality an IP address and the implementation behind it was never capable
of handling an address starting with 355. So practically this is a backwards-compatible change, just like a correction of the description statement. Current YANG rules are ambiguous as to whether non-backwards-compatible bug fixes are allowed without also requiring a module name change.
</t>
</section>
<section title="No way to easily decide whether a change is Backwards-Compatible">
<t>
A management system, SDN controller, or any other user of a module should be capable of easily determining the compatibility between two module versions. Higher level logic for a network function, something that cannot be implemented in a purely
model driven way, is always dependent on a specific version of the module. If the client finds that the module has been updated on the network node, it has to decide if it tries to handle it as it handled the previous version of the model or if it
just stops, to avoid problems. To make this decision the client needs to know if the module was updated in a backwards-compatible way or not.
</t>
<t>
This is not possible to decide today because of the following:
<list style="symbols">
<t>It is sometimes necessary to change the semantic behavior of a data node, action or rpc while the YANG definition does not change (with the possible exception of the description statement). In such a case it is impossible to determine whether the change is
backwards-compatible just by looking at the YANG statements. It's only the human model designer who can decide.</t>
<t>Problems with the deprecated and obsolete status statement,
<xref target="clear_indication_of_node_support"/></t>
<t>YANG module authors might decide to violate YANG 1.1 update rules for some of the reasons above.</t>
</list>
Finding status changes or violations of update rules need a line-by-line comparison of the old and new modules is a tedious task.
</t>
</section>
<section title="No good way to specify which module revision to import">
<t>
If a module (MOD-A) is imported by another one (MOD-B) the importer may specify which revision must be imported. Even if MOD-A is updated in a backwards-compatible way not all revisions will be suitable, e.g., a new MOD-B might need the newest MOD-A.
However, both specifying or omitting the revision date for import leads to problems.
</t>
<t>
If the import by revision-date is specified
<list style="symbols">
<t>
If corrections are made to MOD-A these would not have any effect as the import’s revision date would still point to the un-corrected earlier YANG module revision.
</t>
<t>
If MOD-A is updated in a backwards-compatible way because another importer (MOD-C) needs some functionality, the new MOD-A could be used by MOD-B, but specifying the exact import revision-date prevents this. This will force the implementers to
import two different revisions of MOD-A, forcing them to maintain old MOD-A revisions unnecessarily.
</t>
<t>
If multiple modules import different revisions of MOD-A the human user will need to understand the subtle differences between the different revisions. Small differences would easily lead to operator mistakes as the operator will rarely check the
documentation.
</t>
<t>
Tooling/SW is often not prepared to handle multiple revisions of the same YANG module.
</t>
</list>
</t>
<t>
If the import revision-date is not specified
<list style="symbols">
<t>
any revision of MOD-A may be used including unsuitable ones. Older revisions may be lacking functionality MOD-B needs. Newer MOD-A revisions may obsolete definitions used by MOD-B in which case these must not be used by MOD-B anymore.
</t>
<t>
As it is not specified which revisions of MOD-A are suitable for MOD-B. The problem has to be solved on a case by case basis studying all the details of MOD-A and MOD-B which is considerable work.
</t>
</list>
</t>
</section>
<section title="Early Warning about Removal">
<t>
If a schema part is considered old/bad we need to be able to give advance warning that it will be removed. As this is an advance warning the part must still be present and usable in the current revision; however, it will be removed in one of the next
revisions. The deprecated statement cannot be reliably used for this purpose both because deprecated nodes may not be implemented and also there is no mandate that text be provided explaining the deprecation.
</t>
<t>
We need the advance warning to allow users of the module time to plan/execute migration away from the deprecated functionality. Deprecation should be accompanied by information whether the functionality will just disappear or that there is an
alternative, possibly more advanced solution that should be used.
</t>
<t>
Vendors use such warnings often, but the NMDA related redesign of IETF modules is also an example where it would be useful for IETF. As another example, see the usage of deprecated in the Java programming language.
</t>
</section>
<section title="Clear Indication of Node Support" anchor="clear_indication_of_node_support">
<t>
The current definition of deprecated and obsolete in
<xref target="RFC7950"/>
(as quoted below) is problematic and should be corrected.
<list style="symbols">
<t>"deprecated" indicates an obsolete definition, but it permits new/continued implementation in order to foster interoperability with older/existing implementations.</t>
<t>"obsolete" means that the definition is obsolete and SHOULD NOT be implemented and/or can be removed from implementations.</t>
</list>
</t>
<t>YANG is considered an interface contract between the server and the client. The current definitions of deprecated and obsolete mean that a schema node that is either deprecated or obsolete may or may not be implemented. The client has no way to
find out which is the case except for by trying to write or read data at the leaf in question. This probing would need to be done for each separate data-node, which is not a trivial thing to do. This "may or may not" is unacceptable in a contract. In
effect, this works as if there would be an if-feature statement on each deprecated schema node where the server does not advertise whether the feature is supported or not. Why is it not advertised?
</t>
</section>
</section>
<section anchor="terminology" title="Terminology and Conventions">
<t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in
<xref target="RFC2119"/>.</t>
<t>In addition, this document uses the following terminology:
<list style="symbols">
<t>YANG module revision: An instance of a YANG module, with no implied ordering or backwards compatibility between different revisions of the same module."</t>
<t>YANG module version: A YANG module revision, but also with an implied partial ordering relationship between other versions of the same module. Each module version must be uniquely identifiable.</t>
<t>Non-backwards-compatible (NBC): In the context of this document, the term 'non-backwards-compatible' refers to a change or set of changes between two
YANG module revisions that do not adhere to the list of allowable changes specified in Section 11 "Updating a Module" of <xref target="RFC7950"/>,
with the following additional clarification:
<list style="symbols">
<t>Any addition of, or change to, a "status" statement that allows a server to remove support for a schema node is considered a
non-backwards-compatible change</t>
</list>
</t>
</list>
</t>
</section>
<section anchor="problems" title="The Problem Statement">
<t>
Considering the issues described in the background, the problem definition can be summarized as follows.
</t>
<t>
Development of data models for a large collection of communication
protocols and system components is difficult and typically only
manageable with an iterative development process. Agile development
approaches advocate evolutionary development, early delivery, and
continual improvement. They are designed to support rapid and
flexible response to change. Agile development has been found to be
very successful in a world where the objects being modeled undergo
constant changes.
</t>
<t>
The current module versioning scheme relies on the fundamental idea
that a definition, once published, never changes its semantics. As a
consequence, if a new definition is needed with different
non-backwards-compatible semantics, then a new definition must be
created to replace the old definition. The advantage of this
versioning scheme is that a definition identified by a module name
and a path has fixed semantics that never change. (The details are a
bit more nuanced but we simplify things here a bit in order to get
the problems worked out clearly.)
</t>
<t>
There are two main disadvantages of the current YANG versioning
scheme:
<list style="symbols">
<t>Any non-backwards-compatible change of a definition requires
either a new module name or a new path. This has been found costly
to support in implementations, in particular on the client side.</t>
<t>Since non-backwards-compatible changes require either a new module
name or a new path, such changes will impact other modules that
import definitions. In fact, with the current module versioning
scheme other modules have to opt-in in order to use the new
version. This essentially leads to a ripple effect where a
non-backwards-compatible change of a core module causes updates on
a potentially large number of dependent modules.</t>
</list>
</t>
<t>
Other problems experienced with the current YANG versioning scheme
are the following:
<list style="symbols">
<t>
YANG has a mechanism to mark definitions deprecated but it leaves
it open whether implementations are expected to implement
deprecated definitions and there is no way (other than trial and
error) for a client to find out whether deprecated definitions are
supported by a given implementation.
</t>
<t> YANG does not have a robust mechanism to document which data
definitions have changed and to provide guidance how
implementations should deal with the change. While it is possible
to have this described in general description statements, having
these details embedded in general description statements does not
make this information accessible to tools.
</t>
<t>
YANG data models often do not exist in isolation and they interact
with other software systems or data models that often do allow
(controlled) non-backwards-compatible changes. In some cases, YANG
models are mechanically derived from other data models that do allow
(controlled) non-backwards-compatible changes. In such situations,
a robust mapping to YANG requires to have version numbers exposed
as part of the module name or a path definition, which has been
found to be expensive on the client side (see above).
</t>
</list>
</t>
<t>
Given the need to support agile development processes and the
disadvantages and problems of the current YANG versioning scheme
described above, it is necessary to develop requirements and
solutions for a future YANG versioning scheme that better supports
agile development processes, whilst retaining the ability for
servers to handle clients using older versions of YANG modules.
</t>
</section>
<section anchor="requirements" title="Requirements of a YANG Versioning Solution">
<t>The following is a list of requirements that a solution to the problems mentioned above MUST or SHOULD have. The list is grouped by similar requirements but is not presented in a set priority order.
<list style="numbers">
<t>Requirements related to making non-backwards-compatible updates to modules:
<list style="format 1.%d">
<t>A mechanism is REQUIRED to update a module in a non-backwards-compatible way without forcing all modules with import dependencies on the updated module from being updated at the same time (e.g. to change its import to use a new module name).</t>
<t>Non-backwards-compatible updates of a module MUST not impact clients that only access data nodes of the module that have either not been
updated or have been updated in backwards-compatible ways.</t>
<t>A refined form of YANG's 'import' statement MUST be provided that is more restrictive than "import any revision" and less restrictive than "import a specific revision". Once non-backwards-compatible changes to modules are allowed, the refined
import statement is used to express the correct dependency between modules.</t>
<t>The solution MUST be able to express when non-backwards-compatible changes have occurred between two revisions of a given
YANG module.</t>
</list>
</t>
<t>Requirements related to identifying changes between different module revisions:
<list style="format 2.%d">
<t>Readers of modules, and tools that use modules, MUST be able to determine whether changes between two revisions of a module constitute a backwards-compatible or non-backwards-compatible version change. In addition, it MAY be helpful to identify
whether changes represent bug fixes, new functionality, or both.</t>
<t>A mechanism SHOULD be defined to determine whether data nodes between two arbitrary YANG module revisions have (i) not changed, (ii) changed in a backwards-compatible way, (iii) changed in a non-backwards-compatible way.</t>
</list>
</t>
<t>Requirements related to supporting existing clients in a backwards-compatible way:
<list style="format 3.%d">
<t>The solution MUST provide a mechanism to allow servers to support existing clients in a backwards-compatible way.</t>
<!--<t>The solution MUST provide a mechanism to allow servers to simultaneously support clients using different revisions of modules. A client's choice of particular revision of one or more modules may restrict the particular revision of other modules
that may be used in the same request or session.</t>-->
<t>The solution MUST provide a mechanism to support clients that expect an older version of a given module when the current version has had
non-backwards-compatible changes.</t>
<t>Clients are expected to be able to handle unexpected instance data resulting from backwards-compatible changes.</t>
</list>
</t>
<t>Requirements related to managing and documenting the life cycle of data nodes:
<list style="format 4.%d">
<t>A mechanism is REQUIRED to allow a client to determine whether deprecated nodes are implemented by the server.</t>
<t>If a data node is deprecated or obsolete then it MUST be possible to document in the YANG module what alternatives exist, the reason for the status change, or any other status related information.</t>
<t>A mechanism is REQUIRED to indicate that certain definitions in a YANG module will become status obsolete in future revisions but definitions marked as such MUST still be implemented by compliant servers.</t>
</list>
</t>
<t>Requirements related to documentation and education:
<list style="format 5.%d">
<t>The solution MUST provide guidance to model authors and clients on how to use the new YANG versioning scheme.</t>
<t>The solution is REQUIRED to describe how to transition from the existing YANG 1.0/1.1 versioning scheme to the new scheme.</t>
<t>The solution MUST describe how the versioning scheme affects the interpretation of instance data and references to instance data, for which the schema definition has been updated in a non-backwards-compatible way.</t>
</list>
</t>
</list>
</t>
</section>
<section anchor="contributor" title="Contributors">
<t>This document grew out of the YANG module versioning design team that started after IETF 101. The following people are members of that design team and have contributed to defining the problem and specifying the requirements:</t>
<t>
<list style="symbols">
<t>Balazs Lengyel
</t>
<t>Benoit Claise
</t>
<t>Ebben Aries</t>
<t>Jason Sterne</t>
<t>Joe Clarke</t>
<t>Juergen Schoenwaelder</t>
<t>Mahesh Jethanandani</t>
<t>Michael (Wangzitao)</t>
<t>Qin Wu</t>
<t>Reshad Rahman</t>
<t>Rob Wilton</t>
</list>
</t>
</section>
<section anchor="acknowledgments" title="Acknowledgments">
<t>The design team would like to thank Christian Hopps and Vladimir Vassilev for their feedback and perspectives in shaping and fine tuning the
versioning requirements.</t>
<t>One of the inspirations for solving the YANG module versioning comes from OpenConfig.
The authors would like to thank Anees Shaikh and Rob Shakir for their helpful input.</t>
</section>
<section anchor="security" title="Security Considerations">
<t>
The document does not define any new protocol or data model. There is no security impact.
</t>
</section>
<section anchor="iana" title="IANA Considerations">
<t>None</t>
</section>
</middle>
<?rfc needLines="20"?>
<back>
<references title="Normative References">
<?rfc include="reference.RFC.7950"?>
<?rfc include="reference.RFC.2119"?>
</references>
<references title="Informative References">
<?rfc include="reference.RFC.8049"?>
<?rfc include="reference.RFC.8199"?>
<?rfc include="reference.RFC.8299"?>
</references>
<?rfc needLines="100"?>
</back>
</rfc>