Configure on-change subscription using gRPC

Model-driven telemetry reverses the direction: the device decides when there is something to say and streams YANG-modelled data to a collector. A subscription defines what, when, in what format and to whom. On-change works only on certain paths, so check the path in the Cisco-IOS-XE-mdt-capabilities-oper model first. Dial-out subscriptions live in the configuration and survive a switchover; dial-in ones end with their session.

In Daveth Pro (Network)4 min video · lab: Automation

By , founder of Daveth · Updated

Opening frame of the video walkthrough of Configure on-change subscription using gRPC

Watch this lesson

4 min · Video walkthrough

In Daveth Pro (Network)

The full 4 min walkthrough is in Daveth Pro (Network). See what the plan opens

Upcoming practical lab

Lab C20: Automation

What the lab covers

What this page answers

How do you check whether a YANG path supports on-change telemetry?

Query the path in the Cisco-IOS-XE-mdt-capabilities-oper model, over NETCONF, RESTCONF or gNMI. On-change support is limited to certain model paths. Read it in “Before you configure it: can this path do on-change?”

What is the difference between dial-in and dial-out telemetry?

A dial-in subscription is tied to the session that created it and must be reinitiated after a reload or switchover. A dial-out subscription is part of the running configuration and reconnects to the receiver automatically. Read it in “Dial-out or dial-in — and which one survives”

What does a telemetry subscription define?

The set of data requested, when it is sent, how it is formatted and, when not implicit, which receivers get it. Read it in “The direction reverses”

The direction reverses

Every call so far in this task started with you. You authenticated, you asked, the platform answered. This reverses it: the device decides when there is something to say.

Model-driven telemetry provides a mechanism to stream YANG-modelled data to a data collector. a subscription is used to define the set of data that is requested as part of the telemetry data; when the data is required, how the data is to be formatted, and, when not implicit, who (which receivers) should receive the data.

Set, timing, format, recipient. Every line of configuration below maps onto one of those four.

Before you configure it: can this path do on-change?

The blueprint says configure on-change subscription, which reads as though the configuration is the work. Start one step earlier.

ON_CHANGE support is limited to certain model paths. To check whether a path supports ON_CHANGE, query the path in the Cisco-IOS-XE-MDT-capabilities-oper model.

The model (Cisco-IOS-XE-mdt-capabilities-oper.yang) is YANG: you read it over NETCONF, RESTCONF or gNMI like any other operational model. It doesn't list every node. It lists entries whose support differs from their parent, and you look a node up in order:

1. the transport-specific list for your transport; 2. the per-node list; 3. the system level.

The first entry that selects a given node is what determines the capabilities of that node. The system-level capabilities for Cisco IOS XE support only periodic subscriptions; on-change subscriptions are not supported. For example, gRPC supports on-change on some paths that NETCONF does not support.

This scenario's lookup for its two paths, over gRPC. It's a reading of the model, not the output of any command:

path                                                      decided by  on-change
/iosxe-oper:ios-oper-db/hwidb-table                       per-node    supported
/memory-ios-xe-oper:memory-statistics/memory-statistic    system      not supported

Each entry carries a capability specification. The chapter prints the two shapes you'll meet: on-change supported for config and operational nodes, and not supported:

<sub-caps>
  <on-change-is-valid/>
  <on-change-supported>mdt-cap-notif-config mdt-cap-notif-state</on-change-supported>
</sub-caps>
<sub-caps>
  <on-change-is-valid/>
  <on-change-supported/>
</sub-caps>

In this scenario, the interface table is selected by a per-node entry that supports on-change. memory statistics isn't selected by any entry, so the system level answers: periodic only. (These entries are this scenario's; on a real device, read the model.)

What does the device report for an on-change subscription on a path like that? The chapter doesn't say, and this page doesn't guess. Ask the model first, and choose on-change or periodic from its answer.

Dial-out or dial-in, and which one survives

Life of the subscription is tied to the connection (session) that created it, and over which telemetry updates are sent. Dial-in subscriptions need to be reinitiated after a reload, because established connections or sessions are killed during stateful switchover.
Subscription is created as part of the running configuration; it remains as the device configuration till the configuration is removed. Dial-out subscriptions are created as part of the device configuration, and they automatically reconnect to the receiver after a stateful switchover.

The one that looks passive is the one that persists, because it's configuration. gRPC is the configured, dial-out side here. This is the chapter's configured-subscription example, as the chapter prints it. It's periodic:

Which is worth saying against the names, because dynamic sounds like the durable one and it is the opposite. A dynamic subscription lives as long as the session that asked for it. A configured one is written down, so it comes back with the device, and the two words invite you to guess exactly the wrong way round.

And coming back is not the same as working. A subscription restored from configuration still needs everything it depended on to be there: the receiver reachable, the VRF present, the path still supported. A reboot is the test of whether all of that returns together, not just of whether the subscription did.

telemetry ietf subscription 101
  encoding encode-kvgpb
  filter xpath /memory-ios-xe-oper:memory-statistics/memory-statistic
  stream yang-push
  update-policy periodic 6000
  source-vrf Mgmt-intf
  receiver ip address 10.28.35.45 57555 protocol grpc-tcp

The chapter numbers its example 101. In this scenario 101 is the on-change subscription on the interface table, and the chapter's periodic example becomes 104, on memory statistics.

filter xpath: which data. encoding encode-kvgpb: what shape. update-policy: when. receiver ip address … protocol grpc-tcp: who. source-vrf: the VRF the device sources the connection from.

So what changes for on-change? The update-policy line. The chapter's configuration steps give its form as update-policy {on-change | periodic} period, so an on-change subscription takes the other keyword, and one more rule applies:

When creating an on-change subscription, the dampening period must be set to 0 to indicate that there is no dampening period; no other value is supported.

Once 101 is configured on the interface table, what does the device record for it? This course's reading, in the chapter's own detail layout:

CAT9300# show telemetry ietf subscription all detail
Telemetry subscription detail:

  Subscription ID: 101
  Type: Configured
  State: Valid
  Stream: yang-push
  Encoding: encode-kvgpb
  Filter:
    Filter type: xpath
    XPath: /iosxe-oper:ios-oper-db/hwidb-table
  Update policy:
    Update Trigger: on-change
    ! On-change, with the dampening period 0: the only value supported.
    Synch on start: Yes
! The chapter also says the initial synchronization "is not controllable". This page doesn't tell you what changing this setting would do.
    Dampening period: 0
  Notes:

  Subscription ID: 102
  State: Valid
  Stream: yang-push
  Encoding: encode-kvgpb
  Filter:
    Filter type: xpath
    XPath: /iosxe-oper:ios-oper-db/hwidb-table
  Update policy:
    Update Trigger: on-change
    Synch on start: Yes
    Dampening period: 0
  Notes: