Subject: Re: [yang-doctors] defining new RPCs.

From: Benoit Claise <[email-masked]>
Date: Fri, 2 Sep 2016 17:34:28 +0200

On 8/17/2016 12:19 PM, Juergen Schoenwaelder wrote:
> On Wed, Aug 17, 2016 at 11:59:26AM +0200, Bert Wijnen (IETF) wrote:
>> Do we have an opinion on the suitability of
>> defining (many) new RPCs?
>>
>>
>> My personal thinking was that one can define new RPCs indeed,
>> but that we wouldprefer that not too many be defined?
>>
>> Opinions?
>>
> In my view, the main guideline is that newly defined RPCs should not
> overlap with what can already be achieved with the basic protocol
> primitives we have.
Is this guideline, along with Martin's one, already in 6087bis? (no time 
to check now).

Regards, B.
> /js

---

From: Andy Bierman <[email-masked]>
Date: Fri, 2 Sep 2016 10:29:59 -0700

Hi,

This can be enhanced after WGLC if there is clear guidance.
e.g., how to specify when to use <get> vs. a custom-get like the
<active-route> action in the ietf-routing module.

We need text that says "inputs to the retrieval filtering would be
too complex if done with existing subtree and XPath filtering".

I think the same criteria applies to <edit-config> overlap.
It is quite reasonable to have a <create-loopback-interface>
RPC or something like that, that greatly simplifies a procedure,
or enforces a built-in policy on a procedure, etc.

"Don't overlap existing RPCs" seems too vague for a guideline.

Andy

On Fri, Sep 2, 2016 at 8:34 AM, Benoit Claise <[email-masked]> wrote:

> _______________________________________________
> yang-doctors mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/yang-doctors
>

---

From: Balazs Lengyel <[email-masked]>
Date: Mon, 5 Sep 2016 10:05:26 +0200

For ourselves we have some rules, that are IMHO good and useful:

1.1
Allowed
Use of Actions/RPC

Description:  Generally the
management
interface SHALL be modeled with data definition statements.
Management
operations generally mean creating, deleting and modifying
data.

The
use of actions/RPC
is allowed but only in the following cases:

·
when the
aim of the operation is to achieve some behavior or action and
not to just
change or read data. Examples of good actions:

·
activate a
SW package

·
start a
ping test

·
when the
aim of the operation is to read a set of data in a
user-friendly way for
example by collecting leafs from different containers/lists.  Every bit of data
available in such an action
MUST also be modeled as a leaf/leaf-list/container/list,
making it possible to
read the data with normal read operations

·
when the
aim of the operation is to create/delete/modify a set of
configuration data in
a user-friendly way for example by providing common handling
for leafs from
different lists/containers. Every bit of data available in
such an action MUST
also be modeled as a leaf/leaf-list/container/list, making it
possible to
write the data with normal create/delete/modify operations

The YAMs defining actions/RPC
MUST describe
behavior aspects like concurrent usage, traffic disturbance,
side effects and
so on.

Use Actions instead of RPCs

Description:  Usage of RPCs
SHOULD be avoided.
Use actions instead. Too many RPCs make CLI help cluttered.
Access control is
more difficult on RPCs. Usually it is a good idea to connect
actions to a
specific part of the model and to limit their visibility.

regards Balazs

On 2016-09-02 19:29, Andy Bierman
wrote:

Hi,

e.g., how to specify when to use <get> vs. a
custom-get like the

We need text that says "inputs to the retrieval filtering
would be

too complex if done with existing subtree and XPath
filtering".

I think the same criteria applies to <edit-config>
overlap.

It is quite reasonable to have a
<create-loopback-interface>

RPC or something like that, that greatly simplifies a
procedure,

"Don't overlap existing RPCs" seems too vague for a
guideline.

Andy

On Fri, Sep 2, 2016 at 8:34 AM, Benoit
Claise <[email-masked]>
wrote:

On
8/17/2016 12:19 PM, Juergen Schoenwaelder wrote:

On Wed, Aug 17, 2016 at 11:59:26AM +0200, Bert Wijnen
(IETF) wrote:

My personal thinking was that one can define new RPCs
indeed,

Opinions?

In my view, the main guideline is that newly defined RPCs
should not

overlap with what can already be achieved with the basic
protocol

primitives we have.

Is this guideline, along with Martin's one, already in
6087bis? (no time to check now).

Regards, B.

/js

[email-masked]

--
Balazs Lengyel Ericsson Hungary Ltd.
Senior Specialist
Mobile: +36-70-330-7909 email: [email-masked]

---

From: Martin Bjorklund <[email-masked]>
Date: Mon, 05 Sep 2016 10:33:54 +0200 (CEST)

Balazs Lengyel <[email-masked]> wrote:
> 1.1 Allowed Use of Actions/RPC
> 
> Description: Generally the management interface SHALL be modeled with
> data definition statements. Management operations generally mean
> creating, deleting and modifying data.
> 
> The use of actions/RPC is allowed but only in the following cases:
> 
> · when the aim of the operation is to achieve some behavior or action
> and not to just change or read data. Examples of good actions:
> 
> · activate a SW package
> 
> · start a ping test
> 
> · when the aim of the operation is to read a set of data in a
> user-friendly way for example by collecting leafs from different
> containers/lists. Every bit of data available in such an action MUST
> also be modeled as a leaf/leaf-list/container/list, making it possible
> to read the data with normal read operations
> 
> · when the aim of the operation is to create/delete/modify a set of
> configuration data in a user-friendly way for example by providing
> common handling for leafs from different lists/containers. Every bit
> of data available in such an action MUST also be modeled as a
> leaf/leaf-list/container/list, making it possible to write the data
> with normal create/delete/modify operations

This one is IMO questionable in standard models.  Such an operation
will need to work with candidate / running; different error-options,
test-options etc.  Since different protocols (NETCONF/RESTCONF) work
differently in this regard, such an operation will protbably not work
very well in all protocols.

> The YAMs defining actions/RPC MUST describe behavior aspects like
> concurrent usage, traffic disturbance, side effects and so on.
> 
> Description: Usage of RPCs SHOULD be avoided. Use actions instead. Too
> many RPCs make CLI help cluttered.

This sounds like a CLI implementation issue.  It should be possible to
annotate RPCs externally so that the CLI help looks pretty.

One rule could be that if an rpc operates on some data, i.e., it has
parameters that identify something that is modelled as data nodes, it
is better to use an action.  For example, instead of:

  rpc ping-from-interface {
    input {
      leaf interface {
        type leafef {
          path /interfaces/interface/name;
        }
      }
      ...
    }
  }

it is better to do:

  container interfaces {
    list interface {
      key name;
      ...
      action ping {
        ...
      }
    }
  }

/martin

> Access control is more difficult on
> RPCs. Usually it is a good idea to connect actions to a specific part
> of the model and to limit their visibility.
> 
> regards Balazs
> 
> On 2016-09-02 19:29, Andy Bierman wrote:
> 
>     Hi,
> 
>