pool

package
v1.8.0 Latest Latest
Warning

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

Go to latest
Published: Nov 1, 2026 License: Apache-2.0 Imports: 18 Imported by: 0

Documentation

Index

Constants

View Source
const (
	PoolStateLabel  = "allocation.cybericebox.com/state"
	LatestPoolLabel = "allocation.cybericebox.com/latest"
	PoolGroupLabel  = "allocation.cybericebox.com/group"

	PoolStateEmpty   = "empty"
	PoolStatePartial = "partial"
	PoolStateFull    = "full"

	// PoolTypeLabel carries semantic pool type (vni, vpn-clients, lab-subnets).
	PoolTypeLabel = "pool.cybericebox.com/type"

	// Semantic pool type values.
	PoolTypeVPNClients = "vpn-clients"
	PoolTypeLabSubnets = "lab-subnets"
	PoolTypeVNI        = "vni"
)
View Source
const CursorAnnotation = "allocation.cybericebox.com/cursor"

CursorAnnotation on a Pool remembers where a rotating allocator handed out last.

View Source
const Recent = 2 * time.Minute

Recent is how long an index handed out is safe from being taken back.

Variables

View Source
var (
	ErrLeaseAbsent  = stderrors.New("pool reservation is absent or identity unavailable")
	ErrLeaseRetired = stderrors.New("pool slot is retired and waits out its quarantine")
)

ErrLeaseAbsent and ErrLeaseRetired are what PinExistingIndex says of a slot that is no longer held: its bit is clear (returned to the pool after the quarantine) or it is retired and waits out its quarantine. For an owner that is being deleted they mean "released".

View Source
var ErrLeaseNotHeld = stderrors.New("current pool lease owner/generation changed")

ErrLeaseNotHeld is what ValidateLease says of a lease the pool does not hold as recorded: no record, another owner or generation, another pool, a clear bit. Other errors (the pool cannot be read, a bad extent) are failures of the question, not its answer.

Functions

func HeldBits added in v1.8.0

func HeldBits(ctx context.Context, c client.Reader, prefix, namespace string) ([]uint, error)

HeldBits lists, per pool, the set bits that have neither a lease nor a retirement: the slots someone took without a lease (a legacy reservation) and the ones whose owner forgot them. Index = bit + the pool's offset.

func InitBitmap

func InitBitmap(size, offset uint) (string, uint)

InitBitmap initialises a pool's bitmap and returns (encodedBitmap, freeCount). Bit 0 is reserved when offset == 0 to avoid assigning the network-address index.

func LeaseReleased added in v1.8.0

func LeaseReleased(ctx context.Context, c client.Reader, prefix, namespace string, size uint, lease Lease) (bool, error)

LeaseReleased says the exact lease has been retired and nothing holds its slot: the slot has no lease record and its retirement record names this very owner and generation (it waits out its quarantine, and the sweep does not return it while a node still owes the acknowledgement). Anything else is not "released": a slot back in the pool (the proof of whose lease it was is gone, and it may be someone else's now), a slot with a lease record (this lease, or another owner's after a reuse), a retirement of another owner or generation, a legacy hold. The pool is read by the caller; for a decision that drops flows it must be an uncached reader.

func ReleaseOwnedIndex added in v1.1.0

func ReleaseOwnedIndex(ctx context.Context, c client.Client, prefix, namespace string, size uint, lease Lease) error

func ReturnMatured added in v1.8.0

func ReturnMatured(ctx context.Context, c client.Client, prefix, namespace string, size uint, quarantine time.Duration, now time.Time) (int, error)

ReturnMatured gives back, in one update per pool, every retired slot whose quarantine has passed, and returns how many.

func ReturnMaturedUnless added in v1.8.0

func ReturnMaturedUnless(ctx context.Context, c client.Client, prefix, namespace string, size uint, quarantine time.Duration, now time.Time, hold func(index uint, ownerUID string, generation int64) bool) (int, error)

ReturnMaturedUnless is ReturnMatured except for the slots hold names: hold(index, ownerUID, generation) says the retired lease still has an obligation (a node has not yet acknowledged that it dropped the flows of the VNI), so the slot stays retired and is not given out until the obligation is gone. A slot is never handed to another owner while a node may still carry the old owner's flows.

func SetBitsForTest added in v1.8.0

func SetBitsForTest(encoded string, free uint, bits ...uint) (string, uint, error)

SetBitsForTest sets bits of an encoded bitmap (and lowers free for each one that was clear); it is for tests that seed a pool.

func ValidateLease added in v1.1.0

func ValidateLease(ctx context.Context, c client.Reader, prefix, namespace string, size uint, lease Lease) error

func ValidateOrReleased added in v1.8.0

func ValidateOrReleased(ctx context.Context, c client.Reader, prefix, namespace string, size uint, lease Lease) error

ValidateOrReleased is the question a node asks before it drops the flows of a VNI for a lease: is the number still this owner's? Yes when the lease is held as recorded, or when it has been retired with exactly this owner and generation (LeaseReleased). A slot that was given back and issued to someone else, a retirement of another lease and a pool that cannot be read are errors, never an answer. Ask it with an uncached reader, before the flows go and again after.

Types

type Allocator

type Allocator interface {
	AllocateIndex(ctx context.Context) (uint, error)
	ReleaseIndex(ctx context.Context, index uint) error
}

func NewAllocator

func NewAllocator(c client.Client, poolNamePrefix, namespace string, poolSize uint) Allocator

func NewRotatingAllocator

func NewRotatingAllocator(c client.Client, poolNamePrefix, namespace string, poolSize uint) Allocator

NewRotatingAllocator is NewAllocator with indexes that are not reused until the pool has been walked (see allocator.rotate): the VNIs of the lab networks, where the same number meeting a new lab at once could inherit stale flows on a node.

type ForwardAllocator added in v1.8.0

type ForwardAllocator struct {
	Client client.Client
	// Prefix and Namespace name the pool "<Prefix>-0" in the group's namespace; Size is the number of values.
	Prefix, Namespace string
	Size              uint
	// InUse returns the indexes something refers to (read straight from the API server).
	InUse func(ctx context.Context) (map[uint]bool, error)
	// Now is the clock; nil means time.Now.
	Now func() time.Time
}

A ForwardAllocator gives out the indexes of a small pool that lives and dies with its group (the subnets of the labs and the tunnel addresses of the clients of a group: 254 values in the group's namespace) only forward: it never takes an index back. A deleted lab or client returns nothing, the pool goes with the group, and every allocation is ONE write of the pool (the bitmap, the free count and the cursor in the same status update).

Insurance for a group that outlives its indexes: when fewer than two indexes are free, once, the indexes that nothing refers to any more are taken back (InUse tells which are referred to, read from the API server) and the allocation goes on round the pool. That code does not run before the pool has come to its end. It never takes back an index handed out in the last Recent (the object that records it may not be written yet), and not in the first Recent of the process.

func (*ForwardAllocator) AllocateIndex added in v1.8.0

func (a *ForwardAllocator) AllocateIndex(ctx context.Context) (uint, error)

AllocateIndex hands out the next index with one write of the pool.

type Lease added in v1.1.0

type Lease struct {
	Index             uint
	PoolUID, OwnerUID string
	Generation        int64
}

Lease is an immutable reservation epoch. Its UID survives caller/process restart; PoolUID also fences pool deletion/recreation with a reset counter.

func AllocateOwnedIndex added in v1.1.0

func AllocateOwnedIndex(ctx context.Context, c client.Client, prefix, namespace string, size uint, uid string) (*Lease, error)

func FindOwnerLease added in v1.1.0

func FindOwnerLease(ctx context.Context, c client.Reader, prefix, namespace, uid string) (*Lease, error)

func PinExistingIndex added in v1.1.0

func PinExistingIndex(ctx context.Context, c client.Client, prefix, namespace string, size, index uint, uid string) (*Lease, error)

PinExistingIndex upgrades a currently held legacy reservation. It never binds a clear bit or a differently owned lease; all subsequent releases are fenced.

type Retirement added in v1.8.0

type Retirement struct {
	Index uint
	Lease *Lease
}

Retirement is one slot to retire. Lease is nil for a slot that never had a lease (a legacy reservation).

func Retire added in v1.8.0

func Retire(ctx context.Context, c client.Client, prefix, namespace string, size uint, rs []Retirement, now time.Time) (failed []Retirement, err error)

Retire marks the slots retired at `now`, one update per pool. A lease that is no longer the slot's (released before, taken again by a new owner) is skipped: it is an old acknowledgement. It returns the retirements it could not make (a failed update of their pool), to be tried again.

type SlotState added in v1.8.0

type SlotState int

SlotState is what the pool says of an index, whoever the owner is.

const (
	// SlotHeld: a lease record, or a set bit with no record (a legacy hold of an unknown owner). Someone may own the number.
	SlotHeld SlotState = iota
	// SlotRetired: its owner let it go and it waits out its quarantine; nobody owns it, and it is not yet issuable.
	SlotRetired
	// SlotFree: no lease, no retirement, a clear bit: back in the pool, issuable to anyone at any moment.
	SlotFree
)

func SlotStateOf added in v1.8.0

func SlotStateOf(ctx context.Context, c client.Reader, prefix, namespace string, size, index uint) (SlotState, error)

SlotStateOf reads the state of the index. The pool is read with the caller's reader (an uncached one for a decision that drops flows). An error is the failure of the question (the pool cannot be read, the index is outside every pool), never an answer.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL