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.

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 packetsspecific 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 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.

Release History Table
Release
Description
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.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.