statecollector.go

// Copyright (c) 2023 Zededa, Inc.
// SPDX-License-Identifier: Apache-2.0

// Package nistate (Network Instance State) is used by zedrouter to collect
// state data and metrics for Network Instances and watch for state changes.
// The main entry point is the interface of Collector, which is expected
// to eventually have multiple implementations, one for every supported network
// stack (currently EVE only provides one implementation of network instances,
// built using the Linux bridge).
package nistate

import (
	"fmt"
	"net"

	"github.com/lf-edge/eve/pkg/pillar/types"
	uuid "github.com/satori/go.uuid"
)

// LogAndErrPrefix is prepended to every log message and error returned by NI State
// Collector so that they are easy to filter in log file.
const LogAndErrPrefix = "NI State"

// Collector collects and publishes state data of monitored network instances
// (IP address assignments, network flows, interface counters, etc.).
// This is just an interface and the expectation is that there will be one implementation
// for every natively supported network stack.
type Collector interface {
	// StartCollectingForNI : start collecting state data for the given network instance.
	// It is called by zedrouter whenever a new network instance is configured.
	StartCollectingForNI(
		niConfig types.NetworkInstanceConfig, br NIBridge, vifs []AppVIF,
		enableArpSnoop bool) error

	// UpdateCollectingForNI : update state data collecting process to reflect a change
	// in the network or app instance config.
	// It is called by zedrouter whenever a config of an existing network instance changes
	// or when VIF is (dis)connected to/from the NI.
	// Note that not every change in network instance config is supported. For example,
	// network instance type (switch / local) cannot change.
	UpdateCollectingForNI(
		niConfig types.NetworkInstanceConfig, vifs []AppVIF, enableArpSnoop bool) error

	// StopCollectingForNI : stop collecting state data for network instance.
	// It is called by zedrouter whenever a network instance is about to be deleted.
	StopCollectingForNI(niID uuid.UUID) error

	// GetIPAssignments returns information about currently assigned IP addresses
	// to VIFs connected to a given network instance.
	GetIPAssignments(niID uuid.UUID) (VIFAddrsList, error)

	// WatchIPAssignments : watch for changes in IP assignments to VIFs across
	// all network instances enabled for state collecting.
	// Channel type is a slice of VIF address updates - this is used to publish
	// multiple updates in a bulk for efficiency.
	WatchIPAssignments() <-chan []VIFAddrsUpdate

	// GetNetworkMetrics : get statistics (interface, ACL counters) for all
	// network interfaces.
	// This should actually include not only interfaces created for network instances
	// by zedrouter, but also wireless physical ports and bridges created for wired
	// ports by NIM.
	GetNetworkMetrics() (types.NetworkMetrics, error)

	// WatchFlows : get periodic statistics for network flows established between
	// applications and remote endpoints.
	WatchFlows() <-chan types.IPFlow

	// TODO: Maybe add something like GetVIFHealth(), returning info like:
	//           - interface exists?
	//           - is bridged?
	//           - what is the state of bridging, is it forwarding?
	//           - is VLAN config OK?
	//           - is link UP?
	//           - is admin state UP?
	//           - does it have IP address? (local unicast, global unicast)
	//           - does EVE have ARP entry? (not always expected to have it)
	//           - keeps dropping Rx/Tx packets? (since the last health retrieval)
	//           - has zero Rx/Tx counters? (since the last health retrieval)
	//       There could be also method to watch for health changes.
	//       Zedrouter would just log this periodically (e.g. once per hour) and on change.

}

// NIBridge : describes bridge created for a network instance.
// This comes from zedrouter.
type NIBridge struct {
	// NI : UUID of the network instance.
	NI uuid.UUID
	// BrNum : a positive integer number (>0) allocated for the bridge by zedrouter.
	// This number is persisted and doesn't change across app config changes or node
	// reboots.
	BrNum int
	// BrIfName : name of the bridge interface inside the network stack.
	BrIfName string
	// MirrorIfName : name of a (dummy) interface where ICMP, ARP, DNS and DHCP packets
	// are mirrored and can be used for monitoring purposes.
	// Empty if mirroring is not available.
	MirrorIfName string
	// BrIfMAC : MAC address assigned to the bridge.
	// MAC address is generated by zedrouter from BrNum.
	BrIfMAC net.HardwareAddr
}

// AppVIF : describes interface created to connect application with network instance.
// This comes from zedrouter.
type AppVIF struct {
	// App : application UUID.
	App uuid.UUID
	// NI : UUID of the network instance to which the application is connected through
	// this virtual interface.
	NI uuid.UUID
	// AppNum : a positive integer number (>0) allocated for the application by zedrouter.
	// This number is persisted and doesn't change across app config changes or node
	// reboots.
	AppNum int
	// NetAdapterName is the logical name for this interface received from the controller
	// in NetworkAdapter.Name
	NetAdapterName string
	// HostIfName : host-side name of the interface connecting application (guest)
	// with EVE OS (host). This name is generated by zedrouter.
	HostIfName string
	// GuestIfMAC : MAC address assigned to VIF on the guest side (inside the app).
	GuestIfMAC net.HardwareAddr
}

// VIFAddrsList : list of VIFs with addresses assigned to them.
type VIFAddrsList []VIFAddrs

// LookupByAdapterName : Lookup VIF by the Application UUID and VIF adapter name.
func (vifs VIFAddrsList) LookupByAdapterName(
	appID uuid.UUID, adapterName string) *VIFAddrs {
	for i := range vifs {
		if vifs[i].VIF.App == appID && vifs[i].VIF.NetAdapterName == adapterName {
			return &vifs[i]
		}
	}
	return nil
}

// VIFAddrs lists IP addresses assigned to a VIF on the guest side
// (inside the app). This is provided to zedrouter by Collector.
type VIFAddrs struct {
	types.AssignedAddrs
	VIF AppVIF
}

// VIFAddrsUpdate describes a change in the address assignment for a single VIF.
// Prev.VIF and New.VIF are always the same.
// This is provided to zedrouter by Collector.
type VIFAddrsUpdate struct {
	Prev VIFAddrs
	New  VIFAddrs
}

// ErrUnknownNI is returned for requests targeting network instances not known
// to the state collector.
type ErrUnknownNI struct {
	NI uuid.UUID
}

// Error implements the error interface.
func (e ErrUnknownNI) Error() string {
	return fmt.Sprintf(
		"%s: network instance %s is not included in state data collecting",
		LogAndErrPrefix, e.NI.String())
}