capacity

Documentation

Overview

Package capacity converts forecasted load into desired replica counts using a deterministic policy (target per pod, headroom, lead time, clamps).

Index

• func ToReplicas(prev int, forecast []float64, stepSec int, p Policy) []int
• type Policy

Functions

func ToReplicas

func ToReplicas(prev int, forecast []float64, stepSec int, p Policy) []int

ToReplicas converts a forecasted load series into desired replicas, applying the policy. prev is the previously applied desired replica count (from the last control loop tick). forecast contains the metric values for each future step (e.g., RPS). stepSec is the step resolution in seconds.

Types

type Policy

type Policy struct {
	// TargetPerPod is the sustainable throughput per pod at your SLO (e.g., RPS per pod).
	// Must be > 0.
	TargetPerPod float64

	// Headroom is a multiplicative safety factor (e.g., 1.2 for +20%).
	// Must be >= 1.0
	Headroom float64

	// LeadTimeSeconds pre-warms capacity this many seconds before the predicted need.
	LeadTimeSeconds int

	// Min/Max replica bounds. MaxReplicas == 0 means "no upper bound".
	MinReplicas int
	MaxReplicas int

	// UpMaxFactorPerStep caps how fast we can scale up relative to the previous step.
	// Example: 2.0 allows doubling per step at most. If <= 0, defaults to 2.0.
	UpMaxFactorPerStep float64

	// DownMaxPercentPerStep caps how fast we can scale down (percentage of previous).
	// Example: 50 means we can drop at most 50% from the previous step. Clamped to [0,100].
	DownMaxPercentPerStep int

	// PrewarmWindowSteps defines how many *extra* steps beyond the lead index to consider.
	// 0 = single point at i+i0 (conservative). N>0 = max over [i+i0 .. i+i0+N] (aggressive).
	// v0.1 default should be 0 for predictable behavior.
	PrewarmWindowSteps int

	// RoundingMode controls how fractional pods are turned into integers.
	// "ceil" (default), "round", or "floor".
	RoundingMode string
}

Policy defines how forecasted load is translated into replicas.