< draft-verdt-netmod-yang-module-versioning.txt | draft-verdt-netmod-yang-module-versioning.txt > | |||
---|---|---|---|---|
Network Working Group B. Claise | Network Working Group B. Claise | |||
Internet-Draft J. Clarke | Internet-Draft J. Clarke | |||
Updates: 7950 (if approved) R. Rahman | Updates: 7950 (if approved) R. Rahman | |||
Intended status: Standards Track R. Wilton, Ed. | Intended status: Standards Track R. Wilton, Ed. | |||
Expires: December 12, 2019 Cisco Systems, Inc. | Expires: December 14, 2019 Cisco Systems, Inc. | |||
B. Lengyel | B. Lengyel | |||
Ericsson | Ericsson | |||
J. Sterne | J. Sterne | |||
Nokia | Nokia | |||
K. D'Souza | K. D'Souza | |||
AT&T | AT&T | |||
June 10, 2019 | June 12, 2019 | |||
Updated YANG Module Revision Handling | Updated YANG Module Revision Handling | |||
draft-verdt-netmod-yang-module-versioning-00 | draft-verdt-netmod-yang-module-versioning-00 | |||
Abstract | Abstract | |||
This document specifies a new YANG module update procedure that can | This document specifies a new YANG module update procedure that can | |||
document when non-backwards-compatible changes have occurred during | document when non-backwards-compatible changes have occurred during | |||
the evolution of a YANG module. It provides a variant to the YANG | the evolution of a YANG module. It provides a variant to the YANG | |||
import statement to better represent inter-module dependencies. It | import statement to better represent inter-module dependencies. It | |||
skipping to change at page 1, line 44 ¶ | skipping to change at page 1, line 44 ¶ | |||
Internet-Drafts are working documents of the Internet Engineering | Internet-Drafts are working documents of the Internet Engineering | |||
Task Force (IETF). Note that other groups may also distribute | Task Force (IETF). Note that other groups may also distribute | |||
working documents as Internet-Drafts. The list of current Internet- | working documents as Internet-Drafts. The list of current Internet- | |||
Drafts is at https://datatracker.ietf.org/drafts/current/. | Drafts is at https://datatracker.ietf.org/drafts/current/. | |||
Internet-Drafts are draft documents valid for a maximum of six months | Internet-Drafts are draft documents valid for a maximum of six months | |||
and may be updated, replaced, or obsoleted by other documents at any | and may be updated, replaced, or obsoleted by other documents at any | |||
time. It is inappropriate to use Internet-Drafts as reference | time. It is inappropriate to use Internet-Drafts as reference | |||
material or to cite them other than as "work in progress." | material or to cite them other than as "work in progress." | |||
This Internet-Draft will expire on December 12, 2019. | This Internet-Draft will expire on December 14, 2019. | |||
Copyright Notice | Copyright Notice | |||
Copyright (c) 2019 IETF Trust and the persons identified as the | Copyright (c) 2019 IETF Trust and the persons identified as the | |||
document authors. All rights reserved. | document authors. All rights reserved. | |||
This document is subject to BCP 78 and the IETF Trust's Legal | This document is subject to BCP 78 and the IETF Trust's Legal | |||
Provisions Relating to IETF Documents | Provisions Relating to IETF Documents | |||
(https://trustee.ietf.org/license-info) in effect on the date of | (https://trustee.ietf.org/license-info) in effect on the date of | |||
publication of this document. Please review these documents | publication of this document. Please review these documents | |||
skipping to change at page 2, line 44 ¶ | skipping to change at page 2, line 44 ¶ | |||
4.1. Module import examples . . . . . . . . . . . . . . . . . 11 | 4.1. Module import examples . . . . . . . . . . . . . . . . . 11 | |||
5. Updates to ietf-yang-library . . . . . . . . . . . . . . . . 13 | 5. Updates to ietf-yang-library . . . . . . . . . . . . . . . . 13 | |||
5.1. Advertising revision-label . . . . . . . . . . . . . . . 13 | 5.1. Advertising revision-label . . . . . . . . . . . . . . . 13 | |||
5.2. Resolving ambiguous module imports . . . . . . . . . . . 13 | 5.2. Resolving ambiguous module imports . . . . . . . . . . . 13 | |||
5.3. Reporting how deprecated and obsolete nodes are handled . 14 | 5.3. Reporting how deprecated and obsolete nodes are handled . 14 | |||
6. Versioning of YANG instance data . . . . . . . . . . . . . . 14 | 6. Versioning of YANG instance data . . . . . . . . . . . . . . 14 | |||
7. Guidelines for using the YANG module update rules . . . . . . 15 | 7. Guidelines for using the YANG module update rules . . . . . . 15 | |||
7.1. Guidelines for YANG module authors . . . . . . . . . . . 15 | 7.1. Guidelines for YANG module authors . . . . . . . . . . . 15 | |||
7.1.1. Making non-backwards-compatible changes to a YANG | 7.1.1. Making non-backwards-compatible changes to a YANG | |||
module . . . . . . . . . . . . . . . . . . . . . . . 15 | module . . . . . . . . . . . . . . . . . . . . . . . 15 | |||
7.2. Versioning Considerations for Clients . . . . . . . . . . 16 | 7.2. Versioning Considerations for Clients . . . . . . . . . . 17 | |||
8. Module Versioning Extension YANG Modules . . . . . . . . . . 17 | 8. Module Versioning Extension YANG Modules . . . . . . . . . . 17 | |||
9. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 23 | 9. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 23 | |||
10. Security Considerations . . . . . . . . . . . . . . . . . . . 23 | 10. Security Considerations . . . . . . . . . . . . . . . . . . . 24 | |||
11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23 | 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 24 | |||
11.1. YANG Module Registrations . . . . . . . . . . . . . . . 23 | 11.1. YANG Module Registrations . . . . . . . . . . . . . . . 24 | |||
12. References . . . . . . . . . . . . . . . . . . . . . . . . . 24 | 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 24 | |||
12.1. Normative References . . . . . . . . . . . . . . . . . . 24 | 12.1. Normative References . . . . . . . . . . . . . . . . . . 24 | |||
12.2. Informative References . . . . . . . . . . . . . . . . . 25 | 12.2. Informative References . . . . . . . . . . . . . . . . . 25 | |||
Appendix A. Appendix . . . . . . . . . . . . . . . . . . . . . . 25 | Appendix A. Appendix . . . . . . . . . . . . . . . . . . . . . . 26 | |||
A.1. Examples of guidelines for making NBC changes to a YANG | A.1. Examples of guidelines for making NBC changes to a YANG | |||
module . . . . . . . . . . . . . . . . . . . . . . . . . 25 | module . . . . . . . . . . . . . . . . . . . . . . . . . 26 | |||
A.1.1. Removing a data node . . . . . . . . . . . . . . . . 26 | A.1.1. Removing a data node . . . . . . . . . . . . . . . . 26 | |||
A.1.2. Changing the type of a leaf node . . . . . . . . . . 26 | A.1.2. Changing the type of a leaf node . . . . . . . . . . 27 | |||
A.1.3. Reducing the range of a leaf node . . . . . . . . . . 27 | A.1.3. Reducing the range of a leaf node . . . . . . . . . . 28 | |||
A.1.4. Changing the key of a list . . . . . . . . . . . . . 28 | A.1.4. Changing the key of a list . . . . . . . . . . . . . 28 | |||
A.1.5. Renaming a node . . . . . . . . . . . . . . . . . . . 29 | A.1.5. Renaming a node . . . . . . . . . . . . . . . . . . . 29 | |||
A.1.6. Changing a default value . . . . . . . . . . . . . . 30 | A.1.6. Changing a default value . . . . . . . . . . . . . . 30 | |||
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 30 | Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 30 | |||
1. Introduction | 1. Introduction | |||
This document defines a solution to the YANG module lifecycle | This document defines a solution to the YANG module lifecycle | |||
problems described in [I-D.verdt-netmod-yang-versioning-reqs]. | problems described in [I-D.verdt-netmod-yang-versioning-reqs]. | |||
Complementary documents provide a complete solution to the YANG | Complementary documents provide a complete solution to the YANG | |||
skipping to change at page 15, line 10 ¶ | skipping to change at page 15, line 10 ¶ | |||
instance data set, may help a client to determine whether the | instance data set, may help a client to determine whether the | |||
instance data could also be used in conjunction with other revisions | instance data could also be used in conjunction with other revisions | |||
of the YANG schema, or other revisions of the modules that define the | of the YANG schema, or other revisions of the modules that define the | |||
schema. | schema. | |||
7. Guidelines for using the YANG module update rules | 7. Guidelines for using the YANG module update rules | |||
7.1. Guidelines for YANG module authors | 7.1. Guidelines for YANG module authors | |||
NBC changes to YANG modules may cause problems to clients, who are | NBC changes to YANG modules may cause problems to clients, who are | |||
consumers of YANG models, and SHOULD be avoided. YANG module authors | consumers of YANG models, and hence YANG module authors are | |||
are recommended to minimize NBC changes and keep changes BC whenever | RECOMMENDED to minimize NBC changes and keep changes BC whenever | |||
possible. | possible. | |||
When NBC changes are introduced, consideration should be given to the | When NBC changes are introduced, consideration should be given to the | |||
impact on clients and YANG module authors SHOULD try to mitigate that | impact on clients and YANG module authors SHOULD try to mitigate that | |||
impact. | impact. | |||
[Moved from section 4.] Using the "revision-date" statement causes | [Moved from section 4.] Using the "revision-date" statement causes | |||
overly strict import dependencies between modules and SHOULD NOT be | overly strict import dependencies between modules and SHOULD NOT be | |||
used. | used. | |||
A "rev:nbc-changes" statement SHOULD be added only if there are NBC | ||||
changes relative to the previous revision. | ||||
The YANG semantic versioning scheme applies only to YANG modules. | ||||
YANG submodules are not independently versioned by the YANG semantic | ||||
versioning scheme. Instead, if a versioned module includes one or | ||||
more submodules then those submodules are implicitly versioned as | ||||
part of the module's 'rev:revision-label' statements, and all the | ||||
module's 'include' statements MUST specify the revision-date for each | ||||
of the included submodules if any grouping from the submodules is | ||||
used by the module. | ||||
Removing old revision statements from a module's revision history | ||||
could break import by revision, and hence it is RECOMMENDED to retain | ||||
them. If all depencencies have been updated to not import specific | ||||
revisions of a module, then the corresponding revision statements can | ||||
be removed from that module. An alternative solution, if the | ||||
revision section is too long, would be remove, or curtail, the older | ||||
description statements associated with the previous revisions. | ||||
7.1.1. Making non-backwards-compatible changes to a YANG module | 7.1.1. Making non-backwards-compatible changes to a YANG module | |||
There are various valid situations where a YANG module has to be | There are various valid situations where a YANG module has to be | |||
modified in an NBC way. Here are the different ways in which this | modified in an NBC way. Here are the different ways in which this | |||
can be done: | can be done: | |||
o NBC changes can be done incrementally using the "deprecated" | o NBC changes can be sometimes be done incrementally using the | |||
status to provide clients time to adapt to NBC changes. | "deprecated" status to provide clients time to adapt to NBC | |||
changes. | ||||
o NBC changes are done at once, i.e. without using "status" | o NBC changes are done at once, i.e. without using "status" | |||
statements. This has a big impact on clients. | statements. Depending on the change, this may have a big impact | |||
on clients. | ||||
o If the server can support multiple versions of the YANG module or | o If the server can support multiple versions of the YANG module or | |||
of YANG packages(as specified in | of YANG packages(as specified in | |||
[I-D.rwilton-netmod-yang-packages]), and allows the client to | [I-D.rwilton-netmod-yang-packages]), and allows the client to | |||
select the version (as per | select the version (as per | |||
[I-D.wilton-netmod-yang-ver-selection]), then NBC changes MAY be | [I-D.wilton-netmod-yang-ver-selection]), then NBC changes MAY be | |||
done without using "status" statements. Clients would be required | done without using "status" statements. Clients would be required | |||
to select the version which they support and the NBC change would | to select the version which they support and the NBC change would | |||
have no impact on them | have no impact on them | |||
Here are some guidelines on how NBC changes can be made | Here are some guidelines on how non-backwards-compatible changes can | |||
incrementally: | be made incrementally, with the assumption that deprecated nodes are | |||
implemented by the server, and obsolete nodes are not: | ||||
1. The changes should be made gradually, e.g. a data node's status | 1. The changes should be made gradually, e.g. a data node's status | |||
SHOULD NOT be changed directly from "current" to "obsolete" (see | SHOULD NOT be changed directly from "current" to "obsolete" (see | |||
Section 4.7 of [RFC8407]), instead the status SHOULD first be | Section 4.7 of [RFC8407]), instead the status SHOULD first be | |||
marked "deprecated" and then when support is removed its status | marked "deprecated" and then when support is removed its status | |||
MUST be changed to "obsolete". Instead of using the "obsolete" | MUST be changed to "obsolete". Instead of using the "obsolete" | |||
status, the data node MAY be removed from the model but this has | status, the data node MAY be removed from the model but this has | |||
the risk of breaking modules which import the modified module. | the risk of breaking modules which import the modified module. | |||
2. A node with status "deprecated" MUST be supported for the | 2. The new extension "status-description" SHOULD be used for nodes | |||
solution described here to function properly. | ||||
3. A node with status "deprecated" SHOULD be available for at least | ||||
one year before its status is changed to "obsolete", see | ||||
Section 4.7 of [RFC8407]. | ||||
4. Support for a node which is "obsolete" is indicated by the node | ||||
"obsolete-nodes-present, see Section 5. | ||||
5. The new extension "status-description" SHOULD be used for nodes | ||||
which are "obsolete" or "deprecated". | which are "obsolete" or "deprecated". | |||
6. For status "deprecated", the "status-description" SHOULD also | 3. For status "deprecated", the "status-description" SHOULD also | |||
indicate until when support for the node is guaranteed. If there | indicate until when support for the node is guaranteed (if | |||
is a replacement data node, rpc, action or notification for the | known). If there is a replacement data node, rpc, action or | |||
deprecated node, this SHOULD be stated in the "status- | notification for the deprecated node, this SHOULD be stated in | |||
description". | the "status-description". The reason for deprecating the node | |||
can also be included in the "status-description" if it is deemed | ||||
to be of potential interest to the user. | ||||
7. When obsoleting or deprecating data nodes, the "deprecated" or | 4. For status "obsolete", it is RECOMMENDED to keep the "status- | |||
description" information, from when the node had status | ||||
"deprecated, which is still relevant. | ||||
5. When obsoleting or deprecating data nodes, the "deprecated" or | ||||
"obsolete" status SHOULD be applied at the highest possible level | "obsolete" status SHOULD be applied at the highest possible level | |||
in the data tree. For example, when deprecating all data nodes | in the data tree with an appropriate "status-description" | |||
in a container, the "deprecated" status SHOULD be applied to the | statement. For clarity, the "status" statement SHOULD also be | |||
container. For clarity, the status MAY be added in all the | applied to all descendent data nodes, but the "status- | |||
affected nodes but the status-description SHOULD be added only at | description" statement does not need to be repeated if it does | |||
the highest level in the tree. | not introduce any additional information. | |||
See Appendix A.1 for examples on how NBC changes can be made. | See Appendix A.1 for examples on how NBC changes can be made. | |||
7.2. Versioning Considerations for Clients | 7.2. Versioning Considerations for Clients | |||
Guidelines for clients of modules using the new module revision | Guidelines for clients of modules using the new module revision | |||
update procedure: | update procedure: | |||
o Clients SHOULD be liberal when processing data received from a | o Clients SHOULD be liberal when processing data received from a | |||
server. For example, the server may have increased the range of | server. For example, the server may have increased the range of | |||
an operational node causing the client to receive a value which is | an operational node causing the client to receive a value which is | |||
outside the range of the YANG model revision it was coded against. | outside the range of the YANG model revision it was coded against. | |||
o Clients SHOULD monitor changes to published YANG modules through | o Clients SHOULD monitor changes to published YANG modules through | |||
their revision history, and use appropriate tooling to understand | their revision history, and use appropriate tooling to understand | |||
the specific changes between module revision. In particular, | the specific changes between module revision. In particular, | |||
clients SHOULD NOT migrate to NBC revisions of a module without | clients SHOULD NOT migrate to NBC revisions of a module without | |||
considering the specific NBC changes. | understanding any potential impact of the specific NBC changes. | |||
o Clients SHOULD plan to make changes to match published status | o Clients SHOULD plan to make changes to match published status | |||
changes. When a node's status changes from "current" to | changes. When a node's status changes from "current" to | |||
"deprecated", clients SHOULD plan to stop using that node in a | "deprecated", clients SHOULD plan to stop using that node in a | |||
timely fashion. When a node's status changes to "obsolete", | timely fashion. When a node's status changes to "obsolete", | |||
clients MUST stop using that node. | clients MUST stop using that node. | |||
8. Module Versioning Extension YANG Modules | 8. Module Versioning Extension YANG Modules | |||
YANG module with extensions for defining a module's YANG semantic | YANG module with extensions for defining a module's YANG semantic | |||
End of changes. 18 change blocks. | ||||
41 lines changed or deleted | 60 lines changed or added | |||
This html diff was produced by rfcdiff 1.47. The latest version is available from http://tools.ietf.org/tools/rfcdiff/ |