capacity

package
v0.6.13 Latest Latest
Warning

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

Go to latest
Published: Nov 9, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package capacity implements admission control for sandbox creation.

Admission is purely resource-math — there is no fixed "max sandboxes" number. The admitter combines two signals before letting a sandbox in:

  1. Sum-of-reservations against host CPU cores and total memory, scaled by configurable ratios. This is predictable: the operator knows that accepted requests will not collectively exceed the ratio of host capacity, regardless of whether the sandboxes are actually using it. A 64-core box can run 200 tiny sandboxes or 8 huge ones — whatever the math allows.
  2. A live free-memory floor read from /proc/meminfo. This catches the case where reservations look fine but the host is genuinely tight right now (e.g. another process is eating RAM).

Reservations are tracked in-process. They must be replayed at startup from persistent state so a daemon restart doesn't reset accounting to zero.

Index

Constants

View Source
const (
	SlotPoolContainerNetns = "container_netns"
	SlotPoolFirecrackerTap = "firecracker_tap"
	SlotPoolWasmInstances  = "wasm_instances"
	// SlotPoolDockerBridge is the docker engine's sandbox network: every
	// running runc or gVisor sandbox, and every parked warm container, is
	// one veth on its bridge. The admitter counts it (SlotLimit).
	SlotPoolDockerBridge = "docker_bridge"
)

Slot pool names advertised in Snapshot.SlotPools. Placement matches pools by Runtimes, not by name; the names are for operators and dashboards.

View Source
const BridgeMaxPorts = 1023

BridgeMaxPorts is how many interfaces one Linux bridge holds. The kernel numbers bridge ports with 10 bits (BR_MAX_PORTS = 1 << BR_PORT_BITS = 1024) and never hands out port 0, so attaching a 1024th fails with EXFULL ("exchange full"). It bounds the docker sandbox network (docker0, or the br-<id> of SB_DOCKER_NETWORK) and the containerd engine's aerolvm0 alike: a 2026-11-02 metal density run stopped at exactly 1,023 docker sandboxes.

View Source
const DockerBridgePool = "docker bridge pool"

DockerBridgePool is the docker bridge pool in operator words: it leads the refusal message when the pool, or the bridge itself, is full.

Variables

View Source
var ErrCapacityExceeded = errors.New("host capacity exceeded")

ErrCapacityExceeded is returned by Admit when the host cannot accept a new sandbox. The wrapped error carries human-readable reasons; callers can use errors.Is to map this to a 503 response.

Functions

func AsNetworkSlotExhausted added in v0.6.9

func AsNetworkSlotExhausted(pool string, err error) error

AsNetworkSlotExhausted turns a network-exhaustion error into pool's capacity refusal. It is the backstop behind the counted pools, for a start that races past a count (something without a reservation took the last port): the API then answers 503 with Retry-After instead of a fault, and the retry can be placed elsewhere. The original error stays in the chain and the message. Any other error, and one that is already a capacity refusal, comes back unchanged.

func IsNetworkExhaustion added in v0.6.9

func IsNetworkExhaustion(err error) bool

IsNetworkExhaustion reports whether err is the host network refusing one more sandbox: a full bridge or a used-up subnet.

func ParkReservationID added in v0.5.5

func ParkReservationID(slotID string) string

ParkReservationID is the admitter key for a warm-pool parked slot.

func ReleaseParkReservation added in v0.5.5

func ReleaseParkReservation(admitter *Admitter, parkID string)

ReleaseParkReservation is the service-side transfer after adopt.

func SlotPoolExhausted added in v0.6.9

func SlotPoolExhausted(err error) (string, bool)

SlotPoolExhausted reports whether err is a slot-pool refusal and, if so, which pool refused.

Types

type Admitter

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

Admitter is the thread-safe admission controller. Construct with New and keep a single instance per daemon.

func New

func New(host HostInfo, limits Limits, probe MemProbe) *Admitter

New builds an admitter. host should reflect the machine's total capacity; callers that don't care about per-host detection can use DetectHost.

New constructs without an RSSSource (the Phase 5 memory-overcommit axis is disabled). Callers that want it should use NewWithRSSSource — kept as a separate constructor rather than adding a fifth positional arg here so existing call sites in tests and cluster bootstrapping stay untouched.

func NewWithRSSSource added in v0.4.1

func NewWithRSSSource(host HostInfo, limits Limits, probe MemProbe, rss RSSSource) *Admitter

NewWithRSSSource builds an admitter wired to a Phase 5 RSS source. nil rss is equivalent to New — the watermark check is skipped.

func (*Admitter) AddParkReclaimer added in v0.6.5

func (a *Admitter) AddParkReclaimer(fn ParkReclaimer)

AddParkReclaimer registers a warm pool that admission may reclaim parked slots from. A host can run more than one pool against this admitter (the docker pool is not gated on the engine), so each is asked in turn.

func (*Admitter) Admit

func (a *Admitter) Admit(sandboxID string, req Request) error

Admit decides whether a new sandbox with the given resource request can be accepted right now. On success it reserves the request under sandboxID and returns nil. On failure it returns an error wrapping ErrCapacityExceeded with reasons attached; no reservation is made.

Callers that fail downstream (e.g. docker create errors) must call Release to free the reservation. Reserve is idempotent per sandboxID — re-admitting the same ID overwrites the prior reservation.

A real create (any ID but park:*) that fails only on the CPU, memory or disk budget, by no more than parked warm slots hold, reclaims enough slots and is admitted. Reclaim runs without the lock because the pool frees each slot through Release, and it is bounded to two rounds: a refill park or another admit can take the freed room before the retry, and a create must not loop against a pool that keeps re-parking. It fires only when the host is otherwise full, so a create that fits pays nothing for it.

func (*Admitter) AdmitOwned added in v0.6.10

func (a *Admitter) AdmitOwned(sandboxID string, req Request) (owned bool, err error)

AdmitOwned is Admit for a create, which must know whether the reservation is its own to release. An ID that already holds a reservation (its live sandbox, or another create of the same ID) keeps it untouched — no overwrite, no budget check, since that capacity is already counted — and owned is false: the caller did not make it, and its rollback must not Release it. Otherwise it is Admit, and owned is true once admitted.

func (*Admitter) CanAdmitRequest added in v0.5.5

func (a *Admitter) CanAdmitRequest(req Request) (bool, []string)

CanAdmitRequest is a non-mutating admission probe for a specific shape. It counts parked slots as used, which is what the warm-pool refill gate needs: a park must never take capacity a parked slot already holds.

func (*Admitter) Release

func (a *Admitter) Release(sandboxID string)

Release frees the reservation for sandboxID. Safe to call for unknown IDs.

func (*Admitter) Reserve

func (a *Admitter) Reserve(sandboxID string, req Request)

Reserve records a reservation without running admission checks. Use this on startup to replay existing sandboxes from persistent state. Subsequent Admit calls see the replayed reservations as already-counted.

func (*Admitter) SetParkReclaimable added in v0.6.5

func (a *Admitter) SetParkReclaimable(id string, ready bool)

SetParkReclaimable marks a park:<slot-id> reservation as reclaimable (its slot sits ready in a pool) or not (spawning, or acquired for adoption). Pools call it through ParkGate.MarkParkReady; unknown or non-park IDs are ignored, so a notice that races a Release is harmless.

func (*Admitter) SetSlotLimit added in v0.6.9

func (a *Admitter) SetSlotLimit(l SlotLimit)

SetSlotLimit installs the admitter-counted slot pool (Total <= 0 removes it) and recounts the reservations already held, so it is correct whether it runs before or after ReplayReservations.

func (*Admitter) SlotPool added in v0.6.9

func (a *Admitter) SlotPool() (SlotPool, bool)

SlotPool reports the admitter-counted pool as a capacity report carries it; ok=false when none is set. A warm slot ready in its pool counts as free: a create adopts it or reclaims it, so it never needs a new port.

func (*Admitter) Snapshot

func (a *Admitter) Snapshot() Snapshot

Snapshot returns a point-in-time view. Includes a CanAdmit answer for a hypothetical zero-resource sandbox so operators can see "is this host accepting at all" without having to make a real request.

type HostInfo

type HostInfo struct {
	CPUCores      int
	MemoryTotalMB int
	// DiskTotalGB is the disk budget for sandbox storage. It is auto-detected
	// from the host filesystem by default and can be overridden by
	// SB_HOST_DISK_GB when the sandbox pool is smaller than the filesystem.
	DiskTotalGB int
	// DiskFreeGB is the currently available space on the detected sandbox
	// storage filesystem. It is an observability signal; reservation
	// admission uses DiskTotalGB × DiskReservationRatio.
	DiskFreeGB int
	// GPUCount and GPUVendor describe the GPU inventory the operator has
	// wired up to Docker. Operator-declared (SB_HOST_GPU_COUNT /
	// SB_HOST_GPU_VENDOR); 0 means no GPUs available.
	GPUCount  int
	GPUVendor string
	// SupportedRuntimes lists the OCI runtimes installed on this host.
	// Empty defaults to []{"docker"} at Admitter construction so a node
	// that doesn't set the field still admits the common case.
	SupportedRuntimes []string
	// Labels are the node's placement labels (SB_NODE_LABELS + SB_NODE_ZONE),
	// validated at boot. Static like GPUCount: the admitter only reports them.
	Labels map[string]string
}

HostInfo describes the static host capacity.

func DetectHost

func DetectHost() (HostInfo, error)

DetectHost returns CPU core count from runtime and memory total from /proc/meminfo via the default probe. Callers may override either field.

type Limits

type Limits struct {
	// CPUReservationRatio is the maximum fraction of host CPU cores that may
	// be reserved across all sandboxes. 0 = unlimited.
	CPUReservationRatio float64
	// MemoryReservationRatio is the maximum fraction of host memory that may
	// be reserved across all sandboxes. 0 = unlimited.
	MemoryReservationRatio float64
	// DiskReservationRatio is the maximum fraction of host disk that may be
	// reserved across all sandboxes. Disk is sized in GB rather than MB
	// because Docker's --storage-opt size is GB-granular and operators
	// reason about disk in GB. 0 = unlimited.
	DiskReservationRatio float64
	// MemoryFloorRatio is the minimum live MemAvailable the host must retain
	// after admitting the request, expressed as a fraction of total host
	// memory (e.g. 0.05 = keep at least 5% of RAM free). Expressing this as a
	// ratio means a 16 GB laptop and a 256 GB box scale their headroom
	// proportionally — a fixed MB floor would be either pointless on big
	// hosts or starve small ones. 0 = no floor.
	MemoryFloorRatio float64
	// CPUOverProvisionFactor multiplies the CPU reservation budget. Docker
	// --cpus is a CFS cap, not a hard reservation, so idle sandboxes share
	// cores happily — a 10× default lets typical workloads pack densely.
	// Values below 1.0 are clamped to 1.0 (no overcommit). 0 is treated as
	// the default 1.0 so a zero-value Limits behaves as before.
	CPUOverProvisionFactor float64
	// MemoryOverProvisionFactor multiplies the memory reservation budget.
	// Memory pressure is harder to recover from than CPU contention (OOM
	// killer fires on hard limits), so the live MemoryFloorRatio check is
	// the real backstop when this is set high. Same clamping as the CPU
	// factor.
	MemoryOverProvisionFactor float64
	// RSSWatermarkRatio is the Phase 5 memory-overcommit safety floor,
	// expressed as a fraction of host memory. Admission rejects a
	// request when EffectiveMemoryFree (HostMem - sum-of-VMM-RSS) would
	// drop below this watermark after admit. 0 disables the check (the
	// default) — operators opt in by setting the env var, and the check
	// is also gated on a non-nil RSSSource whose Ready() returns true,
	// so a pre-tick daemon falls back to nominal accounting. The point
	// of this axis is to safely raise MemoryOverProvisionFactor:
	// nominal accounting caps you at "host RAM × ratio × factor" but
	// can't see whether VMMs are actually touching the memory they
	// reserved; the watermark says "regardless of nominal, keep this
	// much real free RAM in reserve for the next RSS spike."
	RSSWatermarkRatio float64
}

Limits configures the admitter. Zero values disable the corresponding check.

type MemProbe

type MemProbe interface {
	FreeMB() (int, error)
}

MemProbe reports live free memory in MB. The default implementation reads /proc/meminfo MemAvailable. Tests can substitute a fake.

func NewProcMeminfoProbe

func NewProcMeminfoProbe() MemProbe

NewProcMeminfoProbe returns a MemProbe backed by /proc/meminfo with a 500ms cache. The cache window is small enough that decisions remain responsive to actual host memory pressure but large enough to absorb a burst of concurrent CreateSandbox calls without 50 file reads.

type ParkGate added in v0.5.5

type ParkGate struct {
	Admitter *Admitter
	// GuardShape is reserved for one default-shaped sandbox after each park.
	GuardShape Request
}

ParkGate implements warm-pool refill gating against the host admitter.

func (*ParkGate) CanPark added in v0.5.5

func (g *ParkGate) CanPark(shape dockerpool.ParkShape) bool

CanPark reports whether parking another slot leaves the guard band.

func (*ParkGate) MarkParkReady added in v0.6.5

func (g *ParkGate) MarkParkReady(slotID string, ready bool)

MarkParkReady tells the admitter whether a parked slot sits ready in its pool, and so whether a real create may reclaim it.

func (*ParkGate) ParkReservation added in v0.5.5

func (g *ParkGate) ParkReservation(slotID string, shape dockerpool.ParkShape) error

ParkReservation reserves capacity under park:<slot-id>.

func (*ParkGate) ReleasePark added in v0.5.5

func (g *ParkGate) ReleasePark(slotID string)

ReleasePark frees a park reservation.

type ParkReclaimer added in v0.6.5

type ParkReclaimer func(slots int) int

ParkReclaimer gives up to slots warm-pool slots back to the admitter and returns how many it released. It must release each slot's park:<slot-id> reservation before returning (container teardown may finish later), and it is called without the admitter lock held, so it may call Release.

type RSSSource added in v0.4.1

type RSSSource interface {
	TotalRSSMB() int
	Ready() bool
}

RSSSource is the Phase 5 bridge for the per-VMM RSS sampler that lives in internal/runtime/firecracker. The structural shape keeps pkg/capacity from importing the runtime package (and forming a cycle through main.go); the sampler satisfies the interface without declaring it.

TotalRSSMB returns the most recent aggregate in MB; Ready reports whether the sampler has produced at least one observation. Admission only consults TotalRSSMB when Ready returns true — pre-tick, the "0 MB resident" reading is indistinguishable from "host is empty" and falsely admits under any non-zero RSSWatermarkRatio.

type Request

type Request struct {
	CPU        float64
	MemoryMB   int
	DiskGB     int
	GPUs       int
	GPUVendor  string
	Runtime    string
	TemplateID string
	// ModuleRef, when set alongside Runtime="wasm", lets cluster placement
	// prefer peers that already have the module cached locally.
	ModuleRef string
	// RequiredNodeID pins non-portable local artifacts (for example an image
	// built on one worker) to the only node that can satisfy the request.
	RequiredNodeID string
	// NeedsEgressGateway marks a gateway-mode container create (hostname
	// egress rules). Placement sends it only to peers advertising
	// EgressGatewayReady (plans/egress-domain-filtering.md CEO D20).
	NeedsEgressGateway bool
	// NeedsMediatedEgress marks a WASM or isolate create that sets an egress
	// field. Placement sends it only to peers advertising MediatedEgress.
	NeedsMediatedEgress bool
	// Labels are the node labels the request requires, zone included under
	// "zone" (plans/placement-rules.md). Placement keeps only peers whose
	// heartbeat Labels carry every one with the same value. nil = no rule.
	// It crosses the agent's select-placement RPC as part of this struct, so
	// it keeps a JSON name a control plane can read.
	Labels map[string]string `json:"Labels,omitempty"`
}

Request is the per-sandbox resource ask, in normalized units. CPU is fractional cores (e.g. 0.5 = half a core); memory is whole MB; disk is whole GB. GPUs is the count requested (0 = no GPU); GPUVendor is the required vendor when GPUs > 0 and is matched against HostInfo.GPUVendor at admission/placement time. Runtime is the OCI runtime identifier ("docker", "gvisor", ...) — empty means "any runtime the host supports." TemplateID, when set alongside Runtime="firecracker", lets placement prefer (and gate on) peers that already have the template's artifacts cached locally — empty means "any host," matching pre-Phase-6 behaviour.

type SlotLimit added in v0.6.9

type SlotLimit struct {
	// Name is the SlotPool name advertised in Snapshot.SlotPools.
	Name string
	// Pool names the pool in operator words; it leads the refusal message.
	Pool string
	// Runtimes are the runtimes whose sandboxes take a slot.
	Runtimes []string
	// Total is how many slots the pool has; <= 0 turns the limit off.
	Total int
}

SlotLimit is a per-node network-slot pool that the admitter counts itself, from its own reservations, for sandboxes whose slot no store table tracks: the docker engine's sandbox bridge, where dockerd attaches one veth per running container and the kernel refuses the 1,024th.

Every reservation whose runtime the pool serves holds one slot, warm-pool parks (park:*) included. That makes the count exact without a new record: a create reserves before the container exists and releases on any failure, destroy and stop release (dockerd tears the veth down on stop, and StartSandbox re-admits), and after a restart ReplayReservations rebuilds it from the store.

type SlotPool added in v0.6.9

type SlotPool struct {
	Name     string   `json:"name"`
	Runtimes []string `json:"runtimes"`
	Total    int      `json:"total"`
	Free     int      `json:"free"`
}

SlotPool is one bounded per-node pool as a capacity heartbeat reports it. Runtimes lists every runtime whose creates take a slot from it: on a containerd node runc ("docker") and gVisor share the one netns pool, so a pending gVisor create uses up a slot a docker create could have had.

func (SlotPool) Serves added in v0.6.9

func (p SlotPool) Serves(runtime string) bool

Serves reports whether creates of runtime take a slot from this pool.

type SlotPoolExhaustedError added in v0.6.9

type SlotPoolExhaustedError struct {
	// Pool names the exhausted pool in operator words ("container netns
	// pool"); it leads the message so a log line says which limit was hit.
	Pool string
}

SlotPoolExhaustedError is the error a bounded per-node slot pool returns when it has no free slot. It is a capacity refusal, not a fault: errors.Is matches ErrCapacityExceeded, so every surface answers it like any other admission refusal (503 with Retry-After), the SDKs retry it, and cluster placement can send the retry to a node that still has slots.

Pools declare one package-level value each (store.ErrNoFreeContainerNetnsSlot, store.ErrNoFreeFirecrackerTapSlot, ...), so errors.Is against that value keeps working by identity.

func NewSlotPoolExhausted added in v0.6.9

func NewSlotPoolExhausted(pool string) *SlotPoolExhaustedError

NewSlotPoolExhausted returns the exhaustion error for the named pool.

func (*SlotPoolExhaustedError) Error added in v0.6.9

func (e *SlotPoolExhaustedError) Error() string

func (*SlotPoolExhaustedError) Unwrap added in v0.6.9

func (e *SlotPoolExhaustedError) Unwrap() error

Unwrap makes errors.Is(err, ErrCapacityExceeded) true, which is the whole classification contract: no API surface needs to know slot pools exist.

type Snapshot

type Snapshot struct {
	HostCPUCores      int     `json:"host_cpu_cores"`
	HostMemoryTotalMB int     `json:"host_memory_total_mb"`
	HostDiskTotalGB   int     `json:"host_disk_total_gb,omitempty"`
	HostDiskFreeGB    int     `json:"host_disk_free_gb,omitempty"`
	ReservedCPU       float64 `json:"reserved_cpu"`
	ReservedMemoryMB  int     `json:"reserved_memory_mb"`
	ReservedDiskGB    int     `json:"reserved_disk_gb,omitempty"`
	ReservedGPUs      int     `json:"reserved_gpus,omitempty"`
	AvailableCPU      float64 `json:"available_cpu"`
	AvailableMemoryMB int     `json:"available_memory_mb"`
	AvailableDiskGB   int     `json:"available_disk_gb,omitempty"`
	AvailableGPUs     int     `json:"available_gpus,omitempty"`
	LiveMemoryFreeMB  int     `json:"live_memory_free_mb"`
	SandboxesActive   int     `json:"sandboxes_active"`
	// Parked* is the part of the Reserved* totals held by warm-pool slots
	// (park:<slot-id>). Admission gives it back to a real sandbox by
	// reclaiming slots, so placement treats it as free when deciding fit.
	// Zero (omitted) on a peer that predates the fields, which makes
	// placement read that peer exactly as before.
	ParkedCPU      float64 `json:"parked_cpu,omitempty"`
	ParkedMemoryMB int     `json:"parked_memory_mb,omitempty"`
	ParkedDiskGB   int     `json:"parked_disk_gb,omitempty"`
	ParkedSlots    int     `json:"parked_slots,omitempty"`
	// SandboxesByRuntime is the live reservation count keyed by OCI runtime
	// ("docker"/containerd, "gvisor", "wasm", "isolate", "firecracker";
	// "unspecified" for a runtime-agnostic reservation). Lets dashboards show
	// live sandboxes broken down by isolation type — the bare SandboxesActive
	// gauge has no runtime label.
	SandboxesByRuntime        map[string]int `json:"sandboxes_by_runtime,omitempty"`
	CanAdmit                  bool           `json:"can_admit"`
	Reasons                   []string       `json:"reasons,omitempty"`
	CPUReservationRatio       float64        `json:"cpu_reservation_ratio"`
	MemoryReservationRatio    float64        `json:"memory_reservation_ratio"`
	DiskReservationRatio      float64        `json:"disk_reservation_ratio,omitempty"`
	MemoryFloorRatio          float64        `json:"memory_floor_ratio"`
	CPUOverProvisionFactor    float64        `json:"cpu_overprovision_factor"`
	MemoryOverProvisionFactor float64        `json:"memory_overprovision_factor"`
	// MemoryFloorMB is the absolute floor derived from MemoryFloorRatio and
	// host memory, exposed for operators reading /capacity.
	MemoryFloorMB int `json:"memory_floor_mb"`
	// Phase 5 effective-memory axis. ActualRSSMB is the live aggregate
	// from the per-VMM sampler; EffectiveMemoryFreeMB is the headroom
	// admission actually decides against (HostMem - ActualRSSMB);
	// RSSWatermarkMB is the absolute floor derived from
	// RSSWatermarkRatio. All four are 0 on hosts without a sampler so
	// peers running older binaries report 0 and placement falls back to
	// nominal accounting rather than treating "0" as "host is empty".
	ActualRSSMB           int     `json:"actual_rss_mb,omitempty"`
	EffectiveMemoryFreeMB int     `json:"effective_memory_free_mb,omitempty"`
	RSSWatermarkMB        int     `json:"rss_watermark_mb,omitempty"`
	RSSWatermarkRatio     float64 `json:"rss_watermark_ratio,omitempty"`
	// CPUBudget and MemoryBudgetMB are the post-overcommit budgets actually
	// used by Admit, exposed so operators can see the effective ceiling.
	CPUBudget      float64 `json:"cpu_budget"`
	MemoryBudgetMB int     `json:"memory_budget_mb"`
	DiskBudgetGB   int     `json:"disk_budget_gb,omitempty"`
	// GPUCount and GPUVendor are static node attributes set by the operator
	// (no auto-detection in Phase 1). Placement uses them to skip a peer
	// that cannot satisfy a GPU sandbox at all — running the admitter
	// remotely after a doomed forward would just 503.
	GPUCount  int    `json:"gpu_count,omitempty"`
	GPUVendor string `json:"gpu_vendor,omitempty"`
	// SupportedRuntimes lists the OCI runtimes this host can run
	// ("docker", "gvisor", ...). Used by placement to skip a peer that
	// doesn't have, say, runsc installed. Empty = legacy node, treated as
	// supporting any runtime so rolling upgrades don't strand pre-D peers.
	SupportedRuntimes []string `json:"supported_runtimes,omitempty"`
	// EgressGatewayReady is true while this node's egress gateway is
	// connected and synced, so hostname-filtered creates can be attached.
	// Unlike SupportedRuntimes there is no unknown-allow rule: a peer that
	// omits it (an older build, or the gateway down) gets no gateway-mode
	// creates, because landing one there means a 501 or a 503 instead of a
	// filtered sandbox (plans/egress-domain-filtering.md CEO D20).
	EgressGatewayReady bool `json:"egress_gateway_ready,omitempty"`
	// MediatedEgress is true on builds whose WASM and isolate mediators
	// enforce egress policies (block-all, lists, profiles, learn mode). An
	// older build stored a WASM create's lists and ignored them, so, as for
	// the gateway, a peer that omits it gets no policy-bearing mediated
	// create: during a rolling upgrade those wait for an upgraded peer
	// rather than run unfiltered (review finding 10).
	MediatedEgress bool `json:"mediated_egress,omitempty"`
	// ContainerEngine is an observability tag (docker|containerd) so benches
	// and canary nodes compare engines like-for-like. Deliberately NOT a
	// placement attribute — see plans/containerd-engine.md §2 D18.
	ContainerEngine string `json:"container_engine,omitempty"`
	// SlotPools reports this host's bounded per-sandbox slot pools (slots.go)
	// and how many slots each has free. Placement skips a peer whose pool for
	// the request's runtime has no free slot once its in-flight reservations
	// are counted. The admitter does not fill it: the service overlays it on
	// /v1/capacity and on its own lease, from a short cache. Omitted by a peer
	// that predates the field, which placement reads as "no slot limit".
	SlotPools []SlotPool `json:"slot_pools,omitempty"`
	// LocalTemplateInventoryKnown distinguishes an authoritative empty
	// Firecracker template inventory from a legacy/unknown peer. When
	// false, placement treats LocalTemplateIDs as "unknown, allow" for
	// rolling upgrades and just-joined nodes. When true, an empty
	// LocalTemplateIDs slice means this host definitely has no local
	// templates cached.
	LocalTemplateInventoryKnown bool `json:"local_template_inventory_known,omitempty"`
	// LocalTemplateIDs lists the Firecracker templates whose artifact
	// files (rootfs.ext4 + snapshot.{memory,state}) are present on this
	// host. Placement gates a Firecracker create against it so a clone
	// against a template the target has never seen lands on a node that
	// already has it — preserving the <100ms boot promise. Consult
	// LocalTemplateInventoryKnown before treating an empty list as
	// authoritative: pre-upgrade peers omit both fields and degrade to
	// pre-feature behaviour, while known=true plus an empty list means
	// "definitely no local templates here."
	LocalTemplateIDs []string `json:"local_template_ids,omitempty"`
	// LocalTemplateCatalogInventoryKnown distinguishes an authoritative empty
	// administrative catalogue from a peer that has not published one yet.
	// Unlike LocalTemplateIDs, the catalogue includes pending and failed rows:
	// item GET/DELETE/rebuild must still route to their owning worker.
	LocalTemplateCatalogInventoryKnown bool `json:"local_template_catalog_inventory_known,omitempty"`
	// LocalTemplateCatalogIDs lists every locally-owned template row regardless
	// of lifecycle status. It is used only for O(1) control-plane routing and
	// must never be used to decide whether a node can boot a template.
	LocalTemplateCatalogIDs []string `json:"local_template_catalog_ids,omitempty"`
	// LocalWasmModuleInventoryKnown mirrors LocalTemplateInventoryKnown for
	// runtime=wasm module_ref placement (plans/wasm-runtime.md Phase 7).
	LocalWasmModuleInventoryKnown bool `json:"local_wasm_module_inventory_known,omitempty"`
	// LocalWasmModuleIDs lists module_ref values cached on this host.
	LocalWasmModuleIDs []string `json:"local_wasm_module_ids,omitempty"`
	// WarmPools is this host's warm-pool status for each API warm-pool
	// entry (plans/agent-sandbox-feature-parity.md W1). It rides the
	// capacity heartbeat so any server can answer GET /v1/warm-pools per
	// server without a fan-out. Only entries are listed, never miss-driven
	// targets, and models.MaxWarmPools bounds them, so it stays small.
	// Omitted by a host with no warm pool and by a peer that predates it.
	WarmPools []WarmPoolStatus `json:"warm_pools,omitempty"`
	// Labels are this node's operator-declared labels (SB_NODE_LABELS, plus
	// SB_NODE_ZONE under "zone"). They ride this authenticated heartbeat, not
	// gossip meta: memberlist meta is capped at 512 bytes and overflowing it
	// once stripped Raft addresses (plans/placement-rules.md P1.2). A peer
	// that predates the field reports none, so it never satisfies a placement
	// rule: a rule fails closed rather than landing on an unlabelled node.
	Labels map[string]string `json:"labels,omitempty"`
}

Snapshot is a read-only view of admitter state, suitable for an HTTP /capacity response. It is also the payload in cluster capacity heartbeats: every field needed to decide "can this peer host this request?" must be present here, otherwise placement scores against stale assumptions and the caller fans out to a node that can't actually admit.

func (Snapshot) SlotPoolFor added in v0.6.9

func (s Snapshot) SlotPoolFor(runtime string) (SlotPool, bool)

SlotPoolFor returns the pool runtime's creates draw from on this host. ok=false means the host reports no bounded pool for it — a runtime without one (isolate, uncapped WASM), or a peer that predates SlotPools — and placement treats that as "unknown, allow", like an empty SupportedRuntimes.

type WarmPoolStatus added in v0.6.12

type WarmPoolStatus struct {
	Image  string `json:"image"`
	Ready  int    `json:"ready"`
	Target int    `json:"target"`
	// Outdated counts ready slots holding an older image than the tag
	// names now (W3); omitted when none.
	Outdated int `json:"outdated,omitempty"`
}

WarmPoolStatus is one warm-pool entry's state on one host: slots parked and ready for a create, and how many the host is aiming for.

Jump to

Keyboard shortcuts

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