RFC 8641
Subscription to YANG Notifications for Datastore Updates
Pages: 58
Proposed Standard
Proposed Standard
Part 2 of 3 – Pages 20 to 33
4. A YANG Data Model for Management of Datastore Push Subscriptions
4.1. Overview
The YANG data model for datastore push subscriptions is depicted in Figures 6 through 9. The tree diagram that is used follows the notation defined in [RFC8340]. New schema objects defined here (i.e., beyond those from [RFC8639]) are identified with "yp". For the reader's convenience, in order to compact the tree representation, some nodes that are defined in the ietf-subscribed- notifications YANG module [RFC8639] and therefore are not essential to the understanding of the data model defined here have been removed. This is indicated by "..." in the diagram where applicable. Because the tree diagram is quite large, its depiction is broken up into four figures. Figure 6 depicts the augmentations that are introduced in YANG module ietf-yang-push to the subscription configuration specified in YANG module ietf-subscribed-notifications.
module: ietf-subscribed-notifications ... +--rw filters | ... | +--rw yp:selection-filter* [filter-id] | +--rw yp:filter-id string | +--rw (yp:filter-spec)? | +--:(yp:datastore-subtree-filter) | | +--rw yp:datastore-subtree-filter? <anydata> | | {sn:subtree}? | +--:(yp:datastore-xpath-filter) | +--rw yp:datastore-xpath-filter? yang:xpath1.0 | {sn:xpath}? +--rw subscriptions +--rw subscription* [id] | ... +--rw (target) | +--:(stream) | | ... | +--:(yp:datastore) | +--rw yp:datastore identityref | +--rw (yp:selection-filter)? | +--:(yp:by-reference) | | +--rw yp:selection-filter-ref | | selection-filter-ref | +--:(yp:within-subscription) | +--rw (yp:filter-spec)? | +--:(yp:datastore-subtree-filter) | | +--rw yp:datastore-subtree-filter? | | <anydata> {sn:subtree}? | +--:(yp:datastore-xpath-filter) | +--rw yp:datastore-xpath-filter? | yang:xpath1.0 {sn:xpath}? | ... +--rw (yp:update-trigger) +--:(yp:periodic) | +--rw yp:periodic! | +--rw yp:period centiseconds | +--rw yp:anchor-time? yang:date-and-time +--:(yp:on-change) {on-change}? +--rw yp:on-change! +--rw yp:dampening-period? centiseconds +--rw yp:sync-on-start? boolean +--rw yp:excluded-change* change-type Figure 6: Data Model Structure: Subscription Configuration
Figure 7 depicts the augmentations of YANG module ietf-yang-push made to RPCs specified in YANG module ietf-subscribed-notifications [RFC8639]. Specifically, these augmentations concern the "establish- subscription" and "modify-subscription" RPCs, which are augmented with parameters that are needed to specify datastore push subscriptions. rpcs: +---x establish-subscription | +---w input | | ... | | +---w (target) | | | +--:(stream) | | | | ... | | | +--:(yp:datastore) | | | +---w yp:datastore identityref | | | +---w (yp:selection-filter)? | | | +--:(yp:by-reference) | | | | +---w yp:selection-filter-ref | | | | selection-filter-ref | | | +--:(yp:within-subscription) | | | +---w (yp:filter-spec)? | | | +--:(yp:datastore-subtree-filter) | | | | +---w yp:datastore-subtree-filter? | | | | <anydata> {sn:subtree}? | | | +--:(yp:datastore-xpath-filter) | | | +---w yp:datastore-xpath-filter? | | | yang:xpath1.0 {sn:xpath}? | | | ... | | +---w (yp:update-trigger) | | +--:(yp:periodic) | | | +---w yp:periodic! | | | +---w yp:period centiseconds | | | +---w yp:anchor-time? yang:date-and-time | | +--:(yp:on-change) {on-change}? | | +---w yp:on-change! | | +---w yp:dampening-period? centiseconds | | +---w yp:sync-on-start? boolean | | +---w yp:excluded-change* change-type | +--ro output | +--ro id subscription-id | +--ro replay-start-time-revision? yang:date-and-time | {replay}?
+---x modify-subscription | +---w input | ... | +---w (target) | | ... | | +--:(yp:datastore) | | +---w yp:datastore identityref | | +---w (yp:selection-filter)? | | +--:(yp:by-reference) | | | +---w yp:selection-filter-ref | | | selection-filter-ref | | +--:(yp:within-subscription) | | +---w (yp:filter-spec)? | | +--:(yp:datastore-subtree-filter) | | | +---w yp:datastore-subtree-filter? | | | <anydata> {sn:subtree}? | | +--:(yp:datastore-xpath-filter) | | +---w yp:datastore-xpath-filter? | | yang:xpath1.0 {sn:xpath}? | | ... | +---w (yp:update-trigger) | +--:(yp:periodic) | | +---w yp:periodic! | | +---w yp:period centiseconds | | +---w yp:anchor-time? yang:date-and-time | +--:(yp:on-change) {on-change}? | +---w yp:on-change! | +---w yp:dampening-period? centiseconds +---x delete-subscription | ... +---x kill-subscription ... yang-data (for placement into RPC error responses) ... Figure 7: Data Model Structure: RPCs
Figure 8 depicts augmentations of YANG module ietf-yang-push to the notifications that are specified in YANG module ietf-subscribed- notifications. The augmentations allow the inclusion of subscription configuration parameters that are specific to datastore push subscriptions as part of "subscription-started" and "subscription- modified" notifications. notifications: +---n replay-completed {replay}? | ... +---n subscription-completed | ... +---n subscription-started {configured}? | | ... | +--ro (target) | | ... | | +--:(yp:datastore) | | +--ro yp:datastore identityref | | +--ro (yp:selection-filter)? | | +--:(yp:by-reference) | | | +--ro yp:selection-filter-ref | | | selection-filter-ref | | +--:(yp:within-subscription) | | +--ro (yp:filter-spec)? | | +--:(yp:datastore-subtree-filter) | | | +--ro yp:datastore-subtree-filter? | | | <anydata> {sn:subtree}? | | +--:(yp:datastore-xpath-filter) | | +--ro yp:datastore-xpath-filter? | | yang:xpath1.0 {sn:xpath}? | ... | +--ro (yp:update-trigger) | +--:(yp:periodic) | | +--ro yp:periodic! | | +--ro yp:period centiseconds | | +--ro yp:anchor-time? yang:date-and-time | +--:(yp:on-change) {on-change}? | +--ro yp:on-change! | +--ro yp:dampening-period? centiseconds | +--ro yp:sync-on-start? boolean | +--ro yp:excluded-change* change-type +---n subscription-resumed | ...
+---n subscription-modified | ... | +--ro (target) | | | ... | | +--:(yp:datastore) | | +--ro yp:datastore identityref | | +--ro (yp:selection-filter)? | | +--:(yp:by-reference) | | | +--ro yp:selection-filter-ref | | | selection-filter-ref | | +--:(yp:within-subscription) | | +--ro (yp:filter-spec)? | | +--:(yp:datastore-subtree-filter) | | | +--ro yp:datastore-subtree-filter? | | | <anydata> {sn:subtree}? | | +--:(yp:datastore-xpath-filter) | | +--ro yp:datastore-xpath-filter? | | yang:xpath1.0 {sn:xpath}? | ... | +--ro (yp:update-trigger)? | +--:(yp:periodic) | | +--ro yp:periodic! | | +--ro yp:period centiseconds | | +--ro yp:anchor-time? yang:date-and-time | +--:(yp:on-change) {on-change}? | +--ro yp:on-change! | +--ro yp:dampening-period? centiseconds | +--ro yp:sync-on-start? boolean | +--ro yp:excluded-change* change-type +---n subscription-terminated | ... +---n subscription-suspended ... Figure 8: Data Model Structure: Notifications
Finally, Figure 9 depicts the parts of YANG module ietf-yang-push that are newly introduced in this document (i.e., that are not simply augmentations of another YANG module). module: ietf-yang-push rpcs: +---x resync-subscription {on-change}? +---w input +---w id sn:subscription-id yang-data (for placement into RPC error responses): +-- resync-subscription-error | +--ro reason? identityref | +--ro period-hint? centiseconds | +--ro filter-failure-hint? string | +--ro object-count-estimate? uint32 | +--ro object-count-limit? uint32 | +--ro kilobytes-estimate? uint32 | +--ro kilobytes-limit? uint32 +-- establish-subscription-error-datastore | +--ro reason? identityref | +--ro period-hint? centiseconds | +--ro filter-failure-hint? string | +--ro object-count-estimate? uint32 | +--ro object-count-limit? uint32 | +--ro kilobytes-estimate? uint32 | +--ro kilobytes-limit? uint32 +-- modify-subscription-error-datastore +--ro reason? identityref +--ro period-hint? centiseconds +--ro filter-failure-hint? string +--ro object-count-estimate? uint32 +--ro object-count-limit? uint32 +--ro kilobytes-estimate? uint32 +--ro kilobytes-limit? uint32
notifications: +---n push-update | +--ro id? sn:subscription-id | +--ro datastore-contents? <anydata> | +--ro incomplete-update? empty +---n push-change-update {on-change}? +--ro id? sn:subscription-id +--ro datastore-changes | +--ro yang-patch | +--ro patch-id string | +--ro comment? string | +--ro edit* [edit-id] | +--ro edit-id string | +--ro operation enumeration | +--ro target target-resource-offset | +--ro point? target-resource-offset | +--ro where? enumeration | +--ro value? <anydata> +--ro incomplete-update? empty Figure 9: Data Model Structure: Non-augmentation Portions Selected components of the data model are summarized below.4.2. Subscription Configuration
Both configured and dynamic subscriptions are represented in the list "subscription". New parameters extending the basic subscription data model in [RFC8639] include: o The targeted datastore from which the selection is being made. The potential datastores include those from [RFC8342]. A platform may also choose to support a custom datastore. o A selection filter identifying YANG nodes of interest in a datastore. Filter contents are specified via a reference to an existing filter or via an in-line definition for only that subscription. Referenced filters allow an implementation to avoid evaluating filter acceptability during a dynamic subscription request. The "case" statement differentiates the options.
o For periodic subscriptions, triggered updates will occur at the
boundaries of a specified time interval. These boundaries can be
calculated from the periodic parameters:
* a "period" that defines the duration between push updates.
* an "anchor-time"; update intervals fall on the points in time
that are a multiple of a "period" from an "anchor-time". If an
"anchor-time" is not provided, then the "anchor-time" MUST be
set with the creation time of the initial update record.
o For on-change subscriptions, assuming that any dampening period
has completed, triggering occurs whenever a change in the
subscribed information is detected. On-change subscriptions have
more-complex semantics that are guided by their own set of
parameters:
* a "dampening-period" that specifies the interval that must pass
before a successive update for the subscription is sent. If no
dampening period is in effect, the update is sent immediately.
If a subsequent change is detected, another update is only sent
once the dampening period has passed for this subscription.
* an "excluded-change" that allows the restriction of the types
of changes for which updates should be sent (e.g., only add to
an update record on object creation).
* a "sync-on-start" that specifies whether a complete update with
all the subscribed data is to be sent at the beginning of a
subscription.
4.3. YANG Notifications
4.3.1. State Change Notifications
Subscription state notifications and mechanisms are reused from
[RFC8639]. Notifications "subscription-started" and "subscription-
modified" have been augmented to include the datastore-specific
objects.
4.3.2. Notifications for Subscribed Content
Along with the subscribed content, there are other objects that might be part of a "push-update" or "push-change-update" notification. o An "id" (that identifies the subscription). This object MUST be transported along with the subscribed contents. It allows a receiver to determine which subscription resulted in a particular update record. o An "incomplete-update" leaf. This leaf indicates that not all changes that have occurred since the last update are actually included with this update. In other words, the publisher has failed to fulfill its full subscription obligations. (For example, a datastore was unable to provide the full set of datastore nodes to a publisher process.) To facilitate the resynchronization of on-change subscriptions, a publisher MAY subsequently send a "push-update" containing a full selection snapshot of subscribed data.4.4. YANG RPCs
YANG-Push subscriptions are established, modified, and deleted using RPCs augmented from [RFC8639].4.4.1. "establish-subscription" RPC
The subscriber sends an "establish-subscription" RPC with the parameters listed in Section 3.1. An example might look like:
<netconf:rpc message-id="101" xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0"> <establish-subscription xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications" xmlns:yp="urn:ietf:params:xml:ns:yang:ietf-yang-push"> <yp:datastore xmlns:ds="urn:ietf:params:xml:ns:yang:ietf-datastores"> ds:operational </yp:datastore> <yp:datastore-xpath-filter xmlns:ex="https://example.com/sample-data/1.0"> /ex:foo </yp:datastore-xpath-filter> <yp:periodic> <yp:period>500</yp:period> </yp:periodic> </establish-subscription> </netconf:rpc> Figure 10: "establish-subscription" RPC A positive response includes the "id" of the accepted subscription. In that case, a publisher may respond as follows: <rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <id xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications"> 52 </id> </rpc-reply> Figure 11: "establish-subscription" Positive RPC Response A subscription can be rejected for multiple reasons, including the lack of authorization to establish a subscription, no capacity to serve the subscription at the publisher, or the inability of the publisher to select datastore content at the requested cadence. If a request is rejected because the publisher is not able to serve it, the publisher SHOULD include in the returned error hints that help a subscriber understand what subscription parameters might have been accepted for the request. These hints would be included in the yang-data structure "establish-subscription-error-datastore". However, even with these hints, there are no guarantees that subsequent requests will in fact be accepted.
The specific parameters to be returned as part of the RPC error response depend on the specific transport that is used to manage the subscription. For NETCONF, those parameters are defined in [RFC8640]. For example, for the following NETCONF request: <rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <establish-subscription xmlns= "urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications" xmlns:yp="urn:ietf:params:xml:ns:yang:ietf-yang-push"> <yp:datastore xmlns:ds="urn:ietf:params:xml:ns:yang:ietf-datastores"> ds:operational </yp:datastore> <yp:datastore-xpath-filter xmlns:ex="https://example.com/sample-data/1.0"> /ex:foo </yp:datastore-xpath-filter> <yp:on-change> <yp:dampening-period>100</yp:dampening-period> </yp:on-change> </establish-subscription> </rpc> Figure 12: "establish-subscription" Request: Example 2 A publisher that cannot serve on-change updates but can serve periodic updates might return the following NETCONF response: <rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:yp="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications"> <rpc-error> <error-type>application</error-type> <error-tag>operation-failed</error-tag> <error-severity>error</error-severity> <error-path>/yp:periodic/yp:period</error-path> <error-info> <yp:establish-subscription-error-datastore> <yp:reason>yp:on-change-unsupported</yp:reason> </yp:establish-subscription-error-datastore> </error-info> </rpc-error> </rpc-reply> Figure 13: "establish-subscription" Error Response: Example 2
4.4.2. "modify-subscription" RPC
The subscriber MAY invoke the "modify-subscription" RPC for a subscription it previously established. The subscriber will include newly desired values in the "modify-subscription" RPC. Parameters not included MUST remain unmodified. Figure 14 provides an example where a subscriber attempts to modify the period and datastore XPath filter of a subscription using NETCONF. <rpc message-id="102" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <modify-subscription xmlns= "urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications" xmlns:yp="urn:ietf:params:xml:ns:yang:ietf-yang-push"> <id>1011</id> <yp:datastore xmlns:ds="urn:ietf:params:xml:ns:yang:ietf-datastores"> ds:operational </yp:datastore> <yp:datastore-xpath-filter xmlns:ex="https://example.com/sample-data/1.0"> /ex:bar </yp:datastore-xpath-filter> <yp:periodic> <yp:period>250</yp:period> </yp:periodic> </modify-subscription> </rpc> Figure 14: "modify-subscription" Request The publisher MUST respond to the subscription modification request. If the request is rejected, the existing subscription is left unchanged, and the publisher MUST send an RPC error response. This response might have hints encapsulated in the yang-data structure "modify-subscription-error-datastore". A subscription MAY be modified multiple times. The specific parameters to be returned as part of the RPC error response depend on the specific transport that is used to manage the subscription. For NETCONF, those parameters are specified in [RFC8640]. A configured subscription cannot be modified using a "modify-subscription" RPC. Instead, the configuration needs to be edited as needed.
4.4.3. "delete-subscription" RPC
To stop receiving updates from a subscription and effectively delete a subscription that had previously been established using an "establish-subscription" RPC, a subscriber can send a "delete-subscription" RPC, which takes as its only input the subscription's "id". This RPC is unmodified from [RFC8639].4.4.4. "resync-subscription" RPC
This RPC is supported only for on-change subscriptions previously established using an "establish-subscription" RPC. For example: <rpc message-id="103" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <resync-subscription xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push"> <id>1011</id> </resync-subscription> </rpc> Figure 15: "resync-subscription" On receipt, a publisher must either (1) accept the request and quickly follow with a "push-update" or (2) send an appropriate error in an RPC error response. In its error response, the publisher MAY include, in the yang-data structure "resync-subscription-error", supplemental information about the reasons for the error.4.4.5. YANG Module Synchronization
To make subscription requests, the subscriber needs to know the YANG datastore schemas used by the publisher. These schemas are available in the YANG library module ietf-yang-library.yang as defined in [RFC8525]. The receiver is expected to know the YANG library information before starting a subscription. The set of modules, revisions, features, and deviations can change at runtime (if supported by the publisher implementation). For this purpose, the YANG library provides a simple "yang-library-change" notification that informs the subscriber that the library has changed. In this case, a subscription may need to be updated to take the updates into account. The receiver may also need to be informed of module changes in order to process updates regarding datastore nodes from changed modules correctly.