Help us shape the future of Go! Take the 2026 Go Developer Survey

node

package
v1.21.0-pre.4 Latest Latest
Warning

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

 Go to latest Published: Nov 2, 2026 License: Apache-2.0 Imports: 37 Imported by: 111

Documentation

Overview

Package node provides functionality related to the local and remote node addresses

Index

Constants

View Source 
const (
	LocalNodeTableInitializerName = "local"
)
View Source 
const (
	NodeTableName = "nodes"
)

Variables

View Source 
var (
	NodeNameIndex = statedb.Index[*Node, string]{
		Name: "name",
		FromObject: func(obj *LocalNode) index.KeySet {
			return index.NewKeySet(index.String(obj.Fullname()))
		},
		FromKey:    index.String,
		FromString: index.FromString,
		Unique:     true,
	}
	NodeByName = NodeNameIndex.Query

	// NodeAddressIndex indexes every address of the node. The index is non-unique
	// because configured Cilium internal router addresses may legitimately be
	// shared by every node. Writer resolves all other conflicts according to
	// source priority.
	NodeAddressIndex = statedb.Index[*Node, cmtypes.AddrCluster]{
		Name: "address",
		FromObject: func(obj *Node) index.KeySet {
			keys := make([]index.Key, 0, len(obj.IPAddresses)+4)
			for addr := range obj.addressClusters(nil) {
				keys = append(keys, nodeAddressKey(addr))
			}
			if len(keys) == 0 {
				return index.EmptyKeySet
			}
			return index.NewKeySet(keys[0], keys[1:]...)
		},
		FromKey:    nodeAddressKey,
		FromString: nodeAddressKeyString,
		Unique:     false,
	}
	NodeByAddress = NodeAddressIndex.Query

	NodeLocalIndex = statedb.Index[*Node, bool]{
		Name: "local",
		FromObject: func(obj *LocalNode) index.KeySet {
			if obj.Local == nil {

				return index.KeySet{}
			}
			return index.NewKeySet(index.Bool(true))
		},
		FromKey:    index.Bool,
		FromString: index.BoolString,
		Unique:     true,
	}

	NodeByLocal    = NodeLocalIndex.Query
	LocalNodeQuery = NodeByLocal(true)
)
View Source 
var LocalNodeStoreCell = cell.Module(
	"local-node-store",
	"Provides LocalNodeStore for observing and updating local node info",

	cell.ProvidePrivate(NewNodeTable),
	cell.Provide(provideWriter),
	metrics.Metric(NewNodeMetrics),
	cell.Provide(NewNodeTableAndLocalNodeStore),
	cell.Provide(NewClusterSizeDependantInterval),
)

LocalNodeStoreCell provides the LocalNodeStore instance. The LocalNodeStore is the canonical owner of `types.Node` for the local node and provides a reactive API for observing and updating it.

View Source 
var LocalNodeStoreTestCell = cell.Group(
	cell.Provide(NewNopLocalNodeSynchronizer),
	LocalNodeStoreCell,
)

LocalNodeStoreTestCell is a convenience for tests that provides a no-op LocalNodeSynchronizer. Use LocalNodeStoreCell in tests when you want to provide your own LocalNodeSynchronizer.

Functions

func FirstGlobalV4Addr added in v1.20.0 

func FirstGlobalV4Addr(intf string, preferredIP net.IP) (net.IP, error)

firstGlobalV4Addr returns the first IPv4 global IP of an interface, where the IPs are sorted in creation order (oldest to newest).

All secondary IPs, except the preferredIP, are filtered out.

Public IPs are preferred over private ones. When intf is defined only IPs belonging to that interface are considered.

If preferredIP is present in the IP list it is returned irrespective of the sort order. However, if preferredIP is a private IP, a public IP will be returned if it is assigned to the intf

Passing intf and preferredIP will only return preferredIP if it is in the IPs that belong to intf.

In all cases, if intf is not found all interfaces are considered.

If a intf-specific global address couldn't be found, we retry to find an address with reduced scope (site, custom) on that particular device.

If the latter fails as well, we retry on all interfaces beginning with universe scope again (and then falling back to reduced scope).

Deprecated addresses are only considered once none of the above yielded an address.

In case none of the above helped, we bail out with error.

func FirstGlobalV6Addr added in v1.20.0 

func FirstGlobalV6Addr(intf string, preferredIP net.IP) (net.IP, error)

firstGlobalV6Addr returns first IPv6 global IP of an interface, see firstGlobalV4Addr for more details.

func GetBootID added in v1.13.14 

func GetBootID(logger *slog.Logger) string

func GetCiliumEndpointNodeIP added in v0.15.7 

func GetCiliumEndpointNodeIP(localNode LocalNode) string

GetCiliumEndpointNodeIP is the node IP that will be referenced by CiliumEndpoints with endpoints running on this node.

func GetEndpointEncryptKeyIndex added in v1.14.7 

func GetEndpointEncryptKeyIndex(localNode LocalNode, wgEnabled, ipsecEnabled bool) uint8

GetEndpointEncryptKeyIndex returns the encryption key value for an endpoint owned by the given local node. With IPSec encryption, this is the ID of the currently loaded key. With WireGuard, this returns a non-zero static value. Note that the key index returned by this function is only valid for _endpoints_ of the local node. If you want to obtain the key index of the local node itself, access the `EncryptionKey` field via the LocalNodeStore.

func GetEndpointID added in v0.15.7 

func GetEndpointID() (uint64, bool)

GetEndpointID returns the ID of the host endpoint for this node. The boolean return value indicates whether the host endpoint ID has been set (true) or is still the uninitialized template value (false).

func GetExcludedIPs added in v0.15.7 

func GetExcludedIPs() []net.IP

GetExcludedIPs returns a list of IPs from netdevices that Cilium needs to exclude to operate

func NewNodeMetrics 

func NewNodeMetrics() *nodeMetrics

func NewNodeTable 

func NewNodeTable(db *statedb.DB) (statedb.RWTable[*Node], error)

func NewNodeTableAndLocalNodeStore 

func NewNodeTableAndLocalNodeStore(params LocalNodeStoreParams) (
	*LocalNodeStore, NodeGetter, statedb.Table[*Node], error,
)

NewNodeTableAndLocalNodeStore constructs LocalNodeStore and the node table. Ensures that the local node object is present in the table.

func SetEndpointID added in v0.15.7 

func SetEndpointID(id uint64)

SetEndpointID sets the ID of the host endpoint for this node.

func WaitForLocalNodeInit 

func WaitForLocalNodeInit(ctx context.Context, db *statedb.DB, nodes statedb.Table[*Node]) (statedb.ReadTxn, error)

WaitForLocalNodeInit waits until the local-node initializer has completed. The nodes table may have other pending initializers, so callers interested only in the local node need not wait for the whole table to initialize.

Types

type Addressing added in v1.20.0 

type Addressing interface {
	IPv6() AddressingFamily
	IPv4() AddressingFamily
}

Addressing implements addressing of a node

type AddressingFamily added in v1.20.0 

type AddressingFamily interface {
	// Router is the address that will act as the router on each node where
	// an agent is running on. Endpoints have a default route that points
	// to this address.
	Router() netip.Addr

	// PrimaryExternal is the primary external address of the node. Nodes
	// must be able to reach each other via this address.
	PrimaryExternal() netip.Addr

	// AllocationCIDR is the CIDR used for IP allocation of all endpoints
	// on the node
	AllocationCIDR() netip.Prefix
}

AddressingFamily is the node addressing information for a particular address family

type ClusterSizeDependantIntervalFunc 

type ClusterSizeDependantIntervalFunc func(time.Duration) time.Duration

ClusterSizeDependantIntervalFunc returns a time.Duration that is dependent on the cluster size, i.e. the number of nodes that have been discovered. This can be used to control sync intervals of shared or centralized resources to avoid overloading these resources as the cluster grows.

Example sync interval with baseInterval = 1 * time.Minute

nodes | sync interval ------+----------------- 1 | 41.588830833s 2 | 1m05.916737320s 4 | 1m36.566274746s 8 | 2m11.833474640s 16 | 2m49.992800643s 32 | 3m29.790453687s 64 | 4m10.463236193s 128 | 4m51.588744261s 256 | 5m32.944565093s 512 | 6m14.416550710s 1024 | 6m55.946873494s 2048 | 7m37.506428894s 4096 | 8m19.080616652s 8192 | 9m00.662124608s 16384 | 9m42.247293667s

func NewClusterSizeDependantInterval 

func NewClusterSizeDependantInterval(
	db *statedb.DB,
	nodes statedb.Table[*Node],
) ClusterSizeDependantIntervalFunc

NewClusterSizeDependantInterval returns a function that computes intervals from the current size of the node table.

type IDHandler added in v1.20.0 

type IDHandler interface {
	// GetNodeIP returns the string node IP that was previously registered as the given node ID.
	GetNodeIP(uint16) string

	// GetNodeID gets the node ID for the given node IP. If none is found, exists is false.
	GetNodeID(nodeIP netip.Addr) (nodeID uint16, exists bool)

	// DumpNodeIDs returns all node IDs and their associated IP addresses.
	DumpNodeIDs() []*models.NodeID

	// RestoreNodeIDs restores node IDs and their associated IP addresses from the
	// BPF map and into the node handler in-memory copy.
	RestoreNodeIDs()
}

type LocalNode added in v0.15.7 

type LocalNode = Node

LocalNode is an alias for the Node type to mark that we expect this to be the local node.

func (*LocalNode) RemoteSNATDstAddrExclusionCIDRv4 added in v1.20.0 

func (n *LocalNode) RemoteSNATDstAddrExclusionCIDRv4() netip.Prefix

RemoteSNATDstAddrExclusionCIDRv4 returns a CIDR for SNAT exclusion. Any packet sent from a local endpoint to an IP address belonging to the CIDR should not be SNAT'd. The zero Prefix is returned if no CIDR is known.

func (*LocalNode) RemoteSNATDstAddrExclusionCIDRv6 added in v1.20.0 

func (n *LocalNode) RemoteSNATDstAddrExclusionCIDRv6() netip.Prefix

RemoteSNATDstAddrExclusionCIDRv6 returns a IPv6 CIDR for SNAT exclusion. Any packet sent from a local endpoint to an IP address belonging to the CIDR should not be SNAT'd. The zero Prefix is returned if no CIDR is known.

func (*LocalNode) SetPodSubnets 

func (n *LocalNode) SetPodSubnets(prefixes []netip.Prefix)

SetPodSubnets records the subnets pod IPs are allocated from, coalescing them into the minimal equivalent set and splitting them by address family. It replaces any previously recorded value, so repeated calls with the same input are idempotent and dedup against the previous revision in statedb.

type LocalNodeInfo added in v1.19.0 

type LocalNodeInfo struct {
	// OptOutNodeEncryption will make the local node opt-out of node-to-node
	// encryption
	OptOutNodeEncryption bool
	// Unique identifier of the Kubernetes node, used to construct the
	// corresponding owner reference.
	UID k8stypes.UID
	// ID of the node assigned by the cloud provider.
	ProviderID string
	// v4 CIDR in which pod IPs are routable
	// +deepequal-gen=false
	IPv4NativeRoutingCIDR netip.Prefix
	// v6 CIDR in which pod IPs are routable
	// +deepequal-gen=false
	IPv6NativeRoutingCIDR netip.Prefix
	// ServiceLoopbackIPv4 is the source address used for SNAT when a Pod talks to
	// itself through a Service.
	// +deepequal-gen=false
	ServiceLoopbackIPv4 netip.Addr
	// ServiceLoopbackIPv6 is the source address used for SNAT when a Pod talks to
	// itself through a Service.
	// +deepequal-gen=false
	ServiceLoopbackIPv6 netip.Addr
	// IPv4PodSubnets are the v4 subnets pod IPs are allocated from, for IPAM
	// modes where pods live in cloud provider subnets rather than in a node
	// PodCIDR. Empty for every other mode.
	IPv4PodSubnets []ip.Prefix
	// IPv6PodSubnets are the v6 subnets pod IPs are allocated from, for IPAM
	// modes where pods live in cloud provider subnets rather than in a node
	// PodCIDR. Empty for every other mode.
	IPv6PodSubnets []ip.Prefix
	// IsBeingDeleted indicates that the local node is being deleted.
	IsBeingDeleted bool
	// UnderlayProtocol is the IP family of our underlay.
	UnderlayProtocol tunnel.UnderlayProtocol
}

LocalNodeInfo is the additional information about the local node that is only used internally.

DeepEqual is generated, except for the netip.Addr and netip.Prefix fields: deepequal-gen cannot synthesize a comparison for an external type with unexported pointer fields, so those carry +deepequal-gen=false and are compared by the hand-written prologue in DeepEqual below.

+k8s:deepcopy-gen=false +deepequal-gen=true +deepequal-gen:private-method=true

func (*LocalNodeInfo) DeepCopy added in v1.19.0 

func (in *LocalNodeInfo) DeepCopy() *LocalNodeInfo

DeepCopy creates a deep copy of the LocalNodeInfo.

func (*LocalNodeInfo) DeepCopyInto added in v1.19.0 

func (in *LocalNodeInfo) DeepCopyInto(out *LocalNodeInfo)

DeepCopyInto copies the receiver into out. in must be non-nil.

func (*LocalNodeInfo) DeepEqual added in v1.19.0 

func (in *LocalNodeInfo) DeepEqual(other *LocalNodeInfo) bool

DeepEqual compares two LocalNodeInfo structs for equality. in must be non-nil.

type LocalNodeStore added in v0.15.7 

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

LocalNodeStore is the canonical owner for the local node object and provides a reactive API for observing and updating the state.

func NewTestLocalNodeStore added in v0.15.7 

func NewTestLocalNodeStore(mockNode LocalNode) *LocalNodeStore

func (*LocalNodeStore) Get added in v0.15.7 

func (s *LocalNodeStore) Get(ctx context.Context) (LocalNode, error)

Get retrieves the current local node. Use Get() only for inspecting the state, e.g. in API handlers. Do not assume the value does not change over time. Blocks until the store has been initialized.

func (*LocalNodeStore) Observe added in v1.13.0 

func (s *LocalNodeStore) Observe(ctx context.Context, next func(LocalNode), complete func(error))

Observe changes to the local node state.

func (*LocalNodeStore) Update added in v0.15.7 

func (s *LocalNodeStore) Update(update func(*LocalNode))

Update modifies the local node with a mutator.

func (*LocalNodeStore) WaitForNodeInformation added in v1.20.0 

func (s *LocalNodeStore) WaitForNodeInformation(ctx context.Context) error

type LocalNodeStoreParams added in v0.15.7 

type LocalNodeStoreParams struct {
	cell.In

	Logger      *slog.Logger
	Lifecycle   cell.Lifecycle
	Sync        LocalNodeSynchronizer
	DB          *statedb.DB
	Jobs        job.Group
	ClusterInfo cmtypes.ClusterInfo
	Nodes       statedb.RWTable[*LocalNode]
	NodeWriter  *Writer
}

LocalNodeStoreParams are the inputs needed for constructing LocalNodeStore.

type LocalNodeSynchronizer added in v1.15.0 

type LocalNodeSynchronizer interface {
	InitLocalNode(context.Context, *LocalNode) error
	SyncLocalNode(context.Context, *LocalNodeStore)
	WaitForNodeInformation(context.Context, *LocalNodeStore) error
}

LocalNodeSynchronizer specifies how to build, and keep synchronized the local node object.

func NewNopLocalNodeSynchronizer added in v1.19.0 

func NewNopLocalNodeSynchronizer() LocalNodeSynchronizer

type Node 

type Node struct {
	types.Node

	// Local is non-nil if this is the local node. This carries additional
	// information about the local node that is not shared outside.
	Local *LocalNodeInfo

	// Statuses for reconcilers acting on this object.
	// DeepEqual is reserved for comparing the desired node data.
	// +deepequal-gen=false
	Statuses reconciler.StatusSet
	// contains filtered or unexported fields
}

Node is a Cilium node. It is the local node if Node.Local is non-nil.

+deepequal-gen=true

func (*Node) DeepCopy added in v1.5.0 

func (n *Node) DeepCopy() *Node

DeepCopy returns a deep copy of the node.

func (*Node) DeepEqual 

func (in *Node) DeepEqual(other *Node) bool

DeepEqual is an autogenerated deepequal function, deeply comparing the receiver with other. in must be non-nil.

func (*Node) TableHeader 

func (n *Node) TableHeader() []string

TableHeader implements statedb.TableWritable.

func (*Node) TableRow 

func (n *Node) TableRow() []string

TableRow implements statedb.TableWritable.

type NodeGetter added in v1.20.0 

type NodeGetter interface {
	Get(ctx context.Context) (LocalNode, error)
}

NodeGetter describes the behavior of a node store used for retrieving the local node.

type NodeReconciler 

type NodeReconciler string

NodeReconciler identifies a reconciler operating on the node table. 

const (
	// LinuxNodeReconciler realizes nodes in the Linux datapath.
	LinuxNodeReconciler NodeReconciler = "linux"
	// WireGuardNodeReconciler realizes nodes in the WireGuard datapath.
	WireGuardNodeReconciler NodeReconciler = "wireguard"
)

func (NodeReconciler) String 

func (r NodeReconciler) String() string

type PrefixClusterMutatorFn 

type PrefixClusterMutatorFn = func(*nodeTypes.Node) []cmtypes.PrefixClusterOpts

PrefixClusterMutatorFn derives cluster-aware addressing options from a serialized node.

type UpdatePolicy 

type UpdatePolicy interface {
	// The publish result only controls remote nodes; UpsertLocal always writes
	// the local row. The mutator is the writer's prefix qualification hook.
	Upsert(node *nodeTypes.Node, mutator PrefixClusterMutatorFn) (publish bool)
	// Delete reports whether the source owns the cached node and its published
	// row may be removed, even if that row still has an older source.
	Delete(src source.Source, identity nodeTypes.Identity, mutator PrefixClusterMutatorFn) (remove bool)
}

UpdatePolicy preserves the legacy node update ordering. It retains ownership of conflict resolution and any state it needs.

type Writer 

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

Writer provides source-aware write access to the node table.

func NewWriter 

func NewWriter(log *slog.Logger, db *statedb.DB, nodes statedb.RWTable[*Node]) *Writer

NewWriter constructs a node table writer.

func (*Writer) Delete 

func (w *Writer) Delete(txn statedb.WriteTxn, src source.Source, identity nodeTypes.Identity) bool

Delete removes a remote node if the policy accepts the deletion, or, without a policy, if src still owns the table row. It reports whether the table changed.

func (*Writer) Refresh 

func (w *Writer) Refresh(ctx context.Context, reconcilers ...NodeReconciler) error

Refresh marks the selected reconcilers pending for every node and waits for them to attempt processing the nodes (status is either Done or Error). If no reconcilers are specified, all registered reconcilers are refreshed. The error is [ctx.Err()] if context is cancelled.

func (*Writer) RegisterInitializer 

func (w *Writer) RegisterInitializer(txn statedb.WriteTxn, name string) func(statedb.WriteTxn)

RegisterInitializer registers a producer that must finish its initial node listing before the table is considered initialized.

func (*Writer) RegisterReconciler 

func (w *Writer) RegisterReconciler(name NodeReconciler)

RegisterReconciler adds the named reconciler to the list of required reconcilers and marks existing nodes pending for it. This list is passed to reconciler.StatusSet.Pending when nodes are created or updated. Panics if the reconciler has already been registered.

func (*Writer) SetPrefixClusterMutatorFn 

func (w *Writer) SetPrefixClusterMutatorFn(mutator PrefixClusterMutatorFn)

SetPrefixClusterMutatorFn installs the cluster-address qualification hook. This hook must be set during Hive invoke time.

func (*Writer) SetUpdatePolicy 

func (w *Writer) SetUpdatePolicy(p UpdatePolicy)

func (*Writer) Table 

func (w *Writer) Table() statedb.Table[*Node]

Table returns read-only access to the node table.

func (*Writer) UnregisterReconciler 

func (w *Writer) UnregisterReconciler(name NodeReconciler)

UnregisterReconciler removes the reconciler from the list of required reconcilers and removes its status from every node. The reconciler must be stopped before it is unregistered so it cannot write its status back.

func (*Writer) Upsert 

func (w *Writer) Upsert(txn statedb.WriteTxn, n *nodeTypes.Node) bool

Upsert a remote node into the node table.

func (*Writer) UpsertLocal 

func (w *Writer) UpsertLocal(txn statedb.WriteTxn, n *LocalNode) error

UpsertLocal writes the local node, including its local-only information, and runs the update policy for its side effects once the local node is initialized. The local node is always written independently of whether the policy would publish a remote node.

func (*Writer) WaitUntilReconciled 

func (w *Writer) WaitUntilReconciled(
	ctx context.Context,
	txn statedb.ReadTxn,
	requireDone bool,
) error

WaitUntilReconciled waits until all nodes present in txn have been reconciled. When requireDone is false, both done and error statuses are considered finished. When it is true, every status must be done.

Source Files

View all Source files

Directories

Path Synopsis

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.