Documentation
¶
Index ¶
- Constants
- Variables
- func HeldBits(ctx context.Context, c client.Reader, prefix, namespace string) ([]uint, error)
- func InitBitmap(size, offset uint) (string, uint)
- func LeaseReleased(ctx context.Context, c client.Reader, prefix, namespace string, size uint, ...) (bool, error)
- func ReleaseOwnedIndex(ctx context.Context, c client.Client, prefix, namespace string, size uint, ...) error
- func ReturnMatured(ctx context.Context, c client.Client, prefix, namespace string, size uint, ...) (int, error)
- func ReturnMaturedUnless(ctx context.Context, c client.Client, prefix, namespace string, size uint, ...) (int, error)
- func SetBitsForTest(encoded string, free uint, bits ...uint) (string, uint, error)
- func ValidateLease(ctx context.Context, c client.Reader, prefix, namespace string, size uint, ...) error
- func ValidateOrReleased(ctx context.Context, c client.Reader, prefix, namespace string, size uint, ...) error
- type Allocator
- type ForwardAllocator
- type Lease
- func AllocateOwnedIndex(ctx context.Context, c client.Client, prefix, namespace string, size uint, ...) (*Lease, error)
- func FindOwnerLease(ctx context.Context, c client.Reader, prefix, namespace, uid string) (*Lease, error)
- func PinExistingIndex(ctx context.Context, c client.Client, prefix, namespace string, ...) (*Lease, error)
- type Retirement
- type SlotState
Constants ¶
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" )
const CursorAnnotation = "allocation.cybericebox.com/cursor"
CursorAnnotation on a Pool remembers where a rotating allocator handed out last.
const Recent = 2 * time.Minute
Recent is how long an index handed out is safe from being taken back.
Variables ¶
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".
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
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 ¶
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 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
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 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 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
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 FindOwnerLease ¶ added in v1.1.0
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
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.