YANG Extension and Metadata Annotation for Immutable Flag

Abstract

This document defines a YANG extension named "immutable" to indicate that specific "config true" data nodes are not allowed to be created/deleted/updated. To indicate that specific entries of a list/leaf-list node or instances inside list entries cannot be updated/deleted after initialization, a metadata annotation with the same name is also defined. Any data node or instance marked as immutable is read-only to the clients of YANG-driven management protocols, such as NETCONF, RESTCONF and other management operations (e.g., SNMP and CLI requests).¶

This document aims to provide more visibility into immutability characteristic of particular schema or instance nodes by defining a standard mechanism to allow the server to document the existing immutable configuration data, while this doesn't mean attaching such restrictions is encouraged.¶

2. Overview

The "immutable" concept defined in this document only indicates write access restrictions to read-write datastores. A particular data node or instance MUST have the same immutability in all read-write datastores. The immutable annotation information should also be visible even in read-only datastores (e.g., <system>, <intended>, <operational>), however this only serves as information about the data node itself, but has no effect on the handling of the read-only datastore. The immutability property of a particular data node or instance MUST be protocol-independent and user-independent.¶

If a particular leaf-list node is marked as "immutable" without exceptions for "delete" in the schema, the server SHOULD NOT annotate its instances, as that provides no additional information. If a particular container/list/leaf/anydata/anyxml node is marked as "immutable" without exceptions for "delete" or "update" in the schema, the server SHOULD NOT annotate its instances, as that provides no additional information.¶

Already today the server rejects any attempt to the "create", "delete" or "update" access operations on an immutable configuration data. This document allows the existing immutable data node or instance to be marked by YANG extension or metadata annotation. Requests to create/update/delete an immutable configuration data always return an error (except the exceptions argument in YANG extension). The error reporting is performed immediately at an <edit-config> operation time, regardless what the target configuration datastore is. For an example of an "invalid-value" error response, see Appendix A.1.2.¶

However the following operations SHOULD be allowed:¶

• Use a create, update, delete/remove operation on an immutable node if the effective change is null. E.g., if a leaf has a current value of "5" it should be allowed to replace it with a value of "5";¶
• Create an immutable node with a same value initially set by the system if it doesn't exist in the datastore. E.g., it should be allowed to explicitly configure a system-defined interface name and type in <running> as the same values in <system>;¶
• Delete an immutable node in <running> which is instantiated in <system> and copied into <running>, unless the resource is no longer available (e.g., the interface removed physically), there is no way to actually delete system configuration from a server [I-D.ma-netmod-with-system], even if the node in the schema tree is declared as "immutable" without the exception for "delete".¶

Note that even if a particular data node is immutable without the exception for "delete", it still can be deleted with its parent node, e.g., /if:interfaces/if:interface/if:type leaf is immutable, but the deletion to the /if:interfaces/if:interface list entry is allowed; if a particular data node is immutable without the exception for "create", it means the client can never create the instance of it, regardless the handling of its parent node.¶

When a specific data node or instance is marked as "immutable", NACM cannot override this to allow create/delete/update access. Servers will ignore such NACM rule. For example, if a particular data node is marked as "im:immutable" without the "exceptions" argument for update, the server will ignore any user-defined NACM rule to allow update access operation to that specific data node.¶

Write access restriction due to general YANG rules has no need to be marked as immutable. For example, key leaf which is given a value when a list entry is created cannot be modified and deleted unless the list entry is deleted. A mandatory leaf MUST exist and cannot be deleted if the ancestor node exists in the data tree. Decorating the key leaf and mandatory leaf as immutable provides no additional information in these cases.¶

3. "Immutable" YANG Extension

The "immutable" YANG extension can be a substatement to a "config true" leaf, leaf-list, container, list, anydata or anyxml statement. It indicates that data nodes based on the parent statement are not allowed to be added, removed or updated except according to the exceptions argument. Any such write attempt will be rejected by the server.¶

The "immutable" YANG extension defines an argument statement named "exceptions" which gives a list of operations that users are permitted to invoke for the specified node.¶

The following values are supported for the "exceptions" argument:¶

• Create: allow users to create instances of the data node;¶
• Update: allow users to modify instances of the data node;¶
• Delete: allow users to delete instances of the data node.¶

If more than one value are intended, a space-separated string for the "exceptions" argument is used. For example, if the instance of a particular data node can always be created and modified, it cannot be deleted, the following "immutable" YANG extension with "create" and "update" exceptions could be defined in a substatement to that data node:¶

  im:immutable "create update";

Providing an empty string for the "exceptions" argument is equivalent to a single extension without an argument followed. Providing all 3 values has the same effect as not using this exceptions at all, but can be used anyway.¶

Note that leaf-list instances can be created and deleted, but not modified. Any exception for "update" operation to leaf-list data nodes SHOULD be ignored.¶

4. "Immutable" Metadata Annotation

The "immutable" flag is used to indicate the immutability of a particular instantiated data node. It only applies to the list/leaf-list entries or instances inside particular list entries. The values are boolean types indicating whether the data node instance is immutable or not.¶

Note that "immutable" metadata annotation is used to annotate instances of a list/leaf-list rather than schema nodes. For instance, a list node may exist in multiple instances in the data tree, "immutable" can annotate some of the instances as read-only, while others are not.¶

Any list/leaf-list instance annotated with immutable="true" is read-only to clients, which means that once an instance is created, the client cannot update/delete it. If a list entry is annotated with immutable="true", any contained descendant instances of any type (including leafs, lists, containers, etc.) inside the specific instance is not allowed to be created, updated and deleted without the need to annotate descendant nodes instances explicitly.¶

When the client retrieves a particular datastore, immutable data node instances MUST be annotated with immutable="true" by the server. If the "immutable" metadata annotation for a list/leaf-list entry is not specified, the default "immutable" value is false.¶

5. Inheritance of Immutability

Comment: This section tries to answer the questions : Is immutable inherited down the containment hierarchy? If it is, should we allow overriding the immutability of a particular contained element (i.e., to declare a contained data node as immutable=false inside an immutable container/list) ?¶

Unless otherwise specified, the immutability for data nodes is inherited from their parent nodes. The immutability in the hierarchy is inherited downwards towards the leaf/leaf-list nodes. Specifically, if a node has child elements, non-modification to that node means any child elements is not allowed to be create, update and delete. E.g., if a particular instance of a list node is not allowed to be updated, any descendant node instance is not allowed to be create, update and delete inside that list instance. In this case, there is no need to mark the descendant nodes as immutable.¶

For the following YANG example:¶

   list role {
     key name;
     leaf name {
       type string;
     }
     leaf-list granted-operation {
       type enumeration {
         enum read;
         enum write;
         enum execute;
         enum debug;
       }
     }
   }

A system-defined corresponding XML instance with immutable annotation example:¶

   <role im:immutable="rue">
     <name>owner</name>
     <granted-operation>read</granted-operation>
     <granted-operation>write</granted-operation>
     <granted-operation>execute</granted-operation>
     <granted-operation>debug</granted-operation>
   </role>

The role instance named "owner" is annotated with immutable="true", which means that this instance is not allowed to be updated and deleted, all of the child nodes are not allowed to be created, updated and deleted inside this instance. For example, if a client tries to delete an existing granted-operation "debug" inside the "owner" role in an <edit-config> operation, an "operation-not-supported" error is returned.¶

However, sometimes there is a desire to override the immutability of a particular contained node. For example, given the following list definition:¶

  list application {
    im:immutable "create delete";
    key name;
    leaf name {
      type string;
    }
    leaf protocol {
      type enumeration {
        enum tcp;
        enum udp;
      }
    }
    leaf port-number {
      im:immutable "update";
      type string;
    }
  }

Any list entries of the list node "application" is allowed to be created and deleted, but not modification. However, the contained leaf node "port-number" has the immutability with exception for "update" operation, this means that modification to the value of leaf node "port-number" inside "application" list instance is allowed.¶

6. YANG Module

<CODE BEGINS> file="ietf-immutable@2022-08-11.yang"
// RFC Ed.: replace XXXX with RFC number and remove this note
  module ietf-immutable {
    yang-version 1.1;
    namespace "urn:ietf:params:xml:ns:yang:ietf-immutable";
    prefix im;

    import ietf-yang-metadata {
      prefix md;
    }

    organization
      "IETF Network Modeling (NETMOD) Working Group";

    contact
      "WG Web: <https://datatracker.ietf.org/wg/netmod/>

       WG List: <mailto:netmod@ietf.org>

       Author: Qiufang Ma
               <mailto:maqiufang1@huawei.com>

       Author: Qin Wu
               <mailto:bill.wu@huawei.com>

       Author: Balazs Lengyel
               <mailto:balazs.lengyel@ericsson.com>

       Author: Hongwei Li
               <mailto:flycoolman@gmail.com>";

    description
      "This module defines a metadata annotation named 'immutable'
       to indicate the immutability of a particular instantiated
       data node. Any instantiated data node marked with
       immutable='true' by the server is read-only to the clients
       of YANG-driven management protocols, such as NETCONF,
       RESTCONF as well as SNMP and CLI requests.

       The module defines the immutable extension that indicates
       that data nodes based on data-definition statement cannot
       be added removed or updated except according to the
       exceptions argument.

       Copyright (c) 2022 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 Revised
       BSD License set forth in Section 4.c of the IETF Trust's
       Legal Provisions Relating to IETF Documents
       (https://trustee.ietf.org/license-info).

       This version of this YANG module is part of RFC HHHH
       (https://www.rfc-editor.org/info/rfcHHHH); see the RFC
       itself for full legal notices.

       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 (RFC 2119)
       (RFC 8174) when, and only when, they appear in all
       capitals, as shown here.";

    revision 2022-08-11 {
      description
        "Initial revision.";
      reference
        "RFC XXXX: YANG Extension and Metadata Annotation for Immutable Flag";
    }

    extension immutable {
      argument exceptions;
      description
        "The 'immutable' extension as a substatement to a data
         definition statement indicates that data nodes based on
         the parent statement MUST NOT be added, removed or
         updated by management protocols, such as NETCONF,
         RESTCONF or other management operations (e.g., SNMP
         and CLI requests) except when indicated by the
         exceptions argument.

         Immutable data MAY be marked as config true to allow
         'leafref', 'when' or 'must' constraints to be based
         on it.

         The statement MUST only be a substatement of the leaf,
         leaf-list, container, list, anydata, anyxml statements.
         Zero or one immutable statement per parent statement
         is allowed.
         No substatements are allowed.

         The argument is a list of operations that are
         permitted to be used for the specified node, while
         other operations are forbidden by the immutable extension.
         - create: allows users to create instances of the data node
         - update: allows users to modify instances of the data node
         - delete: allows users to delete instances of the data node

         To disallow all user write access, omit the argument;

         To allow only create and delete user access, provide
         the string 'create delete' for the 'exceptions' parameter.

         Providing all 3 parameters has the same effect as not
         using this extension at all, but can be used anyway.

         Equivalent YANG definition for this extension:

         leaf immutable {
           type bits {
             bit create;
             bit update;
             bit delete;
           }
           default '';
         }


         Adding immutable or removing values from the
         exceptions argument of an existing immutable statement
         are non-backwards compatible changes.
         Other changes to immutable are backwards compatible.";
    }

    md:annotation immutable {
      type boolean;
      description
        "The 'immutable' annotation indicates the immutability of an
         instantiated data node. Any data node instance marked as
         'immutable=true' is read-only to clients and cannot be
         updated through NETCONF, RESTCONF or CLI. It applies to the
         list and leaf-list entries. The default is 'immutable=false'
         if not specified for an instance.";
    }
  }

<CODE ENDS>

References

Appendix B. Changes between revisions

Note to RFC Editor (To be removed by RFC Editor)¶

v03 - v04¶

• Clarify how immutable flag interacts with NACM mechanism.¶

v02 - v03¶

• rephrase and avoid using "server MUST reject" statement, and try to clarify that this documents aims to provide visibility into existing immutable behavior;¶
• Add a new section to discuss the inheritance of immutability;¶
• Clarify that deletion to an immutable node in <running> which is instantiated in <system> and copied into <running> should always be allowed;¶
• Clarify that write access restriction due to general YANG rules has no need to be marked as immutable.¶
• Add an new section named "Acknowledgements";¶
• editoral changes.¶

v01 - v02¶

• clarify the relation between the creation/deletion of the immutable data node with its parent data node;¶
• Add a "TODO" comment about the inheritance of the immutable property;¶
• Define that the server should reject write attempt to the immutable data node at an <edit-config> operation time, rather than waiting until a <commit> or <validate> operation takes place;¶

v00 - v01¶

• Added immutable extension¶
• Added new use-cases for immutable extension and annotation¶
• Added requirement that an update that means no effective change should always be allowed¶
• Added clarification that immutable is only applied to read-write datastore¶
• Narrowed the applied scope of metadata annotation to list/leaf-list instances¶

Appendix C. Open Issues tracking

• Can we do better about the "immutable" terminology?¶
• Is the preferred solution best?¶