gnmi

Documentation

Overview

Package gnmi provides an API to provides an API for querying telemetry and setting the state of the device via gNMI.

This package provides test helpers that wrap API calls to the ygnmi library. Ondatra uses ygnmi (and by extension ygot) to autogenerate gNMI paths and value structs from an input set of YANG modules. Please read the ygnmi README to learn how ygnmi translates gNMI paths to Go API calls and how it handles noncompliance errors in telemetry it receives.

Available gNMI Paths

Ondatra provide a combination of OpenConfig and Open Traffic Generator YANG modules as input to the ygnmi auto-generation.

The OpenConfig paths are documented here:

• https://openconfig.net/projects/models/paths/
• https://openconfig.net/projects/models/schemadocs/

Information on the Open Traffic Generator YANG modules is available here:

• https://github.com/open-traffic-generator/models-yang

If you are using the IxNetwork (aka "ATE") API, see the IxNetwork Telemetry section below to learn which OpenConfig paths are supported by our IxNetwork gNMI implementation.

Best Practice: Avoid time.Sleep

A test often defines a goal state based on telemetry and waits for the device to reach that state. It may be tempting to add a `time.Sleep` call to insert such a wait into the test, but sleeping is both flaky (the sleep may be too short) and wasteful (the sleep may be unnecessarily long). Tests can more reliably and efficiently wait for a particular telemetry state by using Await or Watch.

Example 1: To wait to an interface to be up, use Await:

gnmi.Await(t, dut, gnmi.OC().Interface(dp.Name()).OperStatus().State(), time.Minute, oc.Interface_OperStatus_UP)

Example 2: To wait for at least 100 packets to be sent, use Watch. Using Await would not be wise here, because the counter may never register exactly 100.

watch := gnmi.Watch(t, dut, gnmi.OC().Interface(dp.Name()).Counters().OutPkts().State(), time.Minute, func(val *ygnmi.Value[uint64]) bool {
	count, ok := val.Val()
	return ok && count > 100
})
if val, ok := watch.Await(t); !ok {
	t.Fatalf("DUT did not reach target state: got %v", val)
}

Example 3: To wait for several interfaces to be up in parallel, use a batch query with Watch. Using multiple Await calls wouldn't be as efficient, because that would cause the test to wait for each interface in serial.

batch := gnmi.OCBatch()
for _, port := range dut.Ports() {
	batch.AddPaths(gnmi.OC().Interface(port.Name()))
}
watch := gnmi.Watch(t, dut, batch.State(), time.Minute, func(val *ygnmi.Value[*oc.Root]) bool {
	root, _ := val.Val()
	for _, port := range dut.Ports() {
		if root.GetInterface(port.Name()).GetOperStatus() != oc.Interface_OperStatus_UP {
			return false
		}
	}
	return true
})
if val, ok := watch.Await(t); !ok {
	t.Fatalf("DUT did not reach target state: got %v", val)
}

IxNetwork Telemetry

When using Ondatra's IxNetwork (aka "ATE") API, a test can gather statistics and protocol data about the IxNetwork session via gNMI. This section describes the available IxNetwork telemetry and the corresponding OpenConfig paths at which it can be queried. As the IxNetwork telemetry requires a conversion from a REST API to gNMI, you may encounter some necessary limitations in its behavior.

To query IxNetwork Port Stats:

gnmi.OC().Interface($PortName)

To query IxNetwork Port CPU Stats:

gnmi.OC().Component($PortName).Cpu()

To query IxNetwork Flow Stats:

gnmi.OC().Flow($FlowName)

To query IxNetwork Ingress Flow Stats:

gnmi.OC().Flow($FlowName).IngressTrackingAny()

To query IxNetwork Egress Flow Stats:

gnmi.OC().Flow($FlowName).EgressTrackingAny()

Learned routing data is exported under an OpenConfig "network instance" with the same name as the interface over which the data was learned. Specifically, routing data is available under gNMI paths that start "gnmi.OC().NetworkInstance($InterfaceName)" where "$InterfaceName" is the argument to an "ate.AddInterface($InterfaceName)" call in the test.

To query BGP IPv4 RIB learned routing data:

gnmi.OC().NetworkInstance($InterfaceName).
	Protocol(oc.PolicyTypes_INSTALL_PROTOCOL_TYPE_BGP, "0").Bgp().Rib().
	AfiSafi(oc.BgpTypes_AFI_SAFI_TYPE_IPV4_UNICAST).Ipv4Unicast().
	Neighbor($DutIp).AdjRibInPre().Route($Prefix, $PathId)

To query BGP IPv6 RIB learned routing data:

gnmi.OC().NetworkInstance($InterfaceName).
	Protocol(oc.PolicyTypes_INSTALL_PROTOCOL_TYPE_BGP, "0").Bgp().Rib().
	AfiSafi(oc.BgpTypes_AFI_SAFI_TYPE_IPV6_UNICAST).Ipv6Unicast().
	Neighbor($DutIp).AdjRibInPre().Route($Prefix, $PathId)

To query BGP Attr Sets learned routing data:

gnmi.OC().NetworkInstance($InterfaceName).
	Protocol(oc.PolicyTypes_INSTALL_PROTOCOL_TYPE_BGP, "0").Bgp().Rib().
	AttrSet($Index)

To query BGP Communities learned routing data:

gnmi.OC().NetworkInstance($InterfaceName).
	Protocol(oc.PolicyTypes_INSTALL_PROTOCOL_TYPE_BGP, "0").Bgp().Rib().
	Community($Index)

To query ISIS LSPs learned routing data:

gnmi.OC().NetworkInstance($InterfaceName).
	Protocol(oc.PolicyTypes_INSTALL_PROTOCOL_TYPE_ISIS, "0").Isis().
	Level($LevelNum).Lsp($LspId)

To query RSVP-TE Sessions learned routing data:

gnmi.OC().NetworkInstance($InterfaceName).Mpls().SignalingProtocols().
	RsvpTe().SessionId($LocalIndex)

Index

• func Await[T any](t testing.TB, dev DeviceOrOpts, q ygnmi.SingletonQuery[T], ...) *ygnmi.Value[T]
• func BatchDelete[T any](sb *SetBatch, q ygnmi.ConfigQuery[T])
• func BatchReplace[T any](sb *SetBatch, q ygnmi.ConfigQuery[T], val T)
• func BatchUnionReplace[T any](sb *SetBatch, q ygnmi.ConfigQuery[T], val T)
• func BatchUnionReplaceCLI(sb *SetBatch, nos, ascii string)
• func BatchUpdate[T any](sb *SetBatch, q ygnmi.ConfigQuery[T], val T)
• func Delete[T any](t testing.TB, dev DeviceOrOpts, q ygnmi.ConfigQuery[T]) *ygnmi.Result
• func Get[T any](t testing.TB, dev DeviceOrOpts, q ygnmi.SingletonQuery[T]) T
• func GetAll[T any](t testing.TB, dev DeviceOrOpts, q ygnmi.WildcardQuery[T]) []T
• func Lookup[T any](t testing.TB, dev DeviceOrOpts, q ygnmi.SingletonQuery[T]) *ygnmi.Value[T]
• func LookupAll[T any](t testing.TB, dev DeviceOrOpts, q ygnmi.WildcardQuery[T]) []*ygnmi.Value[T]
• func LookupConfig[T any](t testing.TB, dev DeviceOrOpts, q ygnmi.ConfigQuery[T]) *ygnmi.Value[T]
• func OC() *ocpath.RootPath
• func OCBatch() *ocpath.Batch
• func OTG() *otgpath.RootPath
• func OTGBatch() *otgpath.Batch
• func Replace[T any](t testing.TB, dev DeviceOrOpts, q ygnmi.ConfigQuery[T], val T) *ygnmi.Result
• func Update[T any](t testing.TB, dev DeviceOrOpts, q ygnmi.ConfigQuery[T], val T) *ygnmi.Result
• type Collector
  • func Collect[T any](t testing.TB, dev DeviceOrOpts, q ygnmi.SingletonQuery[T], ...) *Collector[T]
  • func CollectAll[T any](t testing.TB, dev DeviceOrOpts, q ygnmi.WildcardQuery[T], ...) *Collector[T]
  • func (c *Collector[T]) Await(t testing.TB) []*ygnmi.Value[T]
• type DeviceOrOpts
• type Opts
  • func NewOpts(id string, useGetForConfig bool, ...) *Opts
  • func (o *Opts) GNMIOpts() *Opts
  • func (o *Opts) WithClient(client gpb.GNMIClient) *Opts
  • func (o *Opts) WithMetadata(md metadata.MD) *Opts
  • func (o *Opts) WithYGNMIOpts(opts ...ygnmi.Option) *Opts
• type SetBatch
  • func (sb *SetBatch) Set(t testing.TB, dev DeviceOrOpts) *ygnmi.Result
• type Watcher
  • func Watch[T any](t testing.TB, dev DeviceOrOpts, q ygnmi.SingletonQuery[T], ...) *Watcher[T]
  • func WatchAll[T any](t testing.TB, dev DeviceOrOpts, q ygnmi.WildcardQuery[T], ...) *Watcher[T]
  • func (w *Watcher[T]) Await(t testing.TB) (*ygnmi.Value[T], bool)
  • func (w *Watcher[T]) Cancel()

Functions

func Await

func Await[T any](t testing.TB, dev DeviceOrOpts, q ygnmi.SingletonQuery[T], timeout time.Duration, val T) *ygnmi.Value[T]

Await observes values at Query with a STREAM subscription, blocking until a value that is deep equal to the specified val is received or the timeout is reached. To wait for a generic predicate, or to make a non-blocking call, use the Watch method instead.

func BatchDelete

func BatchDelete[T any](sb *SetBatch, q ygnmi.ConfigQuery[T])

BatchDelete stores a delete operation in the SetBatch.

func BatchReplace

func BatchReplace[T any](sb *SetBatch, q ygnmi.ConfigQuery[T], val T)

BatchReplace stores an replace operation in the SetBatch.

func BatchUnionReplace

func BatchUnionReplace[T any](sb *SetBatch, q ygnmi.ConfigQuery[T], val T)

BatchUnionReplace stores a union_replace operation in the SetBatch.

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

func BatchUnionReplaceCLI

func BatchUnionReplaceCLI(sb *SetBatch, nos, ascii string)

BatchUnionReplaceCLI stores a CLI union_replace operation in the SetBatch.

• nos is the name of the Network operating system. "_cli" is appended to it to form the origin, see https://github.com/openconfig/reference/blob/master/rpc/gnmi/gnmi-union_replace.md#24-native-cli-configuration-cli
• ascii is the full CLI text.

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

func BatchUpdate

func BatchUpdate[T any](sb *SetBatch, q ygnmi.ConfigQuery[T], val T)

BatchUpdate stores an update operation in the SetBatch.

func Delete

func Delete[T any](t testing.TB, dev DeviceOrOpts, q ygnmi.ConfigQuery[T]) *ygnmi.Result

Delete deletes the configuration at the given query path.

func Get

func Get[T any](t testing.TB, dev DeviceOrOpts, q ygnmi.SingletonQuery[T]) T

Get fetches the value of a SingletonQuery with a ONCE subscription, failing the test fatally if no value is present at the path. Use Lookup to also get metadata or tolerate no value present.

func GetAll

func GetAll[T any](t testing.TB, dev DeviceOrOpts, q ygnmi.WildcardQuery[T]) []T

GetAll fetches the value of a WildcardQuery with a ONCE subscription skipping any non-present paths. It fails the test fatally if no value is present at the path Use LookupAll to also get metadata or tolerate no values present.

func Lookup

func Lookup[T any](t testing.TB, dev DeviceOrOpts, q ygnmi.SingletonQuery[T]) *ygnmi.Value[T]

Lookup fetches the value of a ygnmi.SingletonQuery with a ONCE subscription.

func LookupAll

func LookupAll[T any](t testing.TB, dev DeviceOrOpts, q ygnmi.WildcardQuery[T]) []*ygnmi.Value[T]

LookupAll fetches the values of a ygnmi.WildcardQuery with a ONCE subscription. It returns an empty list if no values are present at the path.

func LookupConfig

func LookupConfig[T any](t testing.TB, dev DeviceOrOpts, q ygnmi.ConfigQuery[T]) *ygnmi.Value[T]

LookupConfig fetches the value of a ygnmi.SingletonQuery with a ONCE subscription. Note: This is a workaround for Go's type inference not working for this use case and may be removed in a subsequent release. Note: This is equivalent to calling Lookup with a ConfigQuery and providing a fully-qualified type parameter.

func OC

func OC() *ocpath.RootPath

OC returns the root OpenConfig gNMI path.

func OCBatch

func OCBatch() *ocpath.Batch

OCBatch returns a new batch collection of OpenConfig gnmi paths.

func OTG

func OTG() *otgpath.RootPath

OTG returns the root Open Traffic Generator gNMI path.

func OTGBatch

func OTGBatch() *otgpath.Batch

OTGBatch returns a new batch collection of Open Traffic Generator gnmi paths.

func Replace

func Replace[T any](t testing.TB, dev DeviceOrOpts, q ygnmi.ConfigQuery[T], val T) *ygnmi.Result

Replace replaces the configuration at the given query path with the val.

func Update

func Update[T any](t testing.TB, dev DeviceOrOpts, q ygnmi.ConfigQuery[T], val T) *ygnmi.Result

Update updates the configuration at the given query path with the val.

Types

type Collector

type Collector[T any] struct {
	// contains filtered or unexported fields
}

Collector represents an ongoing collection of telemetry values.

func Collect

func Collect[T any](t testing.TB, dev DeviceOrOpts, q ygnmi.SingletonQuery[T], timeout time.Duration) *Collector[T]

Collect starts an asynchronous collection of the values at the query with a STREAM subscription. Calling Await on the return Collection waits until the timeout is reached and returns the collected values.

func CollectAll

func CollectAll[T any](t testing.TB, dev DeviceOrOpts, q ygnmi.WildcardQuery[T], timeout time.Duration) *Collector[T]

CollectAll starts an asynchronous collection of the values at the query with a STREAM subscription. Calling Await on the return Collection waits until the timeout is reached and returns the collected values.

func (*Collector[T]) Await

func (c *Collector[T]) Await(t testing.TB) []*ygnmi.Value[T]

Await waits for the collection to finish and returns all received values. When Await returns the watcher is closed, and Await may not be called again. Note: the func blocks until the timeout is reached.

type DeviceOrOpts

type DeviceOrOpts interface {
	GNMIOpts() *Opts
}

DeviceOrOpts is an interface that is ondatra.Device or a gnmi.Opts

type Opts

type Opts struct {
	// contains filtered or unexported fields
}

Opts contains customs options for a gNMI request.

func NewOpts

func NewOpts(id string, useGetForConfig bool, initClient func(context.Context) (gpb.GNMIClient, error)) *Opts

NewOpts creates a set of GNMI options. DO NOT USE: call dut.GNMIOpts() or ate.OTG().GNMIOpts() instead.

func (*Opts) GNMIOpts

func (o *Opts) GNMIOpts() *Opts

GNMIOpts implements the DeviceOrOpts interface.

func (*Opts) WithClient

func (o *Opts) WithClient(client gpb.GNMIClient) *Opts

WithClient sets a custom gNMI client to the client, overriding any set by previous calls.

func (*Opts) WithMetadata

func (o *Opts) WithMetadata(md metadata.MD) *Opts

WithMetadata adds metadata to the outgoing context, overriding any set by previous calls.

func (*Opts) WithYGNMIOpts

func (o *Opts) WithYGNMIOpts(opts ...ygnmi.Option) *Opts

WithYGNMIOpts adds the ygnmi Options to the client, overriding any set by previous calls.

type SetBatch

type SetBatch struct {
	// contains filtered or unexported fields
}

SetBatch allows multiple Set operations (Replace, Update, Delete) to be applied as part of a single Set transaction. Use BatchUpdate, BatchReplace, BatchDelete to add operations, and then call the Set method to send the SetRequest.

func (*SetBatch) Set

func (sb *SetBatch) Set(t testing.TB, dev DeviceOrOpts) *ygnmi.Result

Set performs the gnmi.Set request with all queued operations.

type Watcher

type Watcher[T any] struct {
	// contains filtered or unexported fields
}

Watcher represents an ongoing watch of telemetry values.

func Watch

func Watch[T any](t testing.TB, dev DeviceOrOpts, q ygnmi.SingletonQuery[T], timeout time.Duration, pred func(*ygnmi.Value[T]) bool) *Watcher[T]

Watch starts an asynchronous STREAM subscription, evaluating each observed value with the specified predicate. The subscription completes when either the predicate is true or the timeout is reached. Calling Await on the returned Watcher waits for the subscription to complete. It returns the last observed value and a boolean that indicates whether that value satisfies the predicate.

func WatchAll

func WatchAll[T any](t testing.TB, dev DeviceOrOpts, q ygnmi.WildcardQuery[T], timeout time.Duration, pred func(*ygnmi.Value[T]) bool) *Watcher[T]

WatchAll starts an asynchronous STREAM subscription, evaluating each observed value with the specified predicate. The subscription completes when either the predicate is true or the timeout is reached. Calling Await on the returned Watcher waits for the subscription to complete. It returns the last observed value and a boolean that indicates whether that value satisfies the predicate.

func (*Watcher[T]) Await

func (w *Watcher[T]) Await(t testing.TB) (*ygnmi.Value[T], bool)

Await waits for the watch to finish and returns the last received value and a boolean indicating whether the predicate evaluated to true. When Await returns the watcher is closed, and Await may not be called again.

func (*Watcher[T]) Cancel

func (w *Watcher[T]) Cancel()

Cancel stops the watch immediately.