gnmi

package
v0.5.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 12, 2024 License: Apache-2.0 Imports: 27 Imported by: 0

README

Reference gNMI Service (and internal central datastore)

gnmi.GNMIServer serves as the reference implementation of gNMI for lemming and the central datastore for internal tasks/agents.

External Clients

External clients use gNMI to configure and read state of the reference device.

Internal Clients

Lemming is designed as an eventually consistent system where the gNMI cache is used as the central datastore. Commonly, features are implemented using reconcilers: a set of initialization and long-running methods (either of which are optional) that monitor the intended configuration (or other internal state) and modify the operational state of the device to reach the intended state.

However, this pattern is not a requirement, certain features may not need modify state or may react to the operational state (instead of config) of the device. Such features must implement the reconciler interface, because it provides a common lifecycle API. Reconcilers registered when the gNMI cache is created and started once the server is started.

Reconcilers can optionally validate incoming SetRequest to prevent semantically incorrect values from being applied. For example, the interface reconciler can validate that MTU > 64 for Ethernet interfaces.

Reconcilers are created by implementing the Reconciler interface, and optionally using the reconciler Builder to simplify the creation.

See the fakedevice package for examples of reconcilers.

Reconciliation

Reconcilers must implement the the reconciler.Reconciler interface. The reconciler interface is intentionally minimum to minimize the burden of creating reconcilers and allow maximum flexibility when creating a reconciler.

Reacting to Values

Reconcilers can react to values by either calling a raw gNMI operation using the provided GNMIClient argument or by starting a Watch using ygnmi (optionally using WithWatch). ygnmi.Watch can be used monitoring the current state of a set of OpenConfig subtrees/leaves using gNMI.Subscribe.

Updating Values

Reconcilers can update values in the cache by sending raw gNMI set requests using the client or using ygnmi. The gnmiclient package contains special helpers that allow using ygnmi.Update/Replace/Delete on state paths. Generally, internal reconcilers should not be updating config paths as those are set by external users.

NOTE: Currently, Set requests are required to be schema-compliant. NOTE: Replace/Update on non-leaf state values is not yet. See issue.

Validation

Reconcilers can validate intended config before it is applied to the cache. To do so, Reconcilers must return a non-empty set of path prefixes they are interested in validating through Reconciler.ValidationPaths(). For any SetRequest that modifies those paths, the Validate function is called on the global intended config.

Note: this currently implemented as any reconciler that returns > 0 paths is called on every SetRequest.

Reconciler Builders

The reconciler package provides a builder API for creating reconcilers with common use cases:

rec := reconciler.NewTypedBuilder[string]("hostname").
    WithWatch(hostnamePath.Config(), func(ctx context.Context, c *ygnmi.Client, v *ygnmi.Value[string]) error { // Watch hostname config: set hostname, and update state.
        hostname, ok := v.Val()
        if !ok {
            resetHostName()
        }
        setHostName(hostName)
        if _, err := gnmiclient.Update(ctx, c, hostnamePath.State(),hostname); err != nil {
            return log.Warningf("Failed to set hostname: %v",err)
        }
        return ygnmi.Continue
    }).Build()

Alternatively, a custom reconciler implementation matching the Reconciler interface can be created and registered on the gnmi server.

Documentation

Overview

Package gnmi contains a reference on-device gNMI implementation.

Index

Constants

View Source 
const (
	// GNMIModeMetadataKey is the context metadata key used to specify the
	// mode in which the gNMI server should operate.
	GNMIModeMetadataKey = "gnmi-mode"
	// ConfigMode indicates that the gNMI service will allow updates to
	// intended configuration, but not operational state values.
	ConfigMode Mode = "config"
	// StateMode indicates that the gNMI service will allow updates to
	// operational state, but not intended configuration values.
	StateMode Mode = "state"

	// TimestampMetadataKey is the context metadata key used to specify a
	// custom timestamp for the values in the SetRequest instead of using
	// the time at which the SetRequest is received by the server.
	TimestampMetadataKey = "gnmi-timestamp"
)
View Source 
const (
	// InternalOrigin is a special gNMI path origin used to store schemaless values.
	InternalOrigin = "lemming-internal"
)
View Source 
const (
	OpenConfigOrigin = "openconfig"
)

Variables

This section is empty.

Functions

func AddTimestampMetadata 

func AddTimestampMetadata(ctx context.Context, timestamp int64) context.Context

AddTimestampMetadata adds a gNMI timestamp metadata to the context.

- ctx is the context to be used for accessing lemming's internal datastore. - timestamp is the number of nanoseconds since Epoch.

NOTE: The output of this function should only be used to call into the internal lemming gNMI server. This is because it adds an incoming rather than an outgoing context metadata to skip regular protobuf handling.

func NewSubscribeTargetUpdateInterceptor added in v0.4.0 

func NewSubscribeTargetUpdateInterceptor(target string) func(srv any, ss grpc.ServerStream, info *grpc.StreamServerInfo, handler grpc.StreamHandler) error

NewSubscribeTargetUpdateInterceptor returns a stream interceptor to populate gNMI Subscribe's target if it's not populated in the SubscribeRequest message in order to retrieve the device's data.

ref: https://www.openconfig.net/docs/gnmi/gnmi-specification/#2221-path-target

Types

type Collector 

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

Collector is a basic gNMI target that supports only the Subscribe RPC, and acts as a cache for exactly one target.

func NewCollector 

func NewCollector(targetName string) *Collector

NewCollector returns an initialized gNMI Collector implementation.

To create a gNMI server that supports gnmi.Set as well, use New() instead.

func (*Collector) GnmiUpdate added in v0.4.0 

func (c *Collector) GnmiUpdate(n *gpb.Notification) error

GnmiUpdate sends a pb.Notification into the target cache.

It simply forwards it to the gNMI cache implementation, populating the target (without copying the message) if empty.

func (*Collector) Start 

func (c *Collector) Start(ctx context.Context, sendMeta bool) (*subscribe.Server, error)

Start starts the collector and returns a linked gNMI server that supports gnmi.Subscribe.

func (*Collector) Stop 

func (c *Collector) Stop()

Stop halts the running collector.

func (*Collector) TargetUpdate 

func (c *Collector) TargetUpdate(m *gpb.SubscribeResponse)

TargetUpdate provides an input gNMI SubscribeResponse to update the cache and clients with.

type Mode 

type Mode string

Mode indicates the mode in which the gNMI service operates.

type PathAuth added in v0.2.0 

type PathAuth interface {
	// CheckPermit returns if the user is allowed to read from or write from in the input path.
	CheckPermit(path *gpb.Path, user string, write bool) bool
	// IsInitialized returns if the authorized has been initialized, if not authorization is not checked.
	IsInitialized() bool
}

PathAuth is an interface for checking authorization for gNMI paths.

type Server 

type Server struct {
	// The subscribe Server implements only Subscribe for gNMI.
	*subscribe.Server

	// TODO(wenbli): Implement gnmi.Get and remove this.
	GetResponses []interface{}
	// contains filtered or unexported fields
}

Server is a reference gNMI implementation.

func New 

func New(srv *grpc.Server, targetName string, pa PathAuth, recs ...reconciler.Reconciler) (*Server, error)

New creates and registers a reference gNMI server on the given gRPC server.

To avoid having to specify the Target field in gNMI requests in order to comply with https://www.openconfig.net/docs/gnmi/gnmi-specification/#2221-path-target, register the gRPC interceptor grpc.StreamInterceptor(gnmi.NewSubscribeTargetUpdateInterceptor(targetName)) when creating your grpc.Server object.

- targetName is the gNMI target name of the datastore. - pa is an optional PathAuth instance used for authorization gNMI requests, set to nil for no authorization.

func (*Server) Capabilities 

func (s *Server) Capabilities(context.Context, *gpb.CapabilityRequest) (*gpb.CapabilityResponse, error)

func (*Server) Get 

func (s *Server) Get(context.Context, *gpb.GetRequest) (*gpb.GetResponse, error)

func (*Server) LocalClient 

func (s *Server) LocalClient() gpb.GNMIClient

LocalClient returns a gNMI client for the server.

func (*Server) Set 

func (s *Server) Set(ctx context.Context, req *gpb.SetRequest) (*gpb.SetResponse, error)

Set implements lemming's gNMI Set operation.

If the given SetRequest is schema compliant AND passes higher-level validators, then the gNMI datastore is updated. Otherwise, the gNMI datastore is untouched and an error is returned.

Context metadata modifies the behaviour of this API. - GNMIModeMetadataKey specifies whether config or state leaves are expected in the SetRequest. This is an exclusive expectation: either the update consists solely of config values (a user request), or state values (an internal goroutine update). - TimestampMetadataKey specifies the timestamp for state leaf updates. This is to support cases where the data comes from an externally-timestamped source.

func (*Server) StartReconcilers 

func (s *Server) StartReconcilers(ctx context.Context) error

StartReconcilers starts all the reconcilers.

func (*Server) StopReconcilers 

func (s *Server) StopReconcilers(ctx context.Context) error

StopReconcilers stops all the reconcilers.

func (*Server) Subscribe added in v0.2.0 

func (s *Server) Subscribe(srv gpb.GNMI_SubscribeServer) error

Subscribe wraps the internal subscribe with optional authorization.

Source Files

View all Source files

Directories

Path Synopsis
Package gnmiclient contains a funcs to create gNMI for the local cache.
 Package gnmiclient contains a funcs to create gNMI for the local cache.
oc
Package oc is a generated package which contains definitions of structs which represent a YANG schema.
 Package oc is a generated package which contains definitions of structs which represent a YANG schema.
acl
Package acl is a generated package which contains definitions of structs which generate gNMI paths for a YANG schema.
 Package acl is a generated package which contains definitions of structs which generate gNMI paths for a YANG schema.
bgpgue
Package bgpgue is a generated package which contains definitions of structs which generate gNMI paths for a YANG schema.
 Package bgpgue is a generated package which contains definitions of structs which generate gNMI paths for a YANG schema.
definedsets
Package definedsets is a generated package which contains definitions of structs which generate gNMI paths for a YANG schema.
 Package definedsets is a generated package which contains definitions of structs which generate gNMI paths for a YANG schema.
interfaces
Package interfaces is a generated package which contains definitions of structs which generate gNMI paths for a YANG schema.
 Package interfaces is a generated package which contains definitions of structs which generate gNMI paths for a YANG schema.
keychain
Package keychain is a generated package which contains definitions of structs which generate gNMI paths for a YANG schema.
 Package keychain is a generated package which contains definitions of structs which generate gNMI paths for a YANG schema.
lacp
Package lacp is a generated package which contains definitions of structs which generate gNMI paths for a YANG schema.
 Package lacp is a generated package which contains definitions of structs which generate gNMI paths for a YANG schema.
lldp
Package lldp is a generated package which contains definitions of structs which generate gNMI paths for a YANG schema.
 Package lldp is a generated package which contains definitions of structs which generate gNMI paths for a YANG schema.
netinstbgp
Package netinstbgp is a generated package which contains definitions of structs which generate gNMI paths for a YANG schema.
 Package netinstbgp is a generated package which contains definitions of structs which generate gNMI paths for a YANG schema.
netinstisis
Package netinstisis is a generated package which contains definitions of structs which generate gNMI paths for a YANG schema.
 Package netinstisis is a generated package which contains definitions of structs which generate gNMI paths for a YANG schema.
networkinstance
Package networkinstance is a generated package which contains definitions of structs which generate gNMI paths for a YANG schema.
 Package networkinstance is a generated package which contains definitions of structs which generate gNMI paths for a YANG schema.
ocpath
Package ocpath is a generated package which contains definitions of structs which generate gNMI paths for a YANG schema.
 Package ocpath is a generated package which contains definitions of structs which generate gNMI paths for a YANG schema.
platform
Package platform is a generated package which contains definitions of structs which generate gNMI paths for a YANG schema.
 Package platform is a generated package which contains definitions of structs which generate gNMI paths for a YANG schema.
qos
Package qos is a generated package which contains definitions of structs which generate gNMI paths for a YANG schema.
 Package qos is a generated package which contains definitions of structs which generate gNMI paths for a YANG schema.
routingpolicy
Package routingpolicy is a generated package which contains definitions of structs which generate gNMI paths for a YANG schema.
 Package routingpolicy is a generated package which contains definitions of structs which generate gNMI paths for a YANG schema.
system
Package system is a generated package which contains definitions of structs which generate gNMI paths for a YANG schema.
 Package system is a generated package which contains definitions of structs which generate gNMI paths for a YANG schema.
Package reconciler contains a common interface for gNMI reconciler.
 Package reconciler contains a common interface for gNMI reconciler.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.