gNMI Streaming
The gRPC Network Management Interface (gNMI) can collect and export system resources, interface, and counter information from NVOS to your gNMI client.
The gNMI server feature state can be set over NVOS using simple NVUE CLI commands:
Show command:
nvos@switch:~$ nv show system gnmi-server
operational applied
---------- ----------- -------
state enabled enabled
is-running yes
version 4.12.0
Set command:
nvos@switch:~$ nv set system gnmi-server state <enabled | disabled>
Unset command:
nvos@switch:~$ nv unset system gnmi-server state
The state is enabled by default and the unset command will restore the state to enabled, if it is not already.
NVOS supports the following gNMI subscription modes:
STREAM Mode: In this mode, the client subscribes to receive updates whenever there is a change in the telemetry data. This mode is suitable for scenarios where you need real-time notifications of data changes.
ONCE Mode: This mode retrieves the data once and then terminates the subscription. It's ideal for scenarios where a single snapshot of the data is needed without ongoing updates.
POLL Mode: In this mode, the client periodically requests data from the server. This mode allows clients to fetch data at defined intervals, providing a balance between real-time and scheduled updates.
Supported stream modes:
ON_CHANGE- when a subscription is defined to be "on change", data updates are only sent when the value of the data item changes.SAMPLE- This mode allows clients to receive periodic samples of telemetry data at specified intervals. This mode is beneficial for scenarios where continuous streaming of data is not necessary, but periodic updates are required for monitoring and analytics.
Key Parameters for STREAM SAMPLE Mode:
sample_interval (mandatory): Defines the interval at which samples are sent to the client. This parameter controls the frequency of data transmission.
suppress_redundant (optional, default false): Determines whether redundant data updates, which have not changed since the last sample, should be suppressed. This helps in reducing unnecessary data transmission and optimizing network usage.
heartbeat_interval (optional, default disabled): Specifies the interval for sending heartbeat messages to indicate that the connection is still active. Heartbeats help in monitoring the health of the connection and detecting failures.
Supported Models
NVOS supports the following OpenConfig models (v4.3.0)
|
Model |
Supported Data |
|
Name, Operstatus, AdminStatus, IfIndex, Description, Enabled, Counters (InPkts, OutPkts, InOctets, InUnicastPkts, InDiscards, InMulticastPkts, InErrors, OutOctets, OutUnicastPkts, OutMulticastPkts, OutDiscards, OutErrors) |
|
|
OperStatus, Utilization |
|
|
OperStatus, Speed |
|
|
OperStatus, InputPower, OutputPower, LaserBiasCurrent, LaserTemperature, Present, SupplyVoltage |
|
|
Hostname |
NVOS supports the following NVIDIA models:
|
Model |
|
nvidia-interfaces-infiniband |
|
nvidia-interfaces-infiniband-errors-ext |
|
nvidia-platform-general-ext |
|
nvidia-platform-asic |
|
nvidia-system-events |
|
nvidia-if-phy-diag |
|
nvidia-platform-transceiver-diag |
The YANG models above can be found in the attached YANG zip file.
gNMI client on a host can request capabilities and data from the switch. The examples below use the gNMIc client.
The following example shows a gNMIc STREAM SAMPLE mode request for specific Interface data, with a sample interval of 30 seconds, suppress redundant flag enabled, and heartbeat interval of 120 seconds:
gnmic -a juliet-128 --port 9339 --skip-verify subscribe --prefix "interfaces" --path "/interface[name=sw1p1]" --target nvos -u admin -p ***** --mode stream --stream-mode sample --sample-interval 30s --suppress-redundant --heartbeat-interval 120s
The following example shows a gNMIc STREAM ON-CHANGE mode request for system events, with an updates-only flag enabled:
gnmic -a juliet-128 --port 9339 --skip-verify subscribe --prefix "/system-events" --path "" --target nvos -u admin -p ***** --mode stream --stream-mode on-change --updates-only
The following example shows a gNMIc ONCE mode request and server response for IB interface MTU (-d for debug mode):
gnmic -a 10.7.148.16 --port 9339 --skip-verify subscribe --prefix "interfaces" --path "/interface[name=sw1p1]/infiniband/state/mtu" -d --target nvos -u admin -p ***** --mode once
{
"source": "10.7.148.16",
"subscription-name": "default-1709707931",
"timestamp": 1709707925858795109,
"time": "2024-03-06T08:52:05.858795109+02:00",
"prefix": "interfaces/interface[name=sw1p1]",
"target": "nvos",
"updates": [
{
"Path": "infiniband/state/mtu",
"values": {
"infiniband/state/mtu": 256
}
}
]
}
The following example shows a gNMIc ONCE request for all supported paths:
gnmic -a juliet-128 --port 9339 --skip-verify subscribe --prefix "/" --path "" --target nvos -u admin -p ***** --mode once
The following example shows a gNMIc POLL mode request and server response for FAN1/1 speed:
gnmic -a juliet-128 --port 9339 --skip-verify subscribe --prefix "components" --path "component[name=FAN1/1]/fan/state/speed" --target nvos -u admin -p ***** --format flat --mode poll
components/component[name=FAN1/1]/fan/state/speed: 33
The following example shows a gNMIc STREAM mode request for specific system-event "text" leaf with PROTO encoding:
gnmic -a 10.7.148.16 --port 9339 --skip-verify subscribe --prefix "system-events" --path "system-event[event-id=38]/state/text" --target nvos -u admin -p ***** --encoding proto --format prototext --mode stream
sync_response: true
update: {
timestamp: 1719295967820127958
prefix: {
elem: {
name: "system-events"
}
elem: {
name: "system-event"
key: {
key: "event-id"
value: "38"
}
}
target: "nvos"
}
update: {
path: {
elem: {
name: "state"
}
elem: {
name: "text"
}
}
val: {
string_val: "Interface admin state is up"
}
}
}
The following example shows a gRPC curl command to describe the server using gRPC reflection service:
docker run fullstorydev/grpcurl -H username:admin -H password:***** -insecure gorilla-16:9339 describe
gnmi.gNMI is a service:
service gNMI {
rpc Capabilities ( .gnmi.CapabilityRequest ) returns ( .gnmi.CapabilityResponse );
rpc Get ( .gnmi.GetRequest ) returns ( .gnmi.GetResponse );
rpc Set ( .gnmi.SetRequest ) returns ( .gnmi.SetResponse );
rpc Subscribe ( stream .gnmi.SubscribeRequest ) returns ( stream .gnmi.SubscribeResponse );
}
grpc.reflection.v1.ServerReflection is a service:
service ServerReflection {
rpc ServerReflectionInfo ( stream .grpc.reflection.v1.ServerReflectionRequest ) returns ( stream .grpc.reflection.v1.ServerReflectionResponse );
}
grpc.reflection.v1alpha.ServerReflection is a service:
service ServerReflection {
rpc ServerReflectionInfo ( stream .grpc.reflection.v1alpha.ServerReflectionRequest ) returns ( stream .grpc.reflection.v1alpha.ServerReflectionResponse );
}