Re: [netmod] Comments on draft-ma-netmod-immutable-flag-06

[Kent Watsen <[e-mail]>]

Hi Qiufang,

> I support ensuring XC/Y remains transactional, such that a client can always move from valid config-A to valid config-B in a single update.  I also support requiring a "with-immutable" flag in client-requests in order for the "immutable" annotations to be returned (like "with-defaults").
> Using an explicit parameter (e.g., with-immutable) avoids the case the client receives an "immutable" annotation yet doesn’t really understand that(clients don’t understand this annotation doesn’t even explicitly ask the server to return this). I agree that could be useful and should be added in the next version. I think this "with-immutable" flag should be supported even when a client retrieves a read-only target datastore (e.g., <system> or <operational>), though immutability only refers to restrictions on read-write datastores.

I think that it is undesirable to support the "with-immutable" request parameter on non-configuration datastores.  The reason why is that I believe the "with-origin" flag is more useful.  If the "origin" is "system", then immutability is "true".

PS: there's an open-question as to if "with-immutable" also returns the "immutable" flag for nodes described as immutable in the YANG schema.  I think that the flags should be returned for all nodes regardless by default so that there is single source of truth.  That said, I'm open to the idea of the "with-immutable" parameter taking an argument specifying how much to return.


> Any issues with the following statements?
>  
> 1) Only the server can create/change/delete `immutable` data, which is seen in the <operational> and <system> datastores by default.  Clients are merely making immutable nodes visible/invisible in <running/start/candidate>.  If the client does not make a system-defined node visible in <running>, the node still exists in <operational> and <system>.
> Among the common cases we see now are immutable data that is generated by system, and cannot be changed by the client. So the statement seems true for me.
> I am unsure if there would be a case like a client creates a node instance but cannot modify that afterwards. That way it will not be present in <system> and the client may also be allowed to delete that. We used to have a BGP AS number case for that in previous version (https://datatracker.ietf.org/doc/html/draft-ma-netmod-immutable-flag-05#appendix-A.5)  but that is not a good practice and it was removed.

The "client creates a node instance but cannot modify that afterwards" (unless the parent is deleted?) case seems to be exactly the non-transactional example we are trying to avoid, agreed?   This definition (#1) essentially guarantees transactionality, since there is nothing clients can do to alter what the system considers immutable.   A node is immutable if and only if system-defined.

FWIW, it may be possible for NACM to be non-transaction.  For instance, a client-removing their own access to NACM, which would be irreversible by that client.  But this is a corner-case, and one a server should guard against occurring. 



> 2) The "immutable" YANG extension statement (not the metadata annotation) designates, at the schema-level, config=true nodes that, when present in <running/startup/candidate>, are system-defined and hence immutable.  
> Note that NMDA does allow clients to create an interface entry with an interface-type value which is not yet physically present. Only when the interface physically appears, the type cannot be modified with another value not matching the real value the device is actually in use.

A temporal nature is at play here.

1) when the client sets the config when the card is installed, the system can fail the request if it affects any "immutable" nodes (non-matching values).   [PS: it is assumed that, for this case, the metadata annotation (not the YANG extension), would be used.]

2) However, if the card is not installed, the client could put non-matching values for the "immutable" parts, and the server would have no way to validate it, and hence the server would, presumably, allow the update to <running>.  When the card is later installed, the interface would appear in <operational>, and <system> if supported.  At that time the non-matching value would be discovered.  Presumably the system would 1) ignore the non-matching config from <running>, 2) send an alert that <running> is invalid, and 3) force the next commit to <running> to correct the non-matching values.

Is this what you are focusing on?


> 3) The "immutable" metadata annotation (not the YANG extension) designates, at the instance-level, config=true nodes that, when present in <running/startup/candidate>, are system-defined and hence immutable.    The metadata annotation is only needed to support config=true YANG lists that can contain a mix of client- and system- defined entries.
> There is no such a case like a client creates several instances some of which are immutable while others are mutable. Generally I agree that “The metadata annotation is only needed to support config=true YANG lists that can contain a mix of client- and system- defined entries.” Which I believe is the most common.
> Notice that leaf-list is not mentioned, cannot a particular leaf-list instance be immutable?

Leaf-list is not mentioned because I wrongly thought that RFC7952 couldn't set metadata on a per leaf-list entry basis in the JSON encoding.  But I see that it can and so, you're right, `leaf-list` should be treated the same as `leaf` in this statement.



> It seems to me all three above statements target that all immutable configuration are system-defined. But I assume some configuration may also be created by the client, e.g., interface type and BGP peer cases documented in the document. Thoughts?


Exactly the intention.  By having "immutable if and only if system-defined", regardless if the <system> datastore is implemented or not, transactionality is ensured.

IDK what "interface-type" case you refer to, but I assume the "BGP peer" case is UC5.  For UC5, my understanding (assuming recursively toggle-able "immutable" flag described before), is that both `container bgp` and `list neighbor` would be "immutable false", while `leaf peer-type` would be "immutable true".  Does that make sense?

PS: I assume the YANG extension would be used since the immutability of `leaf peer-type` seems to be independent of any instance.  Also makes sense?



> 4) The definition for the "immutable" flag means is identical whether it is specified via the YANG extension or the metadata annotation.   Corollary: the "immutable" flag can only be used on data-nodes (e.g., not on "choice", "case", or "grouping").
> Agree that it is a data node property, unless we define specifically what it means to use immutable flag on statements like choice/case/grouping, but I see it as out of scope for now.

Good.



> A couple more musings:
> 
> 
> 1) I wonder if "immutable" should be a boolean that is "false" by default, but can be explicitly set to "false" if it is a descendent of a "immutable=true" node.  That is, to let immutability be recursive but toggle-able.
> If I understand you correctly, Kent, you’re proposing something similar to https://datatracker.ietf.org/doc/html/draft-ma-netmod-immutable-flag-06#section-3.2 except that im:immutable is changed to a Boolean type and of value “false” if not specified. That makes sense to me, if we agree that immutable should be a substatement to a "config true" leaf, leaf-list, container, list, anydata or anyxml statement rather than only terminal node like leaf or leaf-list.

I disagree that only terminal nodes should be immutable.  For starters, consider an immutable presence container.   

Also, with JUNOS's immutable list of "applications" that are referenced by security policies, there are hundreds of them.  Surely the entire list should be marked as immutable in the schema.


> 2) I wonder if *what* the "immutable" flag means should be defined per data-type.  For instance:
>  
>     When a "leaf" node is immutable:
>  
>           - its value cannot change.
> Yes, it’s quite easy.
>     When a "leaf-list" node is immutable:
>  
>          - its value cannot change.
>  
>          - If specified at the schema-level, "ordered-by user"
>            is invalid, because reordering changes the value.
> My understanding is that,
> ·         if a leaf-list node is specified “immutable” at the schema-level, any leaf-list entries can neither be created or deleted. That means totally read-only to clients/users and I also agree that “ordered-by user” is invalid in this case. 
> ·         if a specific leaf-list entry is specified “immutable” at the instance-level, only that specific entry cannot be deleted. Metadata annotation is only applied to existing instance, so the client can add/insert new entries; other entries without immutable flag can also be deleted.
> Is this consistent with what you have in mind?

I stand corrected.  Please see above regarding RFC 7952 JSON encoding for leaf-list.  This being the case, I would rewrite this definition as:

    When a "leaf-list" node (element) is immutable:
 
         - the value, for each element in the leaf-list, cannot change.
 
         - it is not possible to designate the leaf-list as a 
           whole as immutable, because the leaf-list itself
           doesn't exist as a node in the data-tree (and hence
           cannot be flagged as "immutable" in the response
           to a "with-immutable" request.
 
        - If it is desired to communicate that list-entries
          cannot be added/removed by clients, this is already
          the case as the leaf-list's `key` node(s) is immutable
          (i.e., clients cannot make up their own key values).

        - if it is desired to communicate that leaf-list entries
          cannot by reordered, the leaf-list must be "ordered-by system".
          Corollary: an "ordered-by user" leaf-list is never immutable.



>     When a "container" or "list" node is immutable:
>  
>           - all of its recursive descendants are "immutable=true"
>             unless toggled back to "immutable=false" by a
>             descendent node.
> Yes, unless otherwise specified, immutability is inherited downwards towards the terminal leaves.

Thanks for the confirmation.


>           - for lists, it is not possible to designate the list as a 
>             whole as immutable, because the list itself doesn't
>             exist as a node in the data-tree.
>  
>               - If it is desired to communicate that list-entries
>                 cannot be added/removed by clients, it is sufficient
>                 for the list's `key` node(s) to be immutable=true.
> I would rather see immutability of list the same way as leaf-list. That is, we do allow the list data node to be immutable at schema-level and it conveys that any list entry cannot be created and deleted, and likewise, “ordered-by user” is invalid in this case. I understand that list node may exist in multiple instances in the data tree but any issue you see with that?

I understand the desire.  My concern is that the `list` and `leaf-list` YANG nodes themselves do not exist in the data tree.  For example, in XML no parent-node exists and, in JSON, no metadata can be conveyed at that level.   Thus I'm hoping that all semantics can be conveyed in the "with-immutable" response, without the client having to also consult the YANG.   Maybe it's not worth it (i.e., XC/Y demands YANG-awareness) and your understanding prevails.  Either way is okay.


>               - if it is desired to communicate that a list-entries cannot
>                 by reordered, the list must be "ordered-by system".
>                 Corollary: an "ordered-by user" list is never immutable.
> By the way, if a specific list instance is specified as immutable at instance-level, can a user create a descendant node instance inside that list instance?

Yes, if the schema for the descendent node toggles "immutable" to "false" using the YANG-base extension - makes sense?


>     When a "anydata" or "anyxml" node is immutable
> 
> 
>           - the node, and all of its recursive descendants, if any, is/are
>             "immutable=true", unless toggled back to "immutable=false"
>             by a descendent node.
> Agree, I see it similar to a “container” node is immutable.


Yes.   One thing to note, though, is that since there is no schema for the decedents of an anydata/anyxml node, it is never possible for the "immutable" YANG extension to be used to declare up-front which parts of the anydata/anyxml may be immutable.  Of course, the metadata annotation could say, and maybe that is good enough.

 
> Best Regards,
> Qiufang


Kent