nodemanager

type AllocationAction struct {
	// InterfaceID is set to the identifier describing the interface on
	// which the IPs must be allocated. This is optional, an IPAM
	// implementation can leave this empty to indicate that no interface
	// context is needed or a new interface must be created.
	InterfaceID string

	// Interface is the interface to allocate IPs on
	Interface ipamTypes.Interface

	// PoolID is the IPAM pool identifier to allocate the IPs from. This
	// can correspond to a subnet ID or it can also be left blank or set to a
	// value such as "global" to indicate a single address pool.
	PoolID ipamTypes.PoolID

	// EmptyInterfaceSlots is the number of empty interface slots available
	// for interfaces to be attached.
	EmptyInterfaceSlots int

	// IPv4 represents IPv4-specific allocation actions.
	IPv4 IPAllocationAction

	// IPv6 represents IPv6-specific allocation actions.
	IPv6 IPAllocationAction
}

type AllocationImplementation interface {
	// CreateNode is called when the IPAM layer has learned about a new
	// node which requires IPAM services. This function must return a
	// NodeOperations implementation which will render IPAM services to the
	// node context provided.
	CreateNode(obj *v2.CiliumNode, node *Node) NodeOperations

	// GetPoolQuota is called to retrieve the remaining IP addresses in all
	// IP pools known to the IPAM implementation.
	GetPoolQuota() ipamTypes.PoolQuotaMap

	// Resync is called periodically to give the IPAM implementation a
	// chance to resync its own state with external APIs or systems. It is
	// also called when the IPAM layer detects that state got out of sync.
	Resync(ctx context.Context) (time.Time, error)

	// InstanceSync is called to sync the state of the specified instance with
	// external APIs or systems.
	InstanceSync(ctx context.Context, instanceID string) (time.Time, error)

	// HasInstance returns whether the instance is in instances
	HasInstance(instanceID string) bool

	// DeleteInstance deletes the instance from instances
	DeleteInstance(instanceID string)
}

type IPAllocationAction struct {
	// AvailableForAllocation is the number of IPs available for allocation.
	// If InterfaceID is set, then this number corresponds to the number of
	// IPs available for allocation on that interface. This number may be
	// lower than the number of IPs required to resolve the deficit.
	AvailableForAllocation int

	// MaxIPsToAllocate is set by the core IPAM layer before
	// NodeOperations.AllocateIPs() is called and defines the maximum
	// number of IPs to allocate in order to stay within the boundaries as
	// defined by NodeOperations.{ MinAllocate() | PreAllocate() |
	// getMaxAboveWatermark() }.
	MaxIPsToAllocate int

	// MaxPrefixesToAllocate is set by the core IPAM layer before
	// NodeOperations.AllocateIPs() is called and defines the maximum
	// number of prefixes to allocate.
	MaxPrefixesToAllocate int

	// InterfaceCandidates is the number of attached interfaces with IPs
	// available for allocation.
	InterfaceCandidates int
}

type IPStatistics struct {
	// UsedIPs is the number of IPs currently in use
	UsedIPs int

	// AvailableIPs is the number of IPs currently allocated and available for assignment.
	AvailableIPs int

	// AvailablePrefixes is the number of IP prefixes currently allocated and
	// available for assignment. (Used for IPv6 prefixes)
	// Since IPv6 prefixes are very large it does not make sense to keep track of
	// the effective number of IPv6 addresses available for assignment.
	AvailablePrefixes int

	// Capacity is the max inferred IPAM IP capacity for the node.
	// In theory, this provides an upper limit on the number of Cilium IPs that
	// this Node can support.
	Capacity int

	// NeededIPs is the number of IPs needed to reach the PreAllocate
	// watermark
	NeededIPs int

	// NeededPrefixes is the number of prefixes needed.
	//
	// Used for IPv6 prefixes
	NeededPrefixes int

	// ExcessIPs is the number of free IPs exceeding MaxAboveWatermark
	ExcessIPs int

	// RemainingInterfaces is the number of interfaces that can either be
	// allocated or have not yet exhausted the instance specific quota of
	// addresses
	RemainingInterfaces int

	// InterfaceCandidates is the number of attached interfaces with IPs
	// available for allocation.
	InterfaceCandidates int

	// AssignedStaticIP is the static IP address assigned to the node (ex: public Elastic IP address in AWS)
	AssignedStaticIP string
}

type MetricsAPI interface {
	MetricsNodeAPI

	AllocationAttempt(typ, status, subnetID string, observe float64)
	ReleaseAttempt(typ, status, subnetID string, observe float64)
	IncInterfaceAllocation(subnetID string)
	AddIPAllocation(subnetID string, allocated int64)
	AddIPRelease(subnetID string, released int64)
	SetInterfaceCandidates(interfaceCandidates int)
	SetEmptyInterfaceSlots(emptyInterfaceSlots int)
	SetAvailableIPsPerSubnet(subnetID string, availabilityZone string, available int)
	SetNodes(category string, nodes int)
	IncResyncCount()
	ObserveBackgroundSync(status string, duration time.Duration)
	PoolMaintainerTrigger() trigger.MetricsObserver
	K8sSyncTrigger() trigger.MetricsObserver
	ResyncTrigger() trigger.MetricsObserver
}

type MetricsNodeAPI interface {
	SetIPAvailable(node string, cap int)
	SetIPUsed(node string, used int)
	SetIPNeeded(node string, needed int)
	DeleteNode(node string)
}

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

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

type NodeOperations interface {
	// UpdatedNode is called when an update to the CiliumNode is received.
	UpdatedNode(obj *v2.CiliumNode)

	// PopulateStatusFields is called to give the implementation a chance
	// to populate any implementation specific fields in CiliumNode.Status.
	PopulateStatusFields(resource *v2.CiliumNode)

	// CreateInterface is called to create a new interface. This is only
	// done if PrepareIPAllocation indicates that no more IPs are available
	// (AllocationAction.AvailableForAllocation == 0) for allocation but
	// interfaces are available for creation
	// (AllocationAction.EmptyInterfaceSlots > 0). This function must
	// create the interface *and* allocate up to
	// AllocationAction.MaxIPsToAllocate.
	CreateInterface(ctx context.Context, allocation *AllocationAction, scopedLog *slog.Logger) (int, string, error)

	// ResyncInterfacesAndIPs is called to synchronize the latest list of
	// interfaces and IPs associated with the node. This function is called
	// sparingly as this information is kept in sync based on the success
	// of the functions AllocateIPs(), ReleaseIPs() and CreateInterface().
	// It returns all available ip in node and remaining available interfaces
	// that can either be allocated or have not yet exhausted the instance specific quota of addresses
	// and error occurred during execution.
	ResyncInterfacesAndIPs(ctx context.Context, scopedLog *slog.Logger) (ipamTypes.AllocationMap, ipamStats.InterfaceStats, error)

	// PrepareIPAllocation is called to calculate the number of IPs that
	// can be allocated on the node and whether a new network interface
	// must be attached to the node.
	PrepareIPAllocation(scopedLog *slog.Logger) (*AllocationAction, error)

	// AllocateIPs is called after invoking PrepareIPAllocation and needs
	// to perform the actual allocation.
	AllocateIPs(ctx context.Context, allocation *AllocationAction) error

	AllocateStaticIP(ctx context.Context, staticIPTags ipamTypes.Tags) (string, error)

	// PrepareIPRelease is called to calculate whether any IP excess needs
	// to be resolved. It behaves identical to PrepareIPAllocation but
	// indicates a need to release IPs.
	PrepareIPRelease(excessIPs int, scopedLog *slog.Logger) *ReleaseAction

	// ReleaseIPPrefixes is called after invoking PrepareIPRelease and needs to
	// perform the release of IPPrefixes.
	ReleaseIPPrefixes(ctx context.Context, release *ReleaseAction) error

	// ReleaseIPs is called after invoking PrepareIPRelease and needs to
	// perform the release of IPs.
	ReleaseIPs(ctx context.Context, release *ReleaseAction) error

	// GetMaximumAllocatableIPv4 returns the maximum amount of IPv4 addresses
	// that can be allocated to the instance
	GetMaximumAllocatableIPv4() int

	// GetMinimumAllocatableIPv4 returns the minimum amount of IPv4 addresses that
	// must be allocated to the instance.
	GetMinimumAllocatableIPv4() int

	// IsPrefixDelegated helps identify if a node supports prefix delegation
	IsPrefixDelegated() bool

	// GetAttachedCIDRs returns the CIDRs currently attached to the node's
	// network interfaces, as observed by the cloud-specific implementation.
	// Used by multi-pool mode to reconcile the tracking map against ground
	// truth (drop CIDRs no longer attached, seed releases that survived an
	// operator restart). Implementations that do not support multi-pool may
	// return nil.
	GetAttachedCIDRs() []netip.Prefix

	// PrepareCIDRRelease maps released CIDRs back to their source
	// network interfaces and returns release actions grouped by interface.
	// Used by multi-pool mode where the agent removes CIDRs from
	// Allocated instead of participating in the IP release handshake.
	PrepareCIDRRelease(releasedCIDRs []netip.Prefix) []*ReleaseAction

	// ReleaseCIDRs performs the release of the CIDRs listed in
	// release.CIDRsToRelease. The cloud-specific implementation is responsible
	// for appropriately handling single-IP CIDRs and larger ones by dispatching to
	// the appropriate underlying APIs. Returns the subset of CIDRs that were
	// successfully released so the caller can prune its tracking state even on
	// partial failure.
	ReleaseCIDRs(ctx context.Context, release *ReleaseAction) (released []netip.Prefix, err error)
}

type PoolMaintainer interface {
	Trigger()
	Shutdown()
}

type ReleaseAction struct {
	// InterfaceID is set to the identifier describing the interface on
	// which the IPs must be released. This is optional, an IPAM
	// implementation can leave this empty to indicate that no interface
	// context is needed.
	InterfaceID string

	// PoolID is the IPAM pool identifier to release the IPs from. This can
	// correspond to a subnet ID or it can also be left blank or set to a
	// value such as "global" to indicate a single address pool.
	PoolID ipamTypes.PoolID

	// IPsToRelease is the list of IPs to release.
	//
	// Used by the CRD-mode release path. The multi-pool release path uses
	// CIDRsToRelease instead.
	IPsToRelease []string

	// IPPrefixesToRelease is the list of prefixes to release.
	//
	// Used by the CRD-mode release path. The multi-pool release path uses
	// CIDRsToRelease instead.
	IPPrefixesToRelease []string

	// CIDRsToRelease is the list of CIDRs to release. Single-IP entries
	// (e.g. 10.0.0.5/32 for IPv4, 2001:db8::1/128 for IPv6) are detected via
	// netip.Prefix.IsSingleIP() by the cloud-specific implementation, which
	// dispatches to the appropriate underlying API (e.g.
	// UnassignPrivateIpAddresses vs UnassignENIPrefixes on AWS). Used by the
	// multi-pool release path.
	CIDRsToRelease []netip.Prefix
}

type Statistics struct {
	// IPv4 represents IPv4-specific statistics.
	IPv4 IPStatistics

	// IPv6 represents IPv6-specific statistics.
	IPv6 IPStatistics

	// EmptyInterfaceSlots is the number of empty interface slots available
	// for interfaces to be attached.
	EmptyInterfaceSlots int
}