For a YANG operation that clears one interface's counters, why might a model designer choose a YANG 1.1 action on the interface entry over a top-level rpc?
answer
- bound to an instance
- the path names the target
- who may clear which interface
- one action per request
basics
~20 sAn action is bound to the interface entry: the path names the target, the entry must exist, and NACM authorises per interface. An rpc takes the interface as a parameter NACM cannot filter, but can cover many interfaces at once.
solid answer
~40 sAn `rpc` is a top-level operation, so the interface becomes an input parameter. A YANG 1.1 `action` is defined on a container or list, here added to each interface entry by an augment, and is invoked against one instance: the path with its keys identifies the target, and under NMDA the node must exist in the operational datastore. The decisive gain is authorisation: NACM requires read access to the targeted entry plus execute access to the action, while it cannot filter an rpc by parameter values (RFC 9907 §4.26.4). The costs are YANG 1.1 only, one action per NETCONF `<rpc>` (so 200 interfaces means 200 calls), and actions not being listed under `{+restconf}/operations`. RFC 9907 recommends an action when the operation applies to a subset of data nodes.
code
yang · 12 linesaugment "/if:interfaces/if:interface" {
action clear-counters {
description
"Clears this interface's counters and updates
its discontinuity-time.";
output {
leaf cleared-at {
type yang:date-and-time;
}
}
}
}go deeper
Recall that an rpc is a standalone operation while a YANG 1.1 action belongs to a specific data entry, such as one interface.
Explain how the target is identified in each case, why an augment can attach an action to a foreign list, and that actions require YANG 1.1.
Argue the trade-off: per-instance NACM and existence checks for an action, against bulk operations, YANG 1.0 reach and discovery through the operations resource for an rpc.
Set the rule for a model portfolio: which operations are entry-scoped actions, how authorisation maps to tenants, and how automation discovers and batches them.
## The design problem A vendor wants a **clear-counters** operation for one interface. In YANG there are two ways to define it: - A top-level **`rpc`** (RFC 7950 §7.14), with the interface named by an input leaf of type `if:interface-ref`. - A YANG 1.1 **`action`** (§7.15) defined on the interface list entry. The vendor cannot edit `ietf-interfaces`, but an augment whose target is a container or list may contain an `action`, so `augment "/if:interfaces/if:interface"` can attach one. RFC 9907 §4.26.4 calls the choice "a subjective design decision", then gives the guidance: an `action` SHOULD be used if the operation is specific to a subset of all data nodes. Clearing one interface's counters is that case. Here is what each choice actually changes, from the model's point of view rather than the wire's. ## What an action changes 1. **The target is part of the address, not a parameter.** When an action is invoked the data node is specified along with the action's name and input. A NETCONF invocation wraps the path, with every list key, in an `<action>` element in the `urn:ietf:params:xml:ns:yang:1` namespace; RESTCONF POSTs to the data resource, e.g. `/restconf/data/ietf-interfaces:interfaces/interface=eth0/example-vendor-qos:clear-counters`. 2. **The target must exist.** NMDA (RFC 8342 §6.2) says actions are always invoked in the context of the operational state datastore, and the node MUST exist there. RFC 8527 adds that, among the NMDA datastore resources, RESTCONF actions can only be invoked under `{+restconf}/ds/ietf-datastores:operational`. 3. **Access control follows the instance.** NACM (RFC 8341) requires read access to every instance in the path and execute access to the action node. RFC 9907 points out that NACM has no parameter-based control for rpcs: the user may execute the rpc with any parameters or not at all. So "operators of tenant A may clear only tenant A's interfaces" is expressible with an action and not with an rpc. 4. **Names can be reused.** The same action name can be defined on different nodes with different parameters: a `reset` on an interface and a `reset` on a power supply. ## What it costs | Concern | `rpc` | `action` | |---|---|---| | Language version | YANG 1.0 and 1.1 | YANG 1.1 only | | Where defined | top level of a module | inside a container or list (directly or via augment) | | Target | an input parameter | the data-node instance in the request path | | Per-instance NACM | no | yes: read on the path, execute on the action | | Many targets in one request | yes, e.g. a leaf-list input | no: one action per NETCONF `<rpc>`, otherwise `bad-element` | | RESTCONF discovery | listed under `{+restconf}/operations` | not listed there; reached through the data tree | The last two rows matter for automation. Clearing 200 interfaces with an action means 200 invocations; an rpc taking a list of interfaces can do it in one. A client that discovers capabilities by listing `{+restconf}/operations` will not see actions at all; it has to learn them from the schema, through the YANG library and the modules it names. Both kinds return their output the same way: with no output defined, a NETCONF reply is a bare `<ok/>` and a RESTCONF reply is `204 No Content`. ## The notification side An event announcing the clear can follow the same logic. A YANG 1.1 notification can be tied to the interface entry, so its encoding carries the path to that entry and NACM checks read access to it before sending it to a subscriber. ## A design note on counter semantics Clearing counters creates a jump that a collector could misread as a wrap. `ietf-interfaces` gives every interface a `discontinuity-time` leaf, "the time on the most recent occasion at which any one or more of this interface's counters suffered a discontinuity", and each counter's description points at it. A well-written operation description says that the clear updates `discontinuity-time`. That is a modelling choice the vendor documents, not a rule RFC 8343 imposes on clear operations. ## Putting it together - Choose an **action** when the operation is about one entry, when per-entry authorisation matters, and when YANG 1.1 is available everywhere it must run. - Choose an **rpc** when the operation is device-wide, when one call must cover many targets, or when YANG 1.0 clients must use it. - Either way, keep input optional where existing callers exist, and document what the operation does to state such as counters.
- Can a vendor add an rpc to ietf-interfaces through augment instead?No. An `rpc` exists only at the top level of a module, and augment can add `action` and `notification` to a container or list, never an `rpc`. The vendor's rpc simply lives at the top level of its own module, in its own namespace, and takes the interface as input.
- What happens if a client invokes the action on an interface that does not exist?NMDA (RFC 8342 §6.2) says the node for which an action is invoked MUST exist in the operational state datastore, so the server refuses the request instead of running the operation. With an rpc, handling a nonexistent interface named in the input is left to the operation's own logic and description.
saying these in an interview costs you the question
- An action and an rpc differ only in name; both are top-level statements.
- NACM can restrict an rpc by the value of its interface input leaf.
- One NETCONF request can invoke the same action on many interfaces at once.
- Actions work in YANG 1.0 modules as long as the server supports them.
- A client listing RESTCONF's operations resource sees every action the server supports.