From 96e47d23c65ffa0ec0a24474cbe8f431d97d6c0b Mon Sep 17 00:00:00 2001 From: Reshad Rahman Date: Mon, 14 Oct 2019 16:27:06 -0400 Subject: [PATCH] Copied files from Rob's repo @ https://github.com/rgwilton/ver-selection-draft/ --- ...draft-wilton-netmod-yang-ver-selection.xml | 578 ++++++++++++++++++ .../ietf-schema-version-selection.yang | 225 +++++++ 2 files changed, 803 insertions(+) create mode 100644 yang-ver-selection/draft-wilton-netmod-yang-ver-selection.xml create mode 100644 yang-ver-selection/ietf-schema-version-selection.yang diff --git a/yang-ver-selection/draft-wilton-netmod-yang-ver-selection.xml b/yang-ver-selection/draft-wilton-netmod-yang-ver-selection.xml new file mode 100644 index 0000000..3621ea3 --- /dev/null +++ b/yang-ver-selection/draft-wilton-netmod-yang-ver-selection.xml @@ -0,0 +1,578 @@ + + + + + + + + + + + + + +]> + + + + + + + + + + + + + + YANG Schema Version Selection + + + Cisco Systems, Inc. +
+ rwilton@cisco.com +
+ + + Cisco Systems, Inc. +
+ rrahman@cisco.com +
+ + + + + This document defines protocol mechanisms to allow clients to choose which YANG schema to + use for interactions with a server, out of the available YANG schema supported by a server. + The provided functionality allow servers to support clients in a backwards compatible way, + at the same time allowing for non-backwards-compatible updates to YANG modules. + This draft provides a solution to YANG versioning requirements 3.1 and 3.2. + + + + +
+ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", + "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted + as described in BCP 14 when, and only when, + they appear in all capitals, as shown here. + + This document uses terminology introduced in the YANG versioning requirements draft . + This document also makes of the following terminology introduced in the Network Management + Datastore Architecture : + + datastore schema + + + In addition, this document makes use of the following terminology: + + bc: Used as an abbreviation for a backwards-compatible change. + nbc: Used as an abbreviation for a non-backwards-compatible change. + editorial change: A backwards-compatible change that does not change the YANG module + semantics in any way. + YANG schema: The combined set of schema nodes for a set of YANG module revisions, + taking into consideration any deviations and enabled features. + versioned schema: A YANG schema with an associated YANG semantic version number, e.g., + as might be described by a YANG package. + schema set: A set of related versioned YANG schema, one for each datastore that is + supported. + + + TODO - the bc/nbc/editorial terminology should probably be defined and referenced from the + YANG module versioning solution draft. 'schema' and 'versioned schema' could be defined in the + packages draft. +
+
+ This document describes how NETCONF and RESTCONF clients can choose a particular YANG schema + they wish to choose to interact with a server with. + + defines requirements that any + solution to YANG versioning must have. + + specifies a partial solution to the YANG + versioning requirements that focuses on using semantic versioning within individual YANG + modules, but does not address all the requirements listed in the requirements draft. Of + particular relevance here, requirements 3.1 and 3.2 are not addressed. + + describes how sets of related YANG + modules can be grouped together into a logical entity that is versioned using the YANG + semantic versioning number scheme. Different packages can be defined for different sets of + YANG modules, e.g., packages could be defined for the IETF YANG modules, OpenConfig YANG + modules, a vendor's YANG modules. Different versions of these package definitions can be + defined as the contents of these packages evolve over time, and as the versions of the YANG + modules included in the package evolve. + + This draft defines how YANG packages can be used to represent versioned datastore schema, + and how clients can choose which versioned schemas to use during interactions with a + device. +
+
+ There are three ways that the lifecycle of a data model can be managed: + + Disallow all non-backwards-compatible updates to a YANG module. Broadly this is the + approach adopted by , but it has been shown to be too inflexible in + some cases. E.g. it makes it hard to fix bugs in a clean fashion - it is not clear that + allowing two independent data nodes (one deprecated, one current) to configure the same + underlying property is robustly backwards compatible in all scenarios, particularly if the + value space and/or default values differ between the module revisions. + + Allow non-backwards-compatible updates to YANG modules, and use a mechanism such as + semantic version numbers to communicate the likely impact of any changes to module users, + but require that clients handle non-backwards-compatible changes in servers by migrating to + new versions of the modules. Without version selection, this is what the approach likely achieves. + + Allow non-backwards-compatible updates to YANG modules, but also provide mechanisms to + allow servers to support multiple versions of YANG modules, and provide clients with some + ability to select which versions of YANG modules they wish to interact with, subject to some + reasonable constraints. This is the approach that this draft aims to address. It is worth + noting that the idea of supporting multiple versions of an API is not new in the wider + software industry, and there any many examples of where this approach has been successfully + used. + + +
+ +
+ The goals of the schema version selection draft are: + + To provide a mechanism where non-backwards-compatible changes and bug fixes can be made + to YANG modules without forcing clients to immediately migrate to new versions of those + modules as they get implemented. + + To allow servers to support multiple versions of a particular YANG schema, and to allow + clients to choose which YANG schema version to use when interoperating with the server. The + aim here is to give operators more flexibility as to when they update their software. + + To provide a mechanism to allow different YANG schema families (e.g., SDO models, + OpenConfig models, Vendor models) to be supported by a server, and to allow clients to + choose which YANG schema family is used to interoperate with the server. + + + + The following points are non objective of this draft: + + This draft does not provide a mechanism to allow clients to choose arbitrary sets of YANG + module versions to interoperate with the server. + + Servers are not required to concurrently support clients using different YANG schema families + or versioned schema. A server MAY choose to only allow a single schema family or single + versioned schema to be used by all clients. + + There is no requirement for a server to support every published version of a YANG + package, particularly if some package versions are backwards compatible. Clients are + required to interoperate with backwards compatible updates of YANG modules. E.g., if a + particular package was available in versions 1.0.0, 1.1.0, 1.2.0, 2.0.0, 3.0.0 and 3.1.0, + then a server may choose to only support versions 1.2.0, 2.0.0, and 3.1.0, with the + knowledge that all clients should be able to interoperate with the server. + + There is no requirement to support all parts of all versioned schemas. For some nbc + changes in modules, it is not possible for a server to support both the old and new module + versions, and to convert between the two. Where appropriate deviations can be used, and + otherwise an out of band mechanism is used to indicate where a mapping has failed. + + +
+ +
+ An overview the solution is as follows: + + YANG packages are defined for the different versioned schema supported by a server: + + Separate packages can be defined for different families of schema, e.g., SDO, + OpenConfig, or vendor native. + Separate packages can be defined for each versioned schema within a schema family. + Separate packages may be defined for different datastores, if the datastores use + different datastore schema. For example, a different datastore schema, and hence package, + might be used for <operational> vs the conventional datastores. + + Each server advertises, via an operational data model: + + All of the YANG packages that may be used during version selection. The packages can + also be made available for offline consumption via instance data documents, as described + in . + Grouped sets of versioned schema, where each set defines the versioned schema used by + each supported datastore, and each versioned schema is represented by a YANG package + instance. + + Each server supports configuration to: + + Allow a client to configure which schema version set to use for the default + NETCONF/RESTCONF connections. + Allow a client to configure additional separate NETCONF and RESTCONF protocol + instances, which use different schema version sets on those protocol instances. + An RPC mechanism could also be defined to select schema, but is not currently discussed + in this draft. + + The server internally maps requests between the different protocol instances to the + internal device implementation. + + +
+
+ The general premise of this solution is that servers generally implement one native schema, + and the version selection scheme is used to support older version of that native schema and also + foreign schema specified by external entities. + Overall the solution relies on the ability to map instance data between different schema + versions. Depending on the scope of difference between the schema versions then some of these + mappings may be very hard, or even impossible, to implement. Hence, there is still a strong + incentive to try and minimize nbc changes between schema versions to minimize the mapping + complexity. + Server implementations MUST serialize configuration requests across the different schema. + The expectation is that this would be achieved by mapping all requests to the devices native + schema version. + Datastore validation needs to be performed in two places, firstly in whichever schema a + clients is interacting in, and secondly in the native schema for the device. This could have a + negative performance impact. + Depending on the complexity of the mappings between schema versions, it may be necessary for + the mappings to be stateful. + TODO - Figure out how hot fixes that slightly modify the schema are handled. +
+
+ Clients can use configuration to choose which schema sets are available. + Clients cannot choose arbitrary individual YANG module versions, and are instead constrained + by the versions that the server makes available. + Each client protocol connection is to one particular schema set. From that client session + perspective it appears as if the client is interacting with a regular server. If the client + queries YANG library that the version of YANG Library that is returned matches the schema set + that is being used for that server instance. + The server may not support a schema with the exact version desired by the client, and they + have to accept a later version that is backwards compatible with their desired version. + Clients may also have to accept later schema versions that contain NBC fixes, although the + assumption is that such nbc fixes should be designed to minimize the impact on clients. + There is no guarantee that servers will always be able to support all older schema + versions. Deviations should be used where necessary to indicate that the server is unable to + faithfully implement the older schema version. + If clients interact with a server using multiple versions, they should not exact that all + data nodes in later module versions can always be backported to older schema versions. TODO - + Specify how mapping errors can be reported to client. + +
+
+ Not all schema conversions are possible. E.g. an impossible type conversion, or something + has been removed. The solution is fundamentally limited by how the schemas actually change, + this solution does not provide a magic bullet that can solve all versioning issues. +
+
+ The YANG schema version selection YANG module is used by a device to report the schema-sets + that are available, and to allow clients to choose which schema-set they wish to use. + Feature are used to allow servers to decide whether they allow the primary schema-set to be + changed, and/or allow secondary schema-sets to be configured. + The primary schema-set is the datastore schema reported by YANG Library if a client + connects to the device using the standard NETCONF/RESTCONF protocol numbers. + If secondary schema-sets are configured, then the client can choose whether NETCONF or + RESTCONF is supported, which port numbers the protocols should run on (if available), and what + RESTCONF root path prefix to use (e.g. if all of the RESTCONF protocol instances run on port + 443. + Different schema-sets may support different datastores. + +
+ The "ietf-schema-version-selection" YANG module has the following structure: + + /yanglib:yang-library/pkg:package/name + | +--ro version? leafref + +--rw default-schema-set? + -> /schema-selection/schema-sets/name + {default-schema-set}? + ]]> + +
+
+ +
+ The YANG module definition for the module described in the previous sections. +
+ + file "ietf-schema-version-selection@2019-03-11.yang" +module ietf-schema-version-selection { + yang-version 1.1; + namespace + "urn:ietf:params:xml:ns:yang:ietf-schema-version-selection"; + prefix "ver-sel"; + + import ietf-inet-types { + prefix inet; + reference "RFC 6991: Common YANG Data Types."; + } + import ietf-datastores { + prefix ds; + reference + "RFC 8342: Network Management Datastore Architecture (NMDA)"; + } + import ietf-yang-library { + prefix yanglib; + reference "RFC 8525: YANG Library"; + } + import ietf-yang-library-packages { + prefix pkg; + reference "draft-rwilton-netmod-yang-packages-01"; + } + + organization + "IETF NETMOD (Network Modeling) Working Group"; + + contact + "WG Web: + WG List: + + Author: Reshad Rahman + + + Author: Rob Wilton + "; + + description + "This module provide a data model to advertise and allow the + selection of schema versions by clients. + + Copyright (c) 2019 IETF Trust and the persons identified as + authors of the code. All rights reserved. + + Redistribution and use in source and binary forms, with or + without modification, is permitted pursuant to, and subject + to the license terms contained in, the Simplified BSD License + set forth in Section 4.c of the IETF Trust's Legal Provisions + Relating to IETF Documents + (http://trustee.ietf.org/license-info). + + This version of this YANG module is part of RFC XXXX; see + the RFC itself for full legal notices."; + + // RFC Ed.: update the date below with the date of RFC publication + // and remove this note. + // RFC Ed.: replace XXXX with actual RFC number and remove this + // note. + revision 2019-03-11 { + description + "Initial revision"; + reference + "RFC XXXX: YANG Schema Version Selection"; + } + + /* + * Typedefs + */ + + typedef yang-sem-ver { + type string { + pattern '\d+[.]\d+[.]\d+[mM]?'; + } + description + "Represents a YANG semantic version number."; + reference + "TODO - Should be defined by YANG versioning types module"; + } + + feature "default-schema-set" { + description + "Feature that allows clients to choose the default schema set + to be used for clients that connect using the standard network + configuration protocol port number or URL. + + Implementations may choose to only support this feature in + to report the default-schema-set without + allowing it to be configured."; + } + + feature "secondary-schema-set" { + description + "Feature to choose if secondary schema sets may be configured + by clients. + + Implementations may choose to only support this feature in + to report secondary schema sets without + allowing them to be configured."; + } + + container schema-selection { + description + "YANG schema version selection"; + + list schema-sets { + key "name"; + + description + "All schema-sets that are available for client selection."; + + leaf name { + type "string" { + length "1..255"; + } + description + "The server assigned name of the schema-set. + + This should include the schema family, and appropriate + versioning or release information"; + } + + container netconf { + if-feature "secondary-schema-set"; + + presence "Make this schema-set available via NETCONF"; + description + "NETCONF protocol settings for this schema set, if + available"; + + leaf port { + type inet:port-number; + description + "The port numnber to use for interacting with this + schema-set. If not configured,then the port number is + server allocated."; + reference + "RFC 6242: Using the NETCONF Protocol over SSH"; + } + } + + container restconf { + if-feature "secondary-schema-set"; + + presence + "Make this schema-set available via RESTCONF"; + description + "RESTCONF protocol settings for this schema set, if + available"; + + leaf port { + type inet:port-number; + default "443"; + description + "The port numnber to use for interacting with this + schema-set. If not configured, then the port number + defaults to the standard RESTCONF https port number of + 443"; + reference + "RFC 8040: RESTCONF Protocol, section 2.1"; + } + + leaf root-path { + type inet:uri; + default "/restconf"; + description + "The default root path to use to access the RESTCONF + protocol instance for this schema-set"; + + } + } + + list datastores { + key "datastore"; + config false; + + description + "The list of datastores supported for this schema set"; + + leaf datastore { + type ds:datastore-ref; + description + "The datastore that this datastore schema is associated + with"; + reference + "RFC 8342: Network Management Datastore Architecture + (NMDA)"; + } + + container package { + description + "YANG package associated with this datastore schema"; + + leaf name { + type leafref { + path "/yanglib:yang-library/pkg:package/pkg:name"; + } + description + "The name of the YANG package this schema relates to"; + } + leaf version { + type leafref { + path '/yanglib:yang-library/' + + 'pkg:package[pkg:name = current()/../name]/' + + 'pkg:version'; + } + + description + "The version of the YANG package this schema relates + to"; + } + } + } + } + + leaf default-schema-set { + if-feature "default-schema-set"; + type leafref { + path '/schema-selection/schema-sets/name'; + } + description + "Specifies the default schema-set used by this device. This + is the set of datastore schema that is used if a client + connects using the standard protocol port numbers and URLs"; + } + } +} + +]]> + +
+
+ +
+ To be defined. +
+
+ TODO - Add registrations for YANG modules defined in this draft. +
+
+ All issues, along with the draft text, are currently being + tracked at: + TODO - URL +
+
+ The ideas that formed this draft are based on discussions with the YANG versioning design + team, and other members of the NETMOD WG. +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/yang-ver-selection/ietf-schema-version-selection.yang b/yang-ver-selection/ietf-schema-version-selection.yang new file mode 100644 index 0000000..65ea6d4 --- /dev/null +++ b/yang-ver-selection/ietf-schema-version-selection.yang @@ -0,0 +1,225 @@ +module ietf-schema-version-selection { + yang-version 1.1; + namespace + "urn:ietf:params:xml:ns:yang:ietf-schema-version-selection"; + prefix "ver-sel"; + + import ietf-inet-types { + prefix inet; + reference "RFC 6991: Common YANG Data Types."; + } + import ietf-datastores { + prefix ds; + reference + "RFC 8342: Network Management Datastore Architecture (NMDA)"; + } + import ietf-yang-library { + prefix yanglib; + reference "RFC 8525: YANG Library"; + } + import ietf-yang-library-packages { + prefix pkg; + reference "draft-rwilton-netmod-yang-packages-01"; + } + + organization + "IETF NETMOD (Network Modeling) Working Group"; + + contact + "WG Web: + WG List: + + Author: Reshad Rahman + + + Author: Rob Wilton + "; + + description + "This module provide a data model to advertise and allow the + selection of schema versions by clients. + + Copyright (c) 2019 IETF Trust and the persons identified as + authors of the code. All rights reserved. + + Redistribution and use in source and binary forms, with or + without modification, is permitted pursuant to, and subject + to the license terms contained in, the Simplified BSD License + set forth in Section 4.c of the IETF Trust's Legal Provisions + Relating to IETF Documents + (http://trustee.ietf.org/license-info). + + This version of this YANG module is part of RFC XXXX; see + the RFC itself for full legal notices."; + + // RFC Ed.: update the date below with the date of RFC publication + // and remove this note. + // RFC Ed.: replace XXXX with actual RFC number and remove this + // note. + revision 2019-03-11 { + description + "Initial revision"; + reference + "RFC XXXX: YANG Schema Version Selection"; + } + + /* + * Typedefs + */ + + typedef yang-sem-ver { + type string { + pattern '\d+[.]\d+[.]\d+[mM]?'; + } + description + "Represents a YANG semantic version number."; + reference + "TODO - Should be defined by YANG versioning types module"; + } + + feature "default-schema-set" { + description + "Feature that allows clients to choose the default schema set + to be used for clients that connect using the standard network + configuration protocol port number or URL. + + Implementations may choose to only support this feature in + to report the default-schema-set without + allowing it to be configured."; + } + + feature "secondary-schema-set" { + description + "Feature to choose if secondary schema sets may be configured by + clients. + + Implementations may choose to only support this feature in + to report secondary schema sets without + allowing them to be configured."; + } + + container schema-selection { + description + "YANG schema version selection"; + + list schema-sets { + key "name"; + + description + "All schema-sets that are available for client selection."; + + leaf name { + type "string" { + length "1..255"; + } + description + "The server assigned name of the schema-set. + + This should include the schema family, and appropriate + versioning or release information"; + } + + container netconf { + if-feature "secondary-schema-set"; + + presence "Make this schema-set available via NETCONF"; + description + "NETCONF protocol settings for this schema set, if + available"; + + leaf port { + type inet:port-number; + description + "The port numnber to use for interacting with this + schema-set. If not configured, then the port number is + server allocated."; + reference + "RFC 6242: Using the NETCONF Protocol over SSH"; + } + } + + container restconf { + if-feature "secondary-schema-set"; + + presence + "Make this schema-set available via RESTCONF"; + description + "RESTCONF protocol settings for this schema set, if + available"; + + leaf port { + type inet:port-number; + default "443"; + description + "The port numnber to use for interacting with this + schema-set. If not configured, then the port number + defaults to the standard RESTCONF https port number of + 443"; + reference + "RFC 8040: RESTCONF Protocol, section 2.1"; + } + + leaf root-path { + type inet:uri; + default "/restconf"; + description + "The default root path to use to access the RESTCONF + protocol instance for this schema-set"; + + } + } + + list datastores { + key "datastore"; + config false; + + description + "The list of datastores supported for this schema set"; + + leaf datastore { + type ds:datastore-ref; + description + "The datastore that this datastore schema is associated + with"; + reference + "RFC 8342: Network Management Datastore Architecture + (NMDA)"; + } + + container package { + description + "YANG package associated with this datastore schema"; + + leaf name { + type leafref { + path "/yanglib:yang-library/pkg:package/pkg:name"; + } + description + "The name of the YANG package this schema relates to"; + } + leaf version { + type leafref { + path '/yanglib:yang-library/' + + 'pkg:package[pkg:name = current()/../name]/' + + 'pkg:version'; + } + + description + "The version of the YANG package this schema relates to"; + } + } + } + } + + leaf default-schema-set { + if-feature "default-schema-set"; + type leafref { + path '/schema-selection/schema-sets/name'; + } + description + "Specifies the default schema-set used by this device. This + is the set of datastore schema that is used if a client + connects using the standard protocol port numbers and URLs"; + } + } +}