placement

package
v0.6.0 Latest Latest
Warning

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

 Go to latest Published: Oct 17, 2026 License: Apache-2.0 Imports: 5 Imported by: 0

Documentation

Overview

Package placement is the multi-node scheduler: label selectors, a fit check against node CPU, memory and disk headroom, then a spread that prefers the most headroom. No bin-packing and no affinity rules, by design.

Index

Constants

View Source 
const (
	DimCPU    = "cpu"
	DimMemory = "memory"
	DimDisk   = "disk"
)

Dimension names in Evaluation.

Variables

View Source 
var ErrNoEligibleNode = errors.New("placement: no eligible node")

ErrNoEligibleNode is returned when no candidate passes every filter.

Functions

func Check 

func Check(c Candidate, req Request) error

Check validates an explicit target against req, the manual-assignment path.

func Filter 

func Filter(c Candidate, req Request) string

Filter returns why c may not take req, or "" when it may.

func FormatBytes 

func FormatBytes(b int64) string

FormatBytes renders bytes with a binary unit.

func FormatCPU 

func FormatCPU(milli int64) string

FormatCPU renders millicores as cores.

func ParseLabels 

func ParseLabels(pairs []string) (map[string]string, error)

ParseLabels turns ["k=v", ...] into a validated map.

func ValidateLabels 

func ValidateLabels(labels map[string]string) error

ValidateLabels checks keys and values are short, plain identifiers.

Types

type Amount 

type Amount struct {
	Value int64 `json:"value"`
	Known bool  `json:"known"`
}

Amount is a measured quantity. Known is false when the node never reported it: unknown is not zero (nothing fits) and not infinite (everything fits), it is "cannot be verified".

func Measured 

func Measured(v int64) Amount

Measured returns a known Amount.

type Candidate 

type Candidate struct {
	ID          string
	Name        string
	Labels      map[string]string
	Schedulable bool
	Online      bool
	// Load is how many apps and databases already run there.
	Load int
	// Capacity is what the node reported; Requested is what workloads
	// already placed on it asked for.
	Capacity  Capacity
	Requested Resources
}

Candidate is one node as the scheduler sees it.

type Capacity 

type Capacity struct {
	CPUMilli       Amount `json:"cpu_milli"`
	MemoryBytes    Amount `json:"memory_bytes"`
	DiskTotalBytes Amount `json:"disk_total_bytes"`
	DiskFreeBytes  Amount `json:"disk_free_bytes"`
}

Capacity is what a node reports about itself.

type Decision 

type Decision struct {
	NodeID     string       `json:"node_id"`
	Why        string       `json:"why"`
	Needs      Resources    `json:"needs"`
	Policy     Policy       `json:"policy"`
	Considered []Evaluation `json:"considered"`
	Rejected   []Rejection  `json:"rejected"`
	Warnings   []string     `json:"warnings,omitempty"`
}

Decision is the chosen node and the full account of how it was chosen.

func Pinned 

func Pinned(cands []Candidate, req Request, nodeID string) Decision

Pinned records an operator's explicit choice. It is honored even when the node lacks room, and the shortfall is carried as a warning.

func Spread 

func Spread(cands []Candidate, req Request) (Decision, error)

Spread filters out nodes that cannot take req, then picks the one that keeps the most headroom. Nodes whose capacity is unknown rank after every verified node; ties fall to load, then node id, so the choice is stable.

func (Decision) CapacityBlocked 

func (d Decision) CapacityBlocked() bool

CapacityBlocked reports whether any node was refused for lack of room.

type Dimension 

type Dimension struct {
	Name        string `json:"name"`
	Allocatable *int64 `json:"allocatable"`
	Requested   int64  `json:"requested"`
	Need        int64  `json:"need"`
	Free        *int64 `json:"free"`
	Shortfall   int64  `json:"shortfall"`
}

Dimension is one resource on one node, in the unit the operator reads. Allocatable is nil when the node never reported it. For disk, Requested is measured use and Allocatable already excludes the free-space floor.

func (Dimension) Describe 

func (d Dimension) Describe() string

Describe renders d's shortfall or state for an operator.

type Evaluation 

type Evaluation struct {
	NodeID     string      `json:"node_id"`
	Name       string      `json:"name"`
	Eligible   bool        `json:"eligible"`
	Reason     string      `json:"reason,omitempty"`
	Capacity   bool        `json:"capacity_blocked,omitempty"`
	Unverified bool        `json:"unverified,omitempty"`
	Headroom   *int        `json:"headroom_permille,omitempty"`
	Load       int         `json:"load"`
	Dimensions []Dimension `json:"dimensions"`
}

Evaluation is how one node fared for one placement request.

func Evaluate 

func Evaluate(c Candidate, req Request) Evaluation

Evaluate checks c against req: the structural filter first, then each resource. An unknown dimension never fails the node by itself, it marks the node Unverified (or fails it when the policy rejects unknowns).

type Policy 

type Policy struct {
	CPUOvercommitPercent    int  `json:"cpu_overcommit_percent"`
	MemoryOvercommitPercent int  `json:"memory_overcommit_percent"`
	MinFreeDiskPercent      int  `json:"min_free_disk_percent"`
	RejectUnknown           bool `json:"reject_unknown"`
}

Policy is the operator's overcommit and headroom setting. Percent 100 means requests may add up to the node's measured total and no further; above 100 allows overcommit. MinFreeDiskPercent keeps that share of the disk unplaceable. RejectUnknown filters nodes whose capacity cannot be verified instead of ranking them last.

func DefaultPolicy 

func DefaultPolicy() Policy

DefaultPolicy never overcommits, keeps 10 percent of disk free and ranks unverifiable nodes last rather than refusing them.

func (Policy) Validate 

func (p Policy) Validate() error

Validate rejects percentages outside their useful range.

type Rejection 

type Rejection struct {
	NodeID string `json:"node_id"`
	Reason string `json:"reason"`
}

Rejection says why one candidate was filtered out.

type Request 

type Request struct {
	Selector Selector
	// Exclude is skipped outright, typically the node being drained.
	Exclude string
	// Needs are the workload's total requests; zero asks for nothing.
	Needs  Resources
	Policy Policy
	// Prefer wins when it is eligible, e.g. the node that serves ingress.
	Prefer string
}

Request is what one placement decision needs.

type Resources 

type Resources struct {
	CPUMilli    int64 `json:"cpu_milli"`
	MemoryBytes int64 `json:"memory_bytes"`
	DiskBytes   int64 `json:"disk_bytes"`
}

Resources is what a workload asks for, or what placed workloads add up to.

func (Resources) Add 

func (r Resources) Add(o Resources) Resources

Add returns r plus o.

func (Resources) Times 

func (r Resources) Times(n int64) Resources

Times returns r multiplied by n, the replica count.

type Selector 

type Selector map[string]string

Selector is a set of key=value pairs a node's labels must all carry.

func (Selector) Matches 

func (sel Selector) Matches(labels map[string]string) bool

Matches reports whether labels satisfy every pair in sel.

func (Selector) String 

func (sel Selector) String() string

String renders sel as sorted "k=v,k=v".

Source Files

View all Source files

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.