Understanding OpenConfig and gRPC on Junos Telemetry Interface

 

Starting in Junos OS Release 16.1R3, you can use a set of remote procedure call (RPC) interfaces to configure the Junos Telemetry Interface and stream telemetry data using the gRPC framework. OpenConfig supports the use of vendor-neutral data models for configuring and managing multivendor networks. gRPC is an open source framework that provides secure and reliable transport of data.

Note

OpenConfig for Junos OS and gRPC are supported only on MPCs on MX Series and on PTX Series routers starting with Junos OS Release 16.1R3.

Starting with Junos OS Release 17.2R1, OpenConfig and gRPC are also supported on QFX10000 switches, QFX5200 switches, and PTX1000 routers.

Starting with Junos OS Release 17.3R1, Junos Telemetry Interface is supported on the Routing Control and Board (RCB) on PTX3000 routers, QFX5110 switches, and EX4600 and EX9200 switches.

OpenConfig and gRPC are not supported on MX80 and MX104 routers.

Starting with Junos OS Release 17.4R1, MX2008 routers are supported.

Starting with Junos OS Release 19.1R1, MX Series routers operating with MS-MIC and MS-MPC, QFX10002 switches, and PTX10002 routers are also supported.

Network Agent Software

Implementing OpenConfig with gRPC for Junos Telemetry Interface requires that you download and install a package called Network Agent if your Juniper Networks device is running a version of Junos OS with Upgraded FreeBSD. For all other versions of Junos OS, the Network Agent functionality is embedded in the software. Network Agent functions as a gRPC server and terminates the OpenConfig RPC interfaces. It is also responsible for streaming the telemetry data according to the OpenConfig specification. To view the OpenConfig specification for telemetry, see the OpenConfig Telemetry specification. For more information about OpenConfig for Junos OS, see the OpenConfig Feature Guide.

The Network Agent component also supports server-based Secure Sockets Layer (SSL) authentication. Client-based SSL authentication is not supported. You must install SSL certificates on your Juniper Networks device.

For information about installing the Network Agent package, see Installing the Network Agent Package.

Using OpenConfig for Junos OS to Enable Junos Telemetry Interface

OpenConfig for Junos OS specifies an RPC model to enable the Junos Telemetry Interface. You must download and install the OpenConfig for Junos OS package on your Juniper Networks device This package also includes the required YANG models. Using a Web browser, navigate to the All Junos Platforms software download URL on the Juniper Networks webpage: https://www.juniper.net/support/downloads/. From the Network Management tab, scroll down to select OpenConfig. Select the Software tab. Select the appropriate version of OpenConfig module. Two versions are available, one for devices running Junos OS with Upgraded FreeBSD and another for devices running all other versions of Junos OS. For more information, see Installing the OpenConfig Package and Understanding Junos OS YANG Modules.

The programmatic interface OpenConfigTelemetry that is installed by the Network Agent package defines the telemetry gRPC service. The telemetrySubscribe RPC specifies the following subscription parameters:

  • OpenConfig path that identifies the system resource to stream telemetry data, for example:

    /interfaces/interface/state/counters/

  • Interval at which data is reported and streamed to the collector server, in milliseconds, for example:

    sample_frequency = 4000

The telemetrySubscribe RPC is used by a streaming server, or collector, to request an inline subscription for data at the specified path. The device should then send telemetry data back on the same connection as the subscription request.

Using gRPC to Stream Data

Per the OpenConfig specification, only gRPC-based transport is supported for streaming data. The gRPC server that is installed by the Network Agent package terminates the gRPC sessions from the management system that runs the client. RPC calls trigger the creation of Junos OS sensors that either stream data periodically or report events, which are then funneled onto the appropriate gRPC channel by Network Agent.

Note

Starting in Junos OS Release 18.2R1, when an external streaming server, or collector, provisions sensors to export data through gRPC on devices running Junos OS, the sensor configuration is committed to the junos-analytics instance of the ephemeral configuration database, and the configuration can be viewed by using the show ephemeral-configuration instance junos-analytics operational command. In earlier releases, the sensor configuration is committed to the default instance of the ephemeral configuration database.

See Table 1 for a list and descriptions of the RPCs implemented to the support the Junos Telemetry Interface.

Table 1: Telemetry RPCs

RPC Name

Description

telemetrySubscribe

Specify telemetry parameters and stream data for the specified list of OpenConfig paths.

getTelemetrySubscriptions

Retrieve the list of subscriptions that are created through telemetrySubscribe.

cancelSubscription

Unsubscribe a subscription created through telemetrySubscribe.

Data streamed through gRPC is formatted in OpenConfig key/value pairs in protocol buffers (gpb) messages. In this universal format, keys are strings that correspond to the path of the system resources in the OpenConfig schema for the device being monitored. The values correspond to integers or strings that identify the operational state of the system resource, such as interface counters, and the state of the resource.

Note

Starting in Junos OS Release 18.2R1, data streamed through gRPC can be formatted as protobuf in addition to key/value pairs for OpenConfig-based routing engine (RE) sensors. These sensors are in addition to the packet forwarding engine (PFE) sensors.

The following shows the universal key/value format:

The following example shows how a set of counters for an interface can be represented:

The Network Agent package provides a mapping table that maps field names to the OpenConfig key strings.

Exporting Packet Forwarding Engine Traffic Sensor Data

Starting with Junos OS Release 17.4R1, you can export Packet Forwarding Engine traffic statistics through the Junos Telemetry Interface for MX Series and PTX Series routers. Both UDP and gRPC are supported.

This sensor tracks reporting of Packet Forwarding Engine statistics counters and provides visibility into Packet Forwarding Engine error and drop statistics. The resource name for the sensor is /junos/system/linecard/packet/usage/. The OpenConfig paths report data specific to CPU, NPU and center chip (CC). The following paths are supported:

  • /components/component[name='FPCid:NPUid']/properties/property[name='counter']/state/value, where FPC refers to the Flexible PIC Concentrator and NPU refers to the network processing unit (packet forwarding engine). A sample resource path is /components/component[name='FPC0:NPU3']/properties/property[name='ts-output-pps']/state/value where hwds-data-error is the counter for Hardware Discards: Data Error.

  • /components/component[name='FPCid:CCid’]/properties/property[name='counter’]/state/value , where FPC refers to the Flexible PIC Concentrator and CC refers to the center chip. A sample resource path is /components/component[name='FPC0:CC1']/properties/property[name='lpbk-packets’']/state/value where lpbk-packets is the count of Forward packets specific to FPC0, center chip 1.

  • /components/component[name='FPCid’]/properties/property[name='counter’]/state/value , where FPC refers to the Flexible PIC Concentrator. A sample resource path is /components/component[name='FPC0']/properties/property[name='lts-input-packets’']/state/value where lts-input-packets is the CPU counter Local packets input.

To provision the sensor to export data through gRPC, use the telemetrySubcribe RPC to specify telemetry parameters. For streaming through UDP, all parameters are configured at the [edit services analytics] hierarchy level.

The following is a map of counters to output fields in the show pfe statistics traffic command or show pfe statistics traffic detail command (supported only on MX Series routers).

Enabling “ON CHANGE” Sensor Support Through Network Management Interface (gNMI)

Periodical streaming of OpenConfig operational states and counters has been supported since Junos OS Release 16.1, exporting telemetry data from Juniper equipment to an external collector. While useful in collecting all the needed information and creating a baseline “snapshot,” periodical streaming is less useful for time-critical missions. In such instances, you can configure ON_CHANGE streaming for an external collector to receive information only when operational states experience a change in state.

To support ON_CHANGE streaming, a new specification called gRPC Network Management Interface (gNMI) is implemented for the modification and retrieval of configurations from a network element. Additionally, the gNMI specification can be used to generate and control telemetry streams from a network element to a data collection system. Using the new gNMI specification, one gRPC service definition can provide a single implementation on a network element for both configuration and telemetry as well as a single NMS element to interact with a device by means of telemetry and configuration RPCs.

The Junos file package (junos-telemetry-interface) includes the gnmi.proto file and GnmiJuniperTelemetryHeader.proto Juniper extension for gNMI support.

Information about the RPCs supporting this feature can be found in the gNMI Proto file version 0.4.0 (the supported version) and the specification released

  • https://github.com/openconfig/reference/blob/master/rpc/gnmi/gnmi-specification.md

  • https://github.com/openconfig/gnmi/blob/master/proto/gnmi/gnmi.proto

The telemetry RPC subscribe under gNMI service supports ON_CHANGE streaming. RPC subscribe allows a client to request the target to send it values of particular paths within the data tree. Values may be streamed (STREAM), sent one-off on a long-lived channel (POLL), or sent one-off as a retrieval (ONCE).

If a subscription is made for a top level container with a sample frequency of 0, leaves with ON_CHANGE support are streamed based on events. Other leaves will not be streamed.

Note

In order to permit a device to decide which nodes will be streamed as ON_CHANGE and which will SAMPLE, the collector must subscribe for TARGET_DEFINED with sample_interval.

Enabling Client Streaming and Bidirectional Streaming of Telemetry Sensor Information

Starting with Junos OS Release 18.1R1, OpenConfig support through Remote Procedure Calls (gRPC) and JTI is extended to support client streaming and bidirectional streaming of telemetry sensor information on MX Series and PTX Series routers.

APIs are implemented in Junos based on Protobuf specifications for OpenConfig. These APIs perform configuration, operational state retrieval, and telemetry on Junos routers using gRPC as the transport mechanism.

With client streaming, the client sends a stream of requests to the server instead of a single request. The server typically sends back a single response containing status details and optional trailing metadata. With bidirectional streaming, both client and server send a stream of requests and responses. The client starts the operation by invoking the RPC and the server receives the client metadata, method name, and deadline. The server can choose to send back its initial metadata or wait for the client to start sending requests. The client and server can read and write in any order. The streams operate completely independently.

Junos devices can be managed through API (RPC) prototypes:

  • rpc Capabilities (CapabilityRequest)

    Returns (CapabilityResponse). Allows the client to retrieve the set of capabilities that is supported by the target.

  • rpc Get (GetRequest)

    Returns (GetResponse). Retrieves a snapshot of data from the target.

  • rpc Set (SetRequest)

    Returns (SetResponse). Allows the client to modify the state of data on the target.

  • rpc Subscribe (stream SubscribeRequest)

    Returns (stream SubscribeResponse). Allows a client to request the target to send it values for particular paths within the data tree. These values may be streamed (STREAM) or sent one-off on a long-lived channel (POLL), or sent as a one-off retrieval (ONCE). If a subscription is made for a top-level container with a sample frequency of 0, leaves with ON_CHANGE support are streamed based on events. Other leaves will not be streamed.

Juniper Extension Toolkit (JET) support provides insight to users regarding the status of clients connected to JSD. JET support for gRPC includes expanding the maximum number of clients that can connect to JSD from 8 to 30 (the default remains 5). To specify the maximum number of connections, include the max-connections statement at the [edit system services extension-service request-response grpc] hierarchy level.

To provide information regarding the status of clients connected to JSD, issue the enhanced show extension-service client information command and include the clients or servers options. The clients option displays request-response client information. The servers option displays request-response server information.

Enabling Streaming of Telemetry Sensor Information for SR-TE policies (BGP or Static)

Starting with Junos OS Release 18.3R1, OpenConfig support through gRPC and JTI provides continuous statistics streaming via the same sensor irrespective of the route that is active (BGP or static) for a given Segment Routing Traffic Engineering (SR-TE) policy.

This feature provides support for BGP [DRAFT-SRTE] and statically configured SR-TE policies at ingress routers.

To provision the sensor to export data through gRPC streaming, use the telemetrySubscribe RPC to specify telemetry parameters. Include the resource path /mpls/signaling-protocols/segment-routing/ to export these statistics.

In addition to configuring the sensor, you must enable statistics collection through the Junos OS. To do this, include the statistics configuration statement at the [edit protocols source-packet-routing telemetry] hierarchy level. Optionally, you can limit statistics by including the no-transit or no-ingress parameter.

See Configure a Telemetry Sensor in Junos for instructions on configuring a sensor.

See Guidelines for gRPC Sensors (Junos Telemetry Interface) for further information about resource paths.

Support for LSP Statistics

You can provision the LSP statistics sensor /junos/services/label-switched-path/usage/ to monitor per-MPLS LSP statistics. Telemetry data is streamed from Junos devices and exported through JTI to external collectors at configurable intervals through gRPC without involving polling.

Statistics that are streamed are similar to the output displayed by the operational mode command show mpls lsp bypass statistics.

For bypass LSPs, the following are exported:

  • Bypass LSP originating at the ingress router of the protected LSP.

  • Bypass LSP originating at the transit router of the protected LSP.

  • Bypass LSP protecting the transit LSP as well as the locally originated LSP.

When the bypass LSP is active, traffic is exported both on the bypass LSP and the ingress (protected) LSP.

To provision a sensor to export data through gRPC, use the telemetrySubscribe RPC to specify telemetry parameters. Streaming telemetry data through gRPC also requires the OpenConfig for Junos OS module. Both OpenConfig and Network Agent packages are bundled into the Junos OS image by default.

See Configuring a Junos Telemetry Interface Sensor (CLI Procedure) for information about configuring a UDP (native) sensor.

See Table 2 for the level of LSP sensor support by platform.

Table 2: LSP Support by Platform

Platform

Ingress LSP, UDP

Feature Introduced

Ingress LSP, gRPC Streaming

Feature Introduced

Bypass LSP

Feature Introduced

MX80/MX104

Junos OS Release 15.1F6

Junos OS Release 16.1R3

Junos OS Release 17.2R1

Junos OS Release 17.4R1

Junos OS Release 17.2X75D50+

MX Series with MPC

Junos OS Release 15.1F6

Junos OS Release 16.1R4

Junos OS Release 17.2R1

Junos OS Release 17.4R1

Junos OS Release 17.2X75D50+

PTX5000 with FPC3

Junos OS Release 18.2R1

Junos OS Release 17.4R1

PTX3000 with FPC3

Junos OS Release 15.1F6

Junos OS Release 16.1R3

Junos OS Release 17.2R1

Junos OS Release 16.1R4

Junos OS Release 17.2R1

Junos OS Release 18.2R1

Junos OS Release 17.4R1

Junos OS Release 17.2X75D50+

PTX Series with FPC1/2

Junos OS Release 15.1F6

Junos OS Release 16.1R3

Junos OS Release 17.2R1

Junos OS Release 16.1R4

Junos OS Release 17.2R1

Junos OS Release 18.2R1

Junos OS Release 17.4R1

Junos OS Release 17.2X75D50+

PTX1000

Junos OS Release 16.1R3

Junos OS Release 16.1R4

Junos OS Release 17.2R1

Junos OS Release 17.4R1

Junos OS Release 17.2X75D50+

PTX10000

Junos OS Release 17.3R1

Junos OS Release 17.3R1

Junos OS Release 17.4R1

Junos OS Release 17.2X75D50+

PTX10001-20C

 

Junos OS Release 19.1R1

RSVP bypass LSP originating at transit node

PTX10002

Junos OS Release 19.1R1

Junos OS Release 19.1R1

VMX

Junos OS Release 17.3R1

Junos OS Release 17.3R1

Junos OS Release 17.4R1

Junos OS Release 17.2X75D50+

MX150

Junos OS Release 17.4R1

Junos OS Release 17.4R1

EX4600

Junos OS Release 18.4R1

EX4650

Junos OS Release 18.3R1

Junos OS Release 18.3R1

EX9200

Junos OS Release 17.3R1

QFX10000

QFX5200

Junos OS Release 17.2R1

Junos OS Release 17.2R1

QFX10002

Junos OS Release 19.1R1

Junos OS Release 19.1R1

QFX5100

Junos OS Release 18.2R1

Junos OS Release 18.2R1

QFX5110

Junos OS Release 18.2R1

Junos OS Release 18.2R1

QFX5120-48Y

Junos OS Release 18.3R1

Junos OS Release 18.3R1

QFX5200

Junos OS Release 18.2R1

Junos OS Release 18.2R1

Release History Table
Release
Description
Starting with Junos OS Release 19.1R1, MX Series routers operating with MS-MIC and MS-MPC, QFX10002 switches, and PTX10002 routers are also supported.
Starting in Junos OS Release 18.2R1, when an external streaming server, or collector, provisions sensors to export data through gRPC on devices running Junos OS, the sensor configuration is committed to the junos-analytics instance of the ephemeral configuration database, and the configuration can be viewed by using the show ephemeral-configuration instance junos-analytics operational command.
Starting with Junos OS Release 18.1R1, OpenConfig support through Remote Procedure Calls (gRPC) and JTI is extended to support client streaming and bidirectional streaming of telemetry sensor information on MX Series and PTX Series routers.
Starting with Junos OS Release 18.3R1, OpenConfig support through gRPC and JTI provides continuous statistics streaming via the same sensor irrespective of the route that is active (BGP or static) for a given Segment Routing Traffic Engineering (SR-TE) policy.
Starting with Junos OS Release 17.4R1, MX2008 routers are supported.
Starting with Junos OS Release 17.4R1, you can export Packet Forwarding Engine traffic statistics through the Junos Telemetry Interface for MX Series and PTX Series routers. Both UDP and gRPC are supported.
Starting with Junos OS Release 17.3R1, Junos Telemetry Interface is supported on the Routing Control and Board (RCB) on PTX3000 routers, QFX5110 switches, and EX4600 and EX9200 switches.
Starting with Junos OS Release 17.2R1, OpenConfig and gRPC are also supported on QFX10000 switches, QFX5200 switches, and PTX1000 routers.
Starting in Junos OS Release 16.1R3, you can use a set of remote procedure call (RPC) interfaces to configure the Junos Telemetry Interface and stream telemetry data using the gRPC framework.
OpenConfig for Junos OS and gRPC are supported only on MPCs on MX Series and on PTX Series routers starting with Junos OS Release 16.1R3.