Subject: [Netmod-ver-dt] new version-selection draft text for changing schemas

From: "Sterne, Jason (Nokia - CA/Ottawa)" <[email-masked]>
Date: Tue, 25 Feb 2020 23:07:31 +0000

Hi all,

I had the action to look at the schema selection draft and propose text to describe a few scenarios of changing schemas without using any RPC.

Here is a proposed new section 5.6:

5.6.  Changing schema-sets

The selection of a schema-set by one client X does not change the schema-set in use by any other client Y, and does not affect the data returned to client Y (e.g. a get-data request by client Y, before and after client X selects a schema-set, SHOULD return the same data). Schema selection by a client only affects the schema being used between the server and that specific client (on that specific session in the case of NETCONF).

The schema-set being used in a NETCONF session is established at the start of the session and never changes for the duration of the session. If the server can no longer support the schema-set in use in a NETCONF session, then it MUST disconnect the session.  Similarly a RESTCONF server should error if a request attempts to use a schema-set that is not currently supported.

Here is a simple example of a NETCONF client migrating to a new schema-set with a server that has multiple schema-sets in the 'selectable' leaf-list:
1. disconnect the current session
2. reconnect and select a new schema-set from the 'selectable' leaf-list

If a server, for example, only supports a single schema-set at a time by only allowing a single entry in the 'selectable' leaf-list (the default), then a change of the schema-set in the 'selectable' leaf-list (and default) would cause all previously established NETCONF sessions (using the previous 'selectable' schema-set) to be disconnected.

If a server only supports a single schema-set at a time (across all sessions), a NETCONF client can migrate to a new schema-set by using the following sequence of steps:
1. Configure a new schema-set in the 'selectable' leaf-list, remove the old schema-set, and set the 'default' leaf to that new schema-set. Other configuration can also be done in the same request (using the current schema-set in use on the session).
2. The server will process the request and then disconnect the session (since the current schema-set of the session can no longer be supported). All other NETCONF sessions would also be disconnected at this point.
3. The client reconnects using the new schema-set (either by selecting it during capability exchange, or by using no selection and relying on the new default schema-set)
4. The client can then optionally send a complete new configuration using the new schema (i.e. if the client knows that the server can't perfectly convert everything from the old schema to the new schema)

If a server supports multiple schema-sets in parallel, but a client removes a schema-set that is in use on a NETCONF session from the 'selectable' leaf-list, then TBD:
option 1: then any NETCONF sessions that were using that schema-set are disconnected, or
option 2: then any NETCONF sessions that were using that schema-set remain connected, but no new NETCONF sessions can use the schema-set that was removed from the 'selectable' leaf-list. If the server can only support a limited number of schema-sets in parallel, and the maximum number of schema-sets are currently in use, and a new NETCONF session attempts to use a new valid schema-set (exceeding the maximum number of parallel schema-sets), then TBD  (disconnect those old NETCONF sessions that are using a schema-set that was removed from 'selectable', or block the new NETCONF session?)
TBD: leave this entire last paragraph as implementation specific?

Should I take a stab at other key scenarios?

---

From: "Rob Wilton (rwilton)" <[email-masked]>
Date: Wed, 26 Feb 2020 17:05:06 +0000

Hi Jason,

I think that this text looks good, but I wonder whether most of it would fit better under the "Schema selection for clients" section, since it mostly framed about what a client would do/experience?

Here is the updated text in the doc, I've also put some comments inline about what I have done:

5.4.  Schema selection protocol operations

5.4.1.  NETCONF

   The schema-set being used in a NETCONF session is established at the
   start of the session through the exchange of capabilities and never
   changes for the duration of the session.  If the server can no longer
   support the schema-set in use in a NETCONF session, then it MUST
   disconnect the session.

5.4.1.1.  schema-sets NETCONF capability

....

5.4.2.  RESTCONF

   For RESTCONF, schema-sets are chosen via use of their name in the

   request path.

   If the chosen schema-set is not available then the SERVER MUST fail

   the operation and return an XXX error.

...

7.  Schema selection from a client perspective

   Clients can use configuration to choose which schema-sets are

   available for selection.

   Clients cannot choose arbitrary individual YANG module versions, and

   are instead constrained by the versions that the server makes

   available via schema-sets.

   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 using the selected schema.  If the

   client queries YANG library, then the version of YANG Library that is

   returned matches the schema-set that has been selected by the client.

   The selection of a schema-set by a client MUST NOT change the

   behavior of other clients connected using a different schema set.

   The server may not support a schema with the exact version desired by

   the client, and the client may have to choose 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

Wilton, et al.           Expires August 29, 2020               [Page 11]

Internet-Draft            YANG Schema Selection            February 2020

   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 expect 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.

7.1.  Examples

   Here is a simple example of a NETCONF client migrating to a new

   schema-set with a server that has multiple schema-sets in the

   'selectable' leaf-list:

   1.  Disconnect the current session

   2.  Reconnect and select a new schema-set from the 'selectable' leaf-

       list

   If a server, for example, only supports a single schema-set at a time

   by only allowing a single entry in the 'selectable' leaf-list (the

   default), then a change of the schema-set in the 'selectable' leaf-

   list (and default) would cause all previously established NETCONF

   sessions (using the previous 'selectable' schema-set) to be

   disconnected.

   If a server only supports a single schema-set at a time (across all

   sessions), a NETCONF client can migrate to a new schema-set by using

   the following sequence of steps:

   1.  Configure a new schema-set in the 'selectable' leaf-list, remove

       the old schema-set, and set the 'default' leaf to that new

       schema-set.  Other configuration can also be done in the same

       request (using the current schema-set in use on the session).

   2.  The server will process the request and then disconnect the

       session (since the current schema-set of the session can no

       longer be supported).  All other NETCONF sessions would also be

       disconnected at this point.

   3.  The client reconnects using the new schema-set (either by

       selecting it during capability exchange, or by using no selection

       and relying on the new default schema-set).

Wilton, et al.           Expires August 29, 2020               [Page 12]

Internet-Draft            YANG Schema Selection            February 2020

   4.  The client can then optionally send a complete new configuration

       using the new schema (i.e. if the client knows that the server

       can't perfectly convert everything from the old schema to the new

       schema).

Some comments inline ...

From: Netmod-ver-dt <[email-masked]> On Behalf Of Sterne, Jason (Nokia - CA/Ottawa)
Sent: 25 February 2020 23:08
To: [email-masked]
Subject: [Netmod-ver-dt] new version-selection draft text for changing schemas

Hi all,

The selection of a schema-set by one client X does not change the schema-set in use by any other client Y, and does not affect the data returned to client Y (e.g. a get-data request by client Y, before and after client X selects a schema-set, SHOULD return the same data). Schema selection by a client only affects the schema being used between the server and that specific client (on that specific session in the case of NETCONF).
[RW]
I might reword this to, and add it into the server perspective section:
The selection of a schema-set by a client MUST NOT change the behavior of other clients connected using a different schema set.

The schema-set being used in a NETCONF session is established at the start of the session and never changes for the duration of the session. If the server can no longer support the schema-set in use in a NETCONF session, then it MUST disconnect the session.  Similarly a RESTCONF server should error if a request attempts to use a schema-set that is not currently supported.
[RW]
I've split these and add these into the NETCONF and RESTCONF sections.

[RW]
I've added these examples to a new subsection under the "Schema section from a client perspective"

[RW]
I think that we can leave this paragraph out.

In fact, I think that the behavior is covered by "If the server can no longer support the schema-set in use in a NETCONF session, then it MUST disconnect the session"

Should I take a stab at other key scenarios?
[RW]
What other scenarios are you thinking of?

Thanks,
Rob

---

From: "Sterne, Jason (Nokia - CA/Ottawa)" <[email-masked]>
Date: Wed, 26 Feb 2020 19:50:46 +0000

Thx. Pls see inline.
Jason

From: Rob Wilton (rwilton) <[email-masked]>
Sent: Wednesday, February 26, 2020 12:05 PM
To: Sterne, Jason (Nokia - CA/Ottawa) <[email-masked]>; [email-masked]
Subject: RE: new version-selection draft text for changing schemas

Hi Jason,

[>>JTS: ] Sounds good.

5.4.1.  NETCONF

....

5.4.2.  RESTCONF

   request path.

[>>JTS: ] change SERVER to lowercase

...

   available for selection.

[>>JTS: ] That implies it *can* change the behaviour of clients connected using the same schema-set.  How about this:

The selection of a schema-set by a client MUST NOT change the behaviour of the server experienced by other clients. For example, the get-data response to one client MUST be the same before and after another client selects a schema-set.

   the impact on clients.

   schema version.

7.1.  Examples

   'selectable' leaf-list:

       list

   disconnected.

       schema).

Some comments inline ...

From: Netmod-ver-dt <[email-masked]<mailto:[email-masked]>> On Behalf Of Sterne, Jason (Nokia - CA/Ottawa)
Sent: 25 February 2020 23:08
To: [email-masked]<mailto:[email-masked]>
Subject: [Netmod-ver-dt] new version-selection draft text for changing schemas

Hi all,

[RW]

In fact, I think that the behavior is covered by "If the server can no longer support the schema-set in use in a NETCONF session, then it MUST disconnect the session"
[>>JTS: ] It is *somewhat* covered but doesn't really address whether option 1 or option 2 should be followed in the case above. But I'm also OK just *not* standardizing the behavior for this corner case.

Should I take a stab at other key scenarios?
[RW]
What other scenarios are you thinking of?
[>>JTS: ] None came to mind. Just checking if someone had another key scenario in mind that we should document to clarify our intended behavior.

Thanks,
Rob

---

From: "Rob Wilton (rwilton)" <[email-masked]>
Date: Thu, 27 Feb 2020 11:13:14 +0000

Hi Jason,

Please see [RW2] inline.

From: Sterne, Jason (Nokia - CA/Ottawa) <[email-masked]>
Sent: 26 February 2020 19:51
To: Rob Wilton (rwilton) <[email-masked]>; [email-masked]
Subject: RE: new version-selection draft text for changing schemas

Thx. Pls see inline.
Jason

From: Rob Wilton (rwilton) <[email-masked]<mailto:[email-masked]>>
Sent: Wednesday, February 26, 2020 12:05 PM
To: Sterne, Jason (Nokia - CA/Ottawa) <[email-masked]<mailto:[email-masked]>>; [email-masked]<mailto:[email-masked]>
Subject: RE: new version-selection draft text for changing schemas

Hi Jason,

5.4.1.  NETCONF

....

5.4.2.  RESTCONF

   request path.

[RW2]
Thanks.  Fixed.

...

   available for selection.

[RW2]

Okay.

   the impact on clients.

   schema version.

7.1.  Examples

   'selectable' leaf-list:

       list

   disconnected.

       schema).

Some comments inline ...

Hi all,

[RW]

[RW2]
I've just opened an issue to track this.  In my opinion I think that option 1 is the right and obvious choice.  I.e. at all times, all clients must be using a schema listed in the selectables list (which can never be empty), and they are kicked off if the schema that they are using is every removed from that list.

[RW2]
Okay, I will try and finish example 2 today, merge in the other updates, and then post an updated version for folks to either ack or comment on.

Thanks,
Rob