bond

package module
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Oct 2, 2024 License: Apache-2.0 Imports: 22 Imported by: 0

README

A Go package to simplify NDK apps development.

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrAckCfgFailed       = errors.New("acknowledge config failed")
	ErrAckCfgOptionNotSet = errors.New("agent is not registered with WaitAckConfig option")
)
View Source 
var (
	// An error is returned if Agent tries to enable
	// WithConfigAcknowledge option without streaming configs.
	ErrAckCfgAndNotStreamCfg = errors.New("agent cannot acknowledge configs unless it enables config stream")
	// An error is returned if Agent tries to enable
	// WithAutoUpdateConfigState option while acknowledging configs.
	ErrAckCfgAndAutoCfgState = errors.New("agent cannot automatically update config state while acknowledging configs")
)
View Source 
var ErrInvalidIpAddr = errors.New("invalid ip address provided")
View Source 
var ErrNhgAddOrUpdateFailed = errors.New("nexthop group add or update failed")
View Source 
var ErrNhgDeleteFailed = errors.New("nexthop group delete failed")
View Source 
var ErrNhgSyncEnd = errors.New("nexthop group sync end failed")
View Source 
var ErrNhgSyncStart = errors.New("nexthop group start failed")
View Source 
var ErrRouteAddOrUpdateFailed = errors.New("route add or update failed")
View Source 
var ErrRouteDeleteFailed = errors.New("route delete failed")
View Source 
var ErrRouteSyncEnd = errors.New("route sync end failed")
View Source 
var ErrRouteSyncStart = errors.New("route sync start failed")
View Source 
var ErrStateAddOrUpdateFailed = errors.New("state add/update failed")
View Source 
var ErrStateDeleteFailed = errors.New("state delete failed")

Functions

func NewGetRequest 

func NewGetRequest(path string, opts ...api.GNMIOption) (*gnmi.GetRequest, error)

NewGetRequest creates a new *gnmi.GetRequest using the provided gNMI path and a GNMIOption list opts. The list of possible GNMIOption(s) can be imported from gnmic api package github.com/openconfig/gnmic/pkg/api. An error is returned in case one of the options is invalid or if gNMI encoding type is not set (e.g. api.EncodingPROTO, api.EncodingJSON).

func NewNextHopGroup 

func NewNextHopGroup(options ...NextHopGroupOption) *ndk.NextHopGroupInfo

NewNextHopGroup creates a NDK nexthop group with the provided option fields. A valid nexthop group requires the following options: WithNetworkInstanceName, WithName, WithIpNextHop or WithMplsNextHop Multiple nexthop(s) can be associated with a nexthop group.

func NewRoute 

func NewRoute(options ...RouteOption) *ndk.RouteInfo

New creates a NDK route with the provided route option fields. A valid route requires the following option fields: WithNetInstName, WithIpPrefix, and WithNextHopGroup. Optional: WithPreference, WithMetric

Types

type Acknowledgement 

type Acknowledgement = ndk.AcknowledgeConfigRequestInfo

func NewAcknowledgement 

func NewAcknowledgement(path string, m Message) *Acknowledgement

NewAcknowledgement creates a config Acknowledgement. - An acknowledgement contains a path in XPath format which targets an app's config YANG schema node. All the possible YANG path targets are listed below with it's corresponding example. - container: /greeter, /greeter/container-node - leaf: /greeter/leaf-node - leaf-list: /greeter/leaf-list-node[leaf-list-node=*] - leaf-list entry: /greeter/leaf-list-node[leaf-list-node=<entry>] - list: /greeter/list-node[name=*] - list entry: /greeter/list-node[name=<entry>] A YANG leaf-list and list entry can be targeted individually with it's <entry> name, instead of using the wildcard '*' character. - An Acknowledgement message m can also be passed in. After a config is acked back to SR Linux, the message m will be reflected in the CLI during commit phase. A message type can either be an output, warning, or error which can be created using the functions (Output, Error, Warning). If either path or message is not provided, an acknowledgement with empty contents will be returned.

type Agent 

type Agent struct {
	Name  string
	AppID uint32

	// NDK streamed notification channels
	Notifications *Notifications
	// contains filtered or unexported fields
}

func NewAgent 

func NewAgent(name string, opts ...Option) (*Agent, []error)

NewAgent creates a new Agent instance.

func (*Agent) AcknowledgeConfig 

func (a *Agent) AcknowledgeConfig(acks ...*Acknowledgement) error

AcknowledgeConfig explicitly acknowledges configs with SR Linux. - If Agent has WithConfigAcknowledge option set, SR Linux will wait for explicit ack from app before commit completing the configuration. Note: an error is returned if app does not have both streaming of configs (WithStreamConfig) and WithConfigAcknowledge options enabled. - This method should only be called once for all configs in a commit (.commit.end). If app calls AcknowledgeConfig multiple times for a commit, any calls after the first one will be ignored by ndk server. - `acks` can contain one or multiple Acknowledgement, each targeting an app YANG config node with a corresponding message. During commit phase, SR Linux will reflect in the CLI all ack messages and their corresponding paths. If a particular ack contains an Error message, the entire commit is rejected during commit phase. SR Linux will then rollback the commit to the app's previous valid running configuration. During rollback, NDK server will then stream to app the valid config notifications. If `acks` is empty, SR Linux will still treat this as a valid acknowledgement, but with empty data.

func (*Agent) DeleteState 

func (a *Agent) DeleteState(path string) error

DeleteState deletes application's state for a YANG list entry or the root container. It takes in a target path which follows XPath format. Possible YANG path targets are the app's root container (e.g. /greeter) or a YANG list entry (e.g. /greeter/list-node[name=entry1]). All state for child schema nodes will be deleted. If empty path is provided, the app's root container is assumed by default and the entire application state is deleted.

func (*Agent) GetWithGNMI 

func (a *Agent) GetWithGNMI(req *gnmi.GetRequest) (*gnmi.GetResponse, error)

GetWithGNMI sends a gnmi.GetRequest and returns a gnmi.GetResponse and an error. To create a gNMI GetRequest, please use NewGetRequest method.

func (*Agent) NextHopGroupAdd 

func (a *Agent) NextHopGroupAdd(nhgs ...*ndk.NextHopGroupInfo) error

NextHopGroupAdd adds nexthop group(s) in SRL. This method takes nexthop group(s) of type NextHopGroupInfo, which is defined in the NDK Go Bindings. NextHopGroupInfo struct(s) can be populated by method NewNextHopGroup with options configured using the With<nhg_field> functions. Options that need to be included are name, network instance name, and nexthop addresses. If errors are encountered during the parsing of addresses or adding of nexthop groups, an error is returned.

func (*Agent) NextHopGroupDelete 

func (a *Agent) NextHopGroupDelete(networkInstance string, name string) error

NextHopGroupDelete deletes a programmed nexthop group that has been added/updated by the NDK. The method takes as inputs the network instance name and the nexthop group name. If errors are encountered during the deletion of nexthop group, an error is returned.

Example: NextHopGroupDelete("default", "ndk_sdk") deletes from programmed config ndk_sdk nexthop group in network instance default.

func (*Agent) NextHopGroupUpdate 

func (a *Agent) NextHopGroupUpdate(nhgs ...*ndk.NextHopGroupInfo) error

NextHopGroupUpdate updates and performs resynchronization on programmed NDK nexthop group(s). Nexthop groups not added as part of this update are removed from the ephemeral configuration. Nexthop groups added as part of this update are added to the ephemeral configuration. This method takes nexthop group(s) of type NextHopGroupInfo, which is defined in the NDK Go Bindings. NextHopGroupInfo struct(s) can be populated by method NewNextHopGroup with options configured using the With<nhg_field> functions. Options that need to be included are name, network instance name, and nexthop(s) details. If errors are encountered during the parsing of addresses or adding of nexthop groups, an error is returned.

Example: If nexthop groups with addresses 1.1.1.1, 1.1.1.2 were previously programmed with NextHopGroupAdd, a NextHopGroupUpdate on nhgs with addresses 1.1.1.2, 1.1.1.3 will result in the final configuration being 1.1.1.2, 1.1.1.3. Nexthop group with address 1.1.1.1, which was previously added, is deleted due to the update.

func (*Agent) ReceiveAppIdNotifications 

func (a *Agent) ReceiveAppIdNotifications(ctx context.Context)

ReceiveAppIdNotifications starts an AppId notification stream and sends notifications to channel `AppId`. If the main execution intends to continue running after calling this method, it should be called as a goroutine. `AppId` chan carries values of type ndk.AppIdentNotification

func (*Agent) ReceiveBfdNotifications 

func (a *Agent) ReceiveBfdNotifications(ctx context.Context)

ReceiveBfdNotifications starts an Bfd Session notification stream and sends notifications to channel `Bfd`. If the main execution intends to continue running after calling this method, it should be called as a goroutine. `Bfd` chan carries values of type ndk.BfdSessionNotification

func (*Agent) ReceiveInterfaceNotifications 

func (a *Agent) ReceiveInterfaceNotifications(ctx context.Context)

ReceiveInterfaceNotifications starts an interface notification stream and sends notifications to channel `Interface`. If the main execution intends to continue running after calling this method, it should be called as a goroutine. `Interface` chan carries values of type ndk.InterfaceNotification.

func (*Agent) ReceiveLLDPNotifications 

func (a *Agent) ReceiveLLDPNotifications(ctx context.Context)

ReceiveLLDPNotifications starts an LLDP neighbor notification stream and sends notifications to channel `Lldp`. If the main execution intends to continue running after calling this method, it should be called as a goroutine. `Lldp` chan carries values of type ndk.LldpNeighborNotification

func (*Agent) ReceiveNetworkInstanceNotifications 

func (a *Agent) ReceiveNetworkInstanceNotifications(ctx context.Context)

ReceiveNetworkInstanceNotifications starts an network instance notification stream and sends notifications to channel `NwInst`. If the main execution intends to continue running after calling this method, it should be called as a goroutine. `NwInst` chan carries values of type ndk.NetworkInstanceNotification

func (*Agent) ReceiveNexthopGroupNotifications 

func (a *Agent) ReceiveNexthopGroupNotifications(ctx context.Context)

ReceiveNexthopGroupNotifications starts a next hop group notification stream and sends notifications to channel `NextHopGroup`. If the main execution intends to continue running after calling this method, it should be called as a goroutine. `NextHopGroup` chan carries values of type ndk.NextHopGroupNotification

func (*Agent) ReceiveRouteNotifications 

func (a *Agent) ReceiveRouteNotifications(ctx context.Context)

ReceiveRouteNotifications starts an route notification stream and sends notifications to channel `Route`. If the main execution intends to continue running after calling this method, it should be called as a goroutine. `Route` chan carries values of type ndk.IpRouteNotification

func (*Agent) RouteAdd 

func (a *Agent) RouteAdd(routes ...*ndk.RouteInfo) error

RouteAdd adds agent IP route(s) in SR Linux. This method takes route(s) of type RouteInfo, which is defined in the NDK Go Bindings. RouteInfo struct(s) can be populated by method NewRoute with options configured using the With<route_field> functions. Options that need to be included are ip prefix, network instance name,and next hop group name. If errors are encountered during the parsing of prefixes or adding of routes, an error is returned.

func (*Agent) RouteDelete 

func (a *Agent) RouteDelete(networkInstance string, prefixes ...string) error

RouteDelete deletes agent IP route(s) in SR Linux. The method takes single or multiple IPv4/IPv6 prefixes under a network instance name (e.g. default). prefixes is a string in the format of "ip/preflen" where ip is the IP address and preflen is the length of the prefix. If errors are encountered during the parsing of prefixes or deleting of routes, an error is returned.

Example: RouteDelete("default", "192.168.11.1/24") deletes from FIB an IPv4 address with a prefix length of 24. Example: RouteDelete("default", "2001:db8::1/64") deletes from FIB an IPv6 address with a prefix length of 64.

func (*Agent) RouteUpdate 

func (a *Agent) RouteUpdate(routes ...*ndk.RouteInfo) error

RouteUpdate updates and performs resynchronization on programmed NDK routes. Routes not added as part of this update are removed from FIB. Routes added as part of this update are added to the FIB. This method takes route(s) of type RouteInfo, which is defined in the NDK Go Bindings. RouteInfo struct(s) can be populated by method NewRoute with options configured using the With<route_field> functions. Options that need to be included are ip prefix, network instance name, and next hop group name. If errors are encountered during the parsing of prefixes or adding of routes, an error is returned.

Example: If routes 1.1.1.1, 1.1.1.2 were previously added to FIB with RouteAdd, RouteUpdate with routes 1.1.1.1, 1.1.1.3 will result in FIB with routes 1.1.1.1, 1.1.1.3. Route 1.1.1.2 that was previously added, is deleted due to the update.

func (*Agent) Start 

func (a *Agent) Start() error

func (*Agent) UpdateState 

func (a *Agent) UpdateState(path, data string) error

UpdateState updates application's state for a YANG list entry or the root container. It takes in a path which follows XPath format. Examples include /greeter, the app's root container or /greeter/list-node[name=entry1], a list entry of `list-node`. data is the target path's json state, which may contain leaf or leaf-list json data. State for paths added with UpdateState may be deleted with DeleteState.

type CommitSeq 

type CommitSeq struct {
	CommitSeq int `json:"commit_seq"`
}

type ConfigNotification 

type ConfigNotification struct {
	Op              string   // NDK config operation
	Path            string   // YANG path that follows XPath format
	PathWithoutKeys string   // YANG path without list keys
	Keys            []string // Value for keys, only returned for YANG list configs
	Json            string   // Entire configuration fragment as JSON string
}

ConfigNotification type defines streamed notification contents. Possible Path targets are the app's root YANG container or any list entries. e.g. /greeter, /greeter/list-node[name=entry1] When all configs for a particular commit have been streamed, app will receive a Config notification with Path .commit.end. PathWithoutKeys is the Path but wihout the list keys. For example, a Path of /greeter/list-a[name=entry1]/list-b would have PathWithoutKeys of /greeter/list-a/list-b. Possible Op values are Create, Update, or Delete. For example: if a config is deleted, the notification would have an Op Delete. Json contains leaf, leaf-list, or child container configs for the target Path.

type Message 

type Message func(n *Acknowledgement)

func Error 

func Error(e string) Message

Error returns an error Message, given the string e.

func Output 

func Output(o string) Message

Output returns an output Message, given the string o.

func Warning 

func Warning(w string) Message

Warning returns a warning Message, given the string w.

type NextHopGroupOption 

type NextHopGroupOption func(n *ndk.NextHopGroupInfo)

Options when adding/updating nexthop groups.

func WithIpNextHop 

func WithIpNextHop(address string, rt ndk.NextHop_ResolveToType, rType ndk.NextHop_ResolutionType) NextHopGroupOption

WithIpNextHop adds a IP nexthop to this nexthop group. An IP nexthop is defined by it's IPv4/IPv6 address, the resolution type, and type of routes it resolves to. address string is in the format of "ip" where ip is the IP address without the prefix length. rt is of type ndk.NextHop_ResolveToType. rType is of type ndk.NextHop_ResolutionType. Both of these params are defined in the NDK Go Bindings.

Example: WithIpNextHop(1.1.1.1, ndk.NextHop_DIRECT, ndk.NextHop_REGULAR)

func WithMplsNextHop 

func WithMplsNextHop(address string, labels []uint32, rt ndk.NextHop_ResolveToType,
	rType ndk.NextHop_ResolutionType) NextHopGroupOption

WithMplsNextHop adds a MPLS nexthop to this nexthop group. A MPLS nexthop is defined by it's IPv4/IPv6 address, a slice of uint32 MPLS labels, the resolution type, and type of routes it resolves to. address string is in the format of "ip" where ip is the IP address without the prefix length. rt is of type ndk.NextHop_ResolveToType. rType is of type ndk.NextHop_ResolutionType. Both of these params are defined in the NDK Go Bindings.

Example: WithMplsNextHop(1.1.1.1, [100], ndk.NextHop_DIRECT, ndk.NextHop_REGULAR)

func WithName 

func WithName(name string) NextHopGroupOption

WithName sets the nexthop group name. NDK expects the input name to end in the format "_sdk" or "_SDK". If the input string does not match the expected format, NextHopGroupAdd returns an error. Specified nhg must be a valid NDK nexthop group that will be programmed with method NextHopGroupAdd or NextHopGroupUpdate. It cannot be a nexthop group configured on SRL.

Example: ndk_sdk

func WithNetworkInstanceName 

func WithNetworkInstanceName(name string) NextHopGroupOption

WithNetworkInstanceName sets the nexthop group network instance name.

Example: default

type Notifications 

type Notifications struct {
	// FullConfigReceived chan receives the value and stores in FullConfig
	// when the entire application's config is received by the stream client.
	//
	// This channel will not be used if streaming of configs
	// is enabled with WithStreamConfig option.
	FullConfigReceived chan struct{}

	// FullConfig holds the application's config as json_ietf encoded string
	// that is retrieved from the gNMI server once the commit is done.
	// Applications are expected to read from this buffer to populate
	// their Config and State struct.
	//
	// This buffer will not be used if streaming of configs
	// is enabled with WithStreamConfig option.
	FullConfig []byte

	// Config chan receives streamed config notifications for each individual app path.
	// The contents of each notification is defined by ConfigNotification type.
	// To stream configs, application has to register
	// Agent with option WithStreamConfig.
	// Otherwise, individual configs will not be streamed and the entire
	// config will be populated to the FullConfig buffer.
	// bond does not allow application to simultaneously
	// stream individual configs while also receiving full config.
	//
	// This channel will not be used if Agent does not
	// have WithStreamConfig option set.
	Config chan *ConfigNotification

	// Interface chan receives streamed interface notifications.
	// Method ReceiveInterfaceNotifications starts stream
	// and populates notifications in chan Interface.
	Interface chan *ndk.InterfaceNotification

	// Route chan receives streamed route notifications.
	// Method ReceiveRouteNotifications starts stream
	// and populates notifications in chan Route.
	Route chan *ndk.IpRouteNotification

	// NextHopGroup chan receives streamed next hop group notifications.
	// Method ReceiveNexthopGroupNotifications starts stream
	// and populates notifications in chan NextHopGroup.
	NextHopGroup chan *ndk.NextHopGroupNotification

	// NwInst chan receives streamed network instance notifications.
	// Method ReceiveNetworkInstanceNotifications starts stream
	// and populates notifications in chan NwInst.
	NwInst chan *ndk.NetworkInstanceNotification

	// Lldp chan receives streamed LLDP neighbor notifications.
	// Method ReceiveLLDPNotifications starts stream
	// and populates notifications in chan Lldp.
	Lldp chan *ndk.LldpNeighborNotification

	// Bfd chan receives streamed Bfd Session notifications.
	// Method ReceiveBfdNotifications starts stream
	// and populates notifications in chan Bfd.
	Bfd chan *ndk.BfdSessionNotification

	// AppId chan receives streamed App identifier notifications.
	// Method ReceiveAppIdNotifications starts stream
	// and populates notifications in chan AppId.
	AppId chan *ndk.AppIdentNotification
}

Notifications contains channels for various NDK notifications. By default, the entire app's configs is stored in config buffer. To populate channels for other notification types (e.g. interface), explicit calls to `Receive<type>Notifications` methods are required.

type Option 

type Option func(*Agent) error

func WithAppRootPath 

func WithAppRootPath(path string) Option

WithAppRootPath sets the root XPATH path for the application configuration.

func WithAutoUpdateConfigState 

func WithAutoUpdateConfigState() Option

WithAutoUpdateConfigState enables SR Linux to automatically update telemetry state for app configs. When configs are commited, the config data will be merged and synced with the app's current state. Note: app will still need to manually update state using UpdateState or DeleteState for non-configurable (config=false) YANG schema nodes. Any json data pushed using UpdateState will override existing state for that YANG path. If all configs for a path (e.g. /greeter) are deleted, the app's state may still not be empty and will contain the json data that was last pushed by UpdateState. An error will be returned if WaitConfigAck is enabled because NDK server requires app configuration to always succeed during commit phase. By default, this option is disabled and state for configs need to be updated manually with UpdateState or DeleteState.

func WithCaching 

func WithCaching() Option

WithCaching enables SR Linux to cache streamed notifications in NDK server. - By default, notifications are not cached and are streamed directly to the application. This optimizes memory usage for NDK server and is useful for apps that require a scaled environment. Notifications, such as Route and NextHopGroups, contain routing info, which can consume significant memory if cached. - If caching is enabled, notifications would contain a NDK operation Op of either Create, Update, or Delete. - If caching is disabled, Create or Update notifications, will instead have an op of CreateOrUpdate. Delete notification Data (e.g. route ownerid) will be nil. However, Delete notification Key contents will always be present. - Note: Config, Network instance, and App id notifications will always be cached in NDK server, regardless of WithCaching set. All other notifications will not be cached by default.

func WithConfigAcknowledge 

func WithConfigAcknowledge() Option

WithConfigAcknowledge enables SR Linux to wait for explicit acknowledgement from app after delivering configuration. After config notifications are streamed in, app will need acknowledge config with `AcknowledgeConfig` method. By default, SR Linux will not wait for acknowledgement from app and will commit complete immediately.

func WithContext 

func WithContext(ctx context.Context, cancel context.CancelFunc) Option

WithContext sets the context and it's cancellation function for the Agent. The context will be cancelled automatically when the application is stopped and receives interrupt or SIGTERM signals.

func WithKeepAlive 

func WithKeepAlive(interval time.Duration, threshold int) Option

WithKeepAlive enables keepalive messages for the application configuration. Every interval seconds, app will send keepalive messages until ndk mgr has failed threshold times.

func WithLogger 

func WithLogger(logger *zerolog.Logger) Option

WithLogger sets the logger for the Agent.

func WithStreamConfig 

func WithStreamConfig() Option

WithStreamConfig enables streaming of application configs for each YANG path. For example: the application will stream in separate configs for the root container (e.g. /greeter) and any YANG list entries (e.g. /greeter/list-node[name=entry1]). Streamed config notification contents are defined by the Config type. Application can receive streamed config notifications from channel Config. The Agent does not stream config notifications by default. Instead, the agent will receive the app's entire configuration and populate the FullConfig buffer.

type RouteOption 

type RouteOption func(r *ndk.RouteInfo)

Options when adding/updating IP routes.

func WithIpPrefix 

func WithIpPrefix(prefix string) RouteOption

WithIpPrefix sets the route ipv4 or ipv6 prefix. prefix string is in the format of "ip/preflen" where ip is the IP address and preflen is the length of the prefix. If the input string does not match the expected format, RouteAdd/Update returns an error.

Example: 192.168.11.2/30

func WithMetric 

func WithMetric(m uint32) RouteOption

WithMetric sets the route metric value.

func WithNetInstName 

func WithNetInstName(n string) RouteOption

WithNetInstName sets the route network instance name.

Example: default

func WithNextHopGroupName 

func WithNextHopGroupName(nhg string) RouteOption

WithNextHopGroupName sets the route Next Hop Group Name. NDK expects the input nhg to end in the format "_sdk" or "_SDK". If the input string does not match the expected format, RouteAdd returns an error. Specified nhg also must be a valid NDK next hop group that is programmed with method NextHopGroupAdd or NextHopGroupUpdate. It cannot be a nexthop group configured on SRL.

Example: ndk_sdk

func WithPreference 

func WithPreference(p uint32) RouteOption

WithPreference sets the route preference value.

Source Files

View all Source files

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.