Subject: [netmod] Guideline on modeling including features and phased support by a device

From: "Bogaert, Bart (Nokia - BE/Antwerp)" <[email-masked]>
Date: Mon, 5 Mar 2018 09:25:14 +0000

Hi,

We have a question with respect to YANG models using features.  Assume that a part of the model is defined under a feature and that this feature-dependent part defines a leaf as mandatory.

module servers {
  namespace "http://www.example.com/servers";
  prefix servers;

  import ietf-inet-types {
    prefix inet;
  }

  revision 2018-03-01 {
    description
       "Initial version.";
  }

  feature test-feature {
    description "testing feature";
  }

  container servers {
    list server {
      key name;
      max-elements 64;
      leaf name {
        type string;
      }
      leaf ip {
        type inet:ip-address;
        mandatory true;
      }
      leaf port {
        type inet:port-number;
        mandatory true;
      }
      leaf only-if-feature {
        if-feature test-feature;
        type string;
        mandatory true;
      }
    }
  }
}

Now assume that we have a device that implements the model step-wise by first not supporting this feature and in a sub-sequent release by supporting this feature (and uses a persistent running datastore).  The question arising now is how to deal with this mandatory leaf?  Normally this can only be configured by a client, meaning that without any "help", the NC server will not be able to startup with the data contained in the device's persistent datastore unless a value is set for the mandatory leaf that now becomes available as a result of supporting the feature.

When modeling as follows it seems the NC server can start with the model supporting the feature that was not supported before:

module servers {
  namespace "http://www.example.com/servers";
  prefix servers;

  import ietf-inet-types {
    prefix inet;
  }

  revision 2018-03-01 {
    description
       "Initial version.";
  }

  feature test-feature {
    description "testing feature";
  }

  container servers {
    list server {
      key name;
      max-elements 64;
      leaf name {
        type string;
      }
      leaf ip {
        type inet:ip-address;
        mandatory true;
      }
      leaf port {
        type inet:port-number;
        mandatory true;
      }
      container only-if-feature {
        presence "see if this helps";
        if-feature test-feature;
        leaf only-if-feature {
          type string;
          mandatory true;
        }
      }
    }
  }
}

Are recommendations or guidelines in place to deal with this?

Regards, Bart

---

From: Alex Campbell <[email-masked]>
Date: Tue, 6 Mar 2018 03:30:50 +0000

Presumably you will have to decide on a sensible default value to use.

What value will your actual device use after the software upgrade? That should be the value it stores in the data tree when performing the upgrade.

________________________________
From: netmod <[email-masked]> on behalf of Bogaert, Bart (Nokia - BE/Antwerp) <[email-masked]>
Sent: Monday, 5 March 2018 10:25 p.m.
To: [email-masked]
Subject: [netmod] Guideline on modeling including features and phased support by a device

Hi,

module servers {

  import ietf-inet-types {
    prefix inet;
  }

  revision 2018-03-01 {
    description
       "Initial version.";
  }

  feature test-feature {

  container servers {
    list server {
      key name;
      max-elements 64;
      leaf name {
        type string;
      }
      leaf ip {
        type inet:ip-address;
        mandatory true;
      }
      leaf port {
        type inet:port-number;
        mandatory true;
      }
      leaf only-if-feature {
        if-feature test-feature;
        type string;
        mandatory true;
      }
    }
  }
}

module servers {

  import ietf-inet-types {
    prefix inet;
  }

  revision 2018-03-01 {
    description
       "Initial version.";
  }

  feature test-feature {

  container servers {
    list server {
      key name;
      max-elements 64;
      leaf name {
        type string;
      }
      leaf ip {
        type inet:ip-address;
        mandatory true;
      }
      leaf port {
        type inet:port-number;
        mandatory true;
      }

Regards, Bart

---

From: Robert Wilton <[email-masked]>
Date: Tue, 6 Mar 2018 09:37:44 +0000

Hi Bart,

I think that the best solution to problem is perhaps to avoid it 
altogether.  I.e. I don't think that the only-if-feature leaf should be 
marked mandatory.  Instead, it would be better to define a sensible 
default value/behaviour if the leaf is absent even when the feature is 
supported.

Alternatively, you can simulate something similar to an if-feature 
statement by using a when or must expression instead that is predicated 
on a leaf that the client must explicitly set to enable the feature, 
giving control back to the client.

E.g. something along the lines of ...

leaf enable-super-feature {
   if-feature test-feature;
   type boolean;
   default "false";
}

...

       leaf only-if-feature {

         when '/enable-super-feature = "true"';

         type string;

         mandatory true;

       }

It would be interesting if you have a concrete example where neither of 
the above suggestions would work or be appropriate.

Thanks,
Rob

On 05/03/2018 09:25, Bogaert, Bart (Nokia - BE/Antwerp) wrote:
>
> Hi,
>
> We have a question with respect to YANG models using features.  Assume 
> that a part of the model is defined under a feature and that this 
> feature-dependent part defines a leaf as mandatory.
>
> module servers {
>
> Now assume that we have a device that implements the model step-wise 
> by first not supporting this feature and in a sub-sequent release by 
> supporting this feature (and uses a persistent running datastore).  
> The question arising now is how to deal with this mandatory leaf?  
> Normally this can only be configured by a client, meaning that without 
> any “help”, the NC server will not be able to startup with the data 
> contained in the device’s persistent datastore unless a value is set 
> for the mandatory leaf that now becomes available as a result of 
> supporting the feature.
>
> When modeling as follows it seems the NC server can start with the 
> model supporting the feature that was not supported before:
>
> module servers {
>
> _______________________________________________
> netmod mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/netmod

---

From: "Bogaert, Bart (Nokia - BE/Antwerp)" <[email-masked]>
Date: Tue, 6 Mar 2018 11:34:02 +0000

Hi Rob,

I agree but the fact is that some of the BBF models have constructions like that and we were wondering whether this should not be mentioned in the guildelines document.  Normally a server can't set config true leafs if there is no default available in the model.  That is the reason we reached out to NETMOD.  Your suggestions can work but require adaptation of the current model.

Regards, Bart

From: Robert Wilton [mailto:[email-masked]]
Sent: Tuesday, March 6, 2018 10:38 AM
To: Bogaert, Bart (Nokia - BE/Antwerp) <[email-masked]>; [email-masked]
Subject: Re: [netmod] Guideline on modeling including features and phased support by a device

Hi Bart,

I think that the best solution to problem is perhaps to avoid it altogether.  I.e. I don't think that the only-if-feature leaf should be marked mandatory.  Instead, it would be better to define a sensible default value/behaviour if the leaf is absent even when the feature is supported.

Alternatively, you can simulate something similar to an if-feature statement by using a when or must expression instead that is predicated on a leaf that the client must explicitly set to enable the feature, giving control back to the client.

...
      leaf only-if-feature {

It would be interesting if you have a concrete example where neither of the above suggestions would work or be appropriate.

Thanks,
Rob

module servers {

  import ietf-inet-types {
    prefix inet;
  }

  revision 2018-03-01 {
    description
       "Initial version.";
  }

  feature test-feature {

  container servers {
    list server {
      key name;
      max-elements 64;
      leaf name {
        type string;
      }
      leaf ip {
        type inet:ip-address;
        mandatory true;
      }
      leaf port {
        type inet:port-number;
        mandatory true;
      }
      leaf only-if-feature {
        if-feature test-feature;
        type string;
        mandatory true;
      }
    }
  }
}

module servers {

  import ietf-inet-types {
    prefix inet;
  }

  revision 2018-03-01 {
    description
       "Initial version.";
  }

  feature test-feature {

  container servers {
    list server {
      key name;
      max-elements 64;
      leaf name {
        type string;
      }
      leaf ip {
        type inet:ip-address;
        mandatory true;
      }
      leaf port {
        type inet:port-number;
        mandatory true;
      }

Regards, Bart

netmod mailing list

[email-masked]<mailto:[email-masked]>

---

From: Robert Wilton <[email-masked]>
Date: Tue, 6 Mar 2018 11:59:24 +0000

Arguably the guidelines, or YANG, should say "don't allow this" ;-)

I think that what you are describing is just another instance of "don't 
augment with a mandatory node rule", or "only backwards compatible 
changes revisions should be made to a published YANG module".

The key reasoning behind these rules is that the a client should be able 
to work unchanged after the server has been upgraded, as long as they 
are not making use of any new functionality.

Thanks,
Rob

On 06/03/2018 11:34, Bogaert, Bart (Nokia - BE/Antwerp) wrote:
>
> Hi Rob,
>
> I agree but the fact is that some of the BBF models have constructions 
> like that and we were wondering whether this should not be mentioned 
> in the guildelines document. Normally a server can’t set config true 
> leafs if there is no default available in the model.  That is the 
> reason we reached out to NETMOD.  Your suggestions can work but 
> require adaptation of the current model.
>
> Regards, Bart
>
> *From:*Robert Wilton [mailto:[email-masked]]
> *Sent:* Tuesday, March 6, 2018 10:38 AM
> *To:* Bogaert, Bart (Nokia - BE/Antwerp) <[email-masked]>; 
> [email-masked]
> *Subject:* Re: [netmod] Guideline on modeling including features and 
> phased support by a device
>
> Hi Bart,
>
> altogether.  I.e. I don't think that the only-if-feature leaf should 
> be marked mandatory.  Instead, it would be better to define a sensible 
> statement by using a when or must expression instead that is 
> predicated on a leaf that the client must explicitly set to enable the 
> feature, giving control back to the client.
>
> It would be interesting if you have a concrete example where neither 
> of the above suggestions would work or be appropriate.
>
> Thanks,
> Rob
>
>     We have a question with respect to YANG models using features. 
>     Assume that a part of the model is defined under a feature and
>     that this feature-dependent part defines a leaf as mandatory.
>
>     module servers {
>
>     Now assume that we have a device that implements the model
>     step-wise by first not supporting this feature and in a
>     sub-sequent release by supporting this feature (and uses a
>     persistent running datastore).  The question arising now is how to
>     deal with this mandatory leaf?  Normally this can only be
>     configured by a client, meaning that without any “help”, the NC
>     server will not be able to startup with the data contained in the
>     device’s persistent datastore unless a value is set for the
>     mandatory leaf that now becomes available as a result of
>     supporting the feature.
>
>     [email-masked] <mailto:[email-masked]>
>

---

From: "Bogaert, Bart (Nokia - BE/Antwerp)" <[email-masked]>
Date: Tue, 6 Mar 2018 12:04:07 +0000

Rob,

Just to clarify: in this case we are not changing the model, it is the same model but the device SW in release X is not supporting the feature and in release Y it is.  Supporting the feature results in adding that part of the tree to the configuration that is related to the feature and the data leafs related to that feature are simply not there in the data configured when SW release X was active.

Regards, Bart

From: Robert Wilton [mailto:[email-masked]]
Sent: Tuesday, March 6, 2018 12:59 PM
To: Bogaert, Bart (Nokia - BE/Antwerp) <[email-masked]>
Cc: [email-masked]
Subject: Re: [netmod] Guideline on modeling including features and phased support by a device

I think that what you are describing is just another instance of "don't augment with a mandatory node rule", or "only backwards compatible changes revisions should be made to a published YANG module".

The key reasoning behind these rules is that the a client should be able to work unchanged after the server has been upgraded, as long as they are not making use of any new functionality.
Thanks,
Rob

Regards, Bart

From: Robert Wilton [mailto:[email-masked]]
Sent: Tuesday, March 6, 2018 10:38 AM
To: Bogaert, Bart (Nokia - BE/Antwerp) <[email-masked]><mailto:[email-masked]>; [email-masked]<mailto:[email-masked]>
Subject: Re: [netmod] Guideline on modeling including features and phased support by a device

Hi Bart,

...
      leaf only-if-feature {

Thanks,
Rob

module servers {

  import ietf-inet-types {
    prefix inet;
  }

  revision 2018-03-01 {
    description
       "Initial version.";
  }

  feature test-feature {

  container servers {
    list server {
      key name;
      max-elements 64;
      leaf name {
        type string;
      }
      leaf ip {
        type inet:ip-address;
        mandatory true;
      }
      leaf port {
        type inet:port-number;
        mandatory true;
      }
      leaf only-if-feature {
        if-feature test-feature;
        type string;
        mandatory true;
      }
    }
  }
}

module servers {

  import ietf-inet-types {
    prefix inet;
  }

  revision 2018-03-01 {
    description
       "Initial version.";
  }

  feature test-feature {

  container servers {
    list server {
      key name;
      max-elements 64;
      leaf name {
        type string;
      }
      leaf ip {
        type inet:ip-address;
        mandatory true;
      }
      leaf port {
        type inet:port-number;
        mandatory true;
      }

Regards, Bart

netmod mailing list

---

From: Robert Wilton <[email-masked]>
Date: Tue, 6 Mar 2018 12:41:27 +0000

On 06/03/2018 12:04, Bogaert, Bart (Nokia - BE/Antwerp) wrote:
>
> Rob,
>
> Just to clarify: in this case we are not changing the model, it is the 
> same model but the device SW in release X is not supporting the 
> feature and in release Y it is.  Supporting the feature results in 
> adding that part of the tree to the configuration that is related to 
> the feature and the data leafs related to that feature are simply not 
> there in the data configured when SW release X was active.
>
Yes, but an equivalent way of writing this without a feature, and 
ignoring namespaces, would be put the feature nodes into a separate YANG 
module (F) which augments the base module (B).

In release X, the device only supports B.
In release Y, the device supports B and F.

But YANG would not allow F to augment B with a mandatory node for the 
reasons described previously.  Hence, I think that it is probably an 
oversight that YANG allows this.

Probably it should go on the YANG 2.0 issue tracker to consider and 
potentially disallow this.

Thanks,
Rob

> *Sent:* Tuesday, March 6, 2018 12:59 PM
> *To:* Bogaert, Bart (Nokia - BE/Antwerp) <[email-masked]>
> *Cc:* [email-masked]
> I think that what you are describing is just another instance of 
> "don't augment with a mandatory node rule", or "only backwards 
> compatible changes revisions should be made to a published YANG module".
>
> The key reasoning behind these rules is that the a client should be 
> able to work unchanged after the server has been upgraded, as long as 
> they are not making use of any new functionality.
>
> Thanks,
> Rob
>
>     I agree but the fact is that some of the BBF models have
>     constructions like that and we were wondering whether this should
>     not be mentioned in the guildelines document.  Normally a server
>     can’t set config true leafs if there is no default available in
>     the model.  That is the reason we reached out to NETMOD.  Your
>     suggestions can work but require adaptation of the current model.
>
>     Regards, Bart
>
>     *To:* Bogaert, Bart (Nokia - BE/Antwerp) <[email-masked]>
>     <mailto:[email-masked]>; [email-masked]
>     <mailto:[email-masked]>
>     *Subject:* Re: [netmod] Guideline on modeling including features
>     and phased support by a device
>
>     Hi Bart,
>
>     altogether.  I.e. I don't think that the only-if-featureleaf
>     should be marked mandatory.  Instead, it would be better to define
>     a sensible default value/behaviour if the leaf is absent even when
>     the feature is supported.
>
>     predicated on a leaf that the client must explicitly set to enable
>     the feature, giving control back to the client.
>
>     It would be interesting if you have a concrete example where
>     neither of the above suggestions would work or be appropriate.
>
>     Thanks,
>     Rob
>
>
>         We have a question with respect to YANG models using
>         features.  Assume that a part of the model is defined under a
>         feature and that this feature-dependent part defines a leaf as
>         mandatory.
>
>         module servers {
>
>         persistent running datastore).  The question arising now is
>         how to deal with this mandatory leaf?  Normally this can only
>         be configured by a client, meaning that without any “help”,
>         the NC server will not be able to startup with the data
>         contained in the device’s persistent datastore unless a value
>         is set for the mandatory leaf that now becomes available as a
>         result of supporting the feature.
>
>         When modeling as follows it seems the NC server can start with
>         the model supporting the feature that was not supported before:
>
>         module servers {
>

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Tue, 6 Mar 2018 13:41:34 +0100

> I agree but the fact is that some of the BBF models have constructions like that and we were wondering whether this should not be mentioned in the guildelines document.  Normally a server can't set…

I agree that mandatory leafs can be subtle and I agree that this is a
great topic for a guidelines document. Perhaps you can draft some
concrete text that could be considered to be added to section 4.17.
There is text in section 4.19.2 which addresses a similar situation
with mandatory augments and perhaps we should have a similar
discussion in a new section 4.17.1.

/js

-- 
Juergen Schoenwaelder           Jacobs University Bremen gGmbH
Phone: +49 421 200 3587         Campus Ring 1 | 28759 Bremen | Germany
Fax:   +49 421 200 3103         <https://www.jacobs-university.de/>