idxvpp2

README

NameToIndex

Note: idxvpp2 package will completely replace idxvpp once all plugins are based on KVScheduler.

The NameToIndex mapping is an extension of the NamedMapping mapping. It is used by VPP Agent plugins that interact with VPP/Linux to map between items with integer handles and the string-based object identifiers used by northbound clients of the Agent.

The mappings are primarily used to match VPP dumps with the northbound configuration. This is essential for the re-configuration and state re-synchronization after failures. Furthermore, a mapping registry may be shared between plugins. For example, ifplugin exposes a sw_if_index->iface_meta mapping (extended NameToIndex) so that other plugins may reference interfaces from objects that depend on them, such as bridge domains or IP routes.

API

Every plugin is allowed to allocate a new mapping using the function NewNameToIndex(logger, title, indexfunction), giving in-memory-only storage capabilities. Specifying indexFunction allows to add user-defined secondary indices.

The NameToIndexRW interface supports read and write operations. While the registry owner is allowed to do both reads and writes, only the read interface NameToIndex is typically exposed to other plugins.

The read-only interface provides item-by-name and item-by-index look-ups using the LookupByName and LookupByIndex functions, respectively. Additionally, a client can use the WatchItems function to watch for changes in the registry related to items with integer handles. The registry owner can change the mapping content using the Put/Delete/Update functions from the underlying NamedMapping.

KVScheduler-owned mapping

Plugins configuring VPP items via KVScheduler (ligato/cn-infra/kvscheduler), are able to let the scheduler to keep the mapping of item metadata up-to-date. WithMetadata() function of KVDescriptor is used to enable/disable the scheduler-managed mapping for item metadata. Normally, the scheduler uses the basic NamedMapping to keep the association between item name and item metadata. Descriptor, however, may provide a mapping factory, building mapping with customized secondary indexes - like NameToIndex or its extensions. The mapping is then available for reading to everyone via scheduler's method GetMetadataMap(descriptor). For mappings customized using the factory, the returned NamedMapping can be then further casted to interface exposing the extra look-ups, but keeping the access read-only.

Example

Here are some simplified code snippets from ifplugin showing how descriptor can define mapping factory for the scheduler, and how the plugin then propagates a read-only access to the mapping, including the extra secondary indexes:

// ifaceidx extends NameToIndex with IP lookups (for full code see plugins/vpp/ifplugin/ifaceidx2):

type IfaceMetadataIndex interface {
	LookupByName(name string) (metadata *IfaceMetadata, exists bool)
	LookupBySwIfIndex(swIfIndex uint32) (name string, metadata *IfaceMetadata, exists bool)
	LookupByIP(ip string) []string /* name */
	WatchInterfaces(subscriber string, channel chan<- IfaceMetadataDto)
}

type IfaceMetadata struct {
	SwIfIndex   uint32
	IpAddresses []string
}

// In descriptor:

func (intfd *IntfDescriptorImpl) WithMetadata() (withMeta bool, customMapFactory kvscheduler.MetadataMapFactory) {
	return true, func() idxmap.NamedMappingRW {
		return ifaceidx.NewIfaceIndex(logrus.DefaultLogger(), "interface-index")
		}
}

// In ifplugin API:

type IfPlugin struct {
	Deps

	intfIndex ifaceidx.IfaceMetadataIndex
}

func (p *IfPlugin) Init() error {
	descriptor := adapter.NewIntfDescriptor(&descriptor.IntfDescriptorImpl{})
	p.Deps.Scheduler.RegisterKVDescriptor(descriptor)

	var withIndex bool
	metadataMap := p.Deps.Scheduler.GetMetadataMap(descriptor.GetName())
	p.intfIndex, withIndex = metadataMap.(ifaceidx.IfaceMetadataIndex)
	if !withIndex {
		return errors.New("missing index with interface metadata")
	}
	return nil
}

func (p *IfPlugin) GetInterfaceIndex() ifaceidx.IfaceMetadataIndex {
	return p.intfIndex
}

Documentation

Overview

Package idxvpp2 extends NamedMapping from cn-infra to provide a map between VPP/Linux items with integer handles and northbound string-based identifiers (logical names).

Index

• type NameToIndex
• type NameToIndexDto
• type NameToIndexRW
  • func NewNameToIndex(logger logging.Logger, title string, indexFunction mem.IndexFunction) NameToIndexRW
• type OnlyIndex
  • func (item *OnlyIndex) GetIndex() uint32
• type WithIndex

Types

type NameToIndex

type NameToIndex interface {
	// LookupByName retrieves a previously stored item identified by
	// <name>. If there is no item associated with the give name in the mapping,
	// the <exists> is returned as *false* and <item> as *nil*.
	LookupByName(name string) (item WithIndex, exists bool)

	// LookupByIndex retrieves a previously stored item identified in VPP/Linux
	// by the given <index>.
	// If there is no item associated with the given index, <exists> is returned
	// as *false* with <name> and <item> both set to empty values.
	LookupByIndex(index uint32) (name string, item WithIndex, exists bool)

	// WatchItems subscribes to receive notifications about the changes in the
	// mapping related to items with integer handles.
	WatchItems(subscriber string, channel chan<- NameToIndexDto)
}

NameToIndex is the "user API" to the registry of items with integer handles. It provides read-only access intended for plugins that need to do the conversions between logical names from NB and VPP/Linux item IDs.

type NameToIndexDto

type NameToIndexDto struct {
	idxmap.NamedMappingEvent
	Item WithIndex
}

NameToIndexDto represents an item sent through watch channel in NameToIndex. In contrast to NamedMappingGenericEvent, it contains item casted to WithIndex.

type NameToIndexRW

type NameToIndexRW interface {
	NameToIndex
	idxmap.NamedMappingRW
}

NameToIndexRW is the "owner API" to the NameToIndex registry. Using this API the owner is able to add/update and delete associations between logical names and VPP/Linux items identified by integer handles.

func NewNameToIndex

func NewNameToIndex(logger logging.Logger, title string,
	indexFunction mem.IndexFunction) NameToIndexRW

NewNameToIndex creates a new instance implementing NameToIndexRW. User can optionally extend the secondary indexes through <indexFunction>.

type OnlyIndex

type OnlyIndex struct {
	Index uint32
}

OnlyIndex can be used to add items into NameToIndex with the integer handle as the only information associated with each item.

func (*OnlyIndex) GetIndex

func (item *OnlyIndex) GetIndex() uint32

GetIndex returns index assigned to the item.

type WithIndex

type WithIndex interface {
	// GetIndex should return integer handle assigned to the item.
	GetIndex() uint32
}

WithIndex is interface that items with integer handle must implement to get indexed by NameToIndex.