api-reference.md

API reference

API group: scaling.presage.sh, version v1alpha1.

ForecastBackend

Scope: Cluster. Version: v1alpha1.

ForecastBackend is a cluster-scoped forecasting engine.

ForecastBackend.spec

ForecastBackendSpec defines a forecasting backend usable by any PredictiveScaler in the cluster.

Field	Type	Required	Description
seasonalNaive	object		SeasonalNaiveBackend configures the built-in baseline forecaster.
timesFM	object		TimesFMBackend configures the TimesFM model server.
type	TimesFM | SeasonalNaive	yes	BackendType selects a forecasting implementation. Default: SeasonalNaive.

ForecastBackend.spec.seasonalNaive

SeasonalNaiveBackend configures the built-in baseline forecaster.

Field	Type	Required	Description
cycles	integer		Cycles is how many past seasons to average over. Quantiles come from the empirical distribution of residuals across these cycles. Default: 3.
season	string		Season is the periodicity to repeat, typically 24h or 168h. Default: 168h.

ForecastBackend.spec.timesFM

TimesFMBackend configures the TimesFM model server.

Field	Type	Required	Description
endpoint	string	yes	Endpoint is the base URL of a presage-forecaster instance, e.g. "http://presage-forecaster.presage-system:8080".
maxContext	integer		MaxContext is the number of input points the model was compiled for. TimesFM 2.5 supports up to 16384. Together with the signal Resolution this decides how far back the model can see: 4096 points at 5m resolution is ~14 days. Default: 4096.
maxHorizon	integer		MaxHorizon is the number of output points the model was compiled for. Default: 64.
model	string		Model is the checkpoint the server should load. Changing this requires restarting the forecaster; presage only reports what the server tells it. Default: google/timesfm-2.5-200m-pytorch.
timeout	string		Timeout for a single forecast request. Default: 30s.
useQuantileHead	boolean		UseQuantileHead enables TimesFM 2.5's continuous quantile head. Without it you get a point forecast only, and the asymmetric up/down quantile policy degenerates to a single number. Default: True.

ForecastBackend.status

ForecastBackendStatus reports backend reachability.

Field	Type	Required	Description
conditions	[]object
lastProbeTime	string
model	string		Model reported by the backend on its last successful probe.
observedGeneration	integer

ForecastBackend.status.conditions

Condition contains details for one aspect of the current state of this API Resource.

Field	Type	Required	Description
lastTransitionTime	string	yes	lastTransitionTime is the last time the condition transitioned from one status to another. This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable.
message	string	yes	message is a human readable message indicating details about the transition. This may be an empty string.
observedGeneration	integer		observedGeneration represents the .metadata.generation that the condition was set based upon. For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date with respect to the current state of the instance.
reason	string	yes	reason contains a programmatic identifier indicating the reason for the condition's last transition. Producers of specific condition types may define expected values and meanings for this field, and whether the values are considered a guaranteed API. The value should be a CamelCase string. This field may not be empty.
status	True | False | Unknown	yes	status of the condition, one of True, False, Unknown.
type	string	yes	type of condition in CamelCase or in foo.example.com/CamelCase.

PredictiveScaler

Scope: Namespaced. Version: v1alpha1.

PredictiveScaler forecasts a workload's demand and sizes it for the demand expected once new replicas are actually ready.

PredictiveScaler.spec

PredictiveScalerSpec defines the desired state of a PredictiveScaler.

Field	Type	Required	Description
capacity	object		Capacity applies to the single-signal form only; multi-signal scalers carry a capacity per signal.
forecast	object		ForecastSpec selects and parameterises the forecasting backend.
interval	string		Interval is how often to refresh the forecast and recommendation. Note that for Agones targets this is decoupled from the FleetAutoscaler sync period: Agones may poll the webhook every 30s while presage refreshes the underlying forecast far less often. Default: 1m.
leadTime	object		LeadTimeSpec configures the forecast horizon. This is the reason predictive autoscaling beats reactive autoscaling. A reactive autoscaler observes demand at time T and starts a replica that is only useful at T+lead, so it is structurally always one lead time behind. presage forecasts demand at T+lead and provisions for that instead.
mode	Shadow | Enforce		Mode defaults to Shadow. Run a workload in Shadow long enough to compare the recommendation against what actually happened before switching. Default: Shadow.
policy	object	yes	PolicySpec is the decision layer: how a predictive distribution becomes a replica count.
scaleTargetRef	object	yes	ScaleTargetRef identifies the workload whose replica count is being managed. Two families of target are supported: - Anything exposing the standard scale subresource (Deployment, StatefulSet, ReplicaSet, and most custom resources that implement it). This is the default and requires no target-specific support in presage. - An Agones Fleet, which is NOT scaled directly. Instead presage serves a FleetAutoscaler webhook for it; see AgonesFleetTarget.
signal	object		Signal is the single-signal form, paired with the top-level Capacity. Exactly one of Signal or Signals must be set.
signals	[]object		Signals is the multi-signal form. Each entry becomes a replica requirement and the largest binds, so the workload ends up sized for whichever dimension needs the most.

PredictiveScaler.spec.capacity

Capacity applies to the single-signal form only; multi-signal scalers carry a capacity per signal.

Field	Type	Required	Description
perReplica	int-or-string		PerReplica is how many units of the signal one replica serves. If the signal is already expressed in replicas (for example, forecasting allocated GameServers directly), set this to 1. Default: 1.
query	object		Query optionally derives per-replica capacity from live data instead of a constant, e.g. average capacity across the fleet. Takes precedence over PerReplica when set.

PredictiveScaler.spec.capacity.query

Query optionally derives per-replica capacity from live data instead of a constant, e.g. average capacity across the fleet. Takes precedence over PerReplica when set.

Field	Type	Required	Description
address	string	yes	Address is the base URL of the query endpoint, e.g. "http://vmselect.monitoring:8481/select/0/prometheus".
bearerTokenSecretRef	object		BearerTokenSecretRef optionally supplies an Authorization bearer token.
insecureSkipVerify	boolean		InsecureSkipVerify disables TLS verification. Not recommended.
query	string	yes	Query must evaluate to exactly one series. If it returns more than one, the PredictiveScaler goes Degraded rather than silently picking one.

PredictiveScaler.spec.capacity.query.bearerTokenSecretRef

BearerTokenSecretRef optionally supplies an Authorization bearer token.

Field	Type	Required	Description
key	string	yes
name	string	yes

PredictiveScaler.spec.forecast

ForecastSpec selects and parameterises the forecasting backend.

Field	Type	Required	Description
backendRef	string		BackendRef names a cluster-scoped ForecastBackend. If unset, the backend named "default" is used.
horizon	string		Horizon is how far ahead to forecast. It must be at least the lead time; forecasting further is harmless and makes the projected curve useful for dashboards. Defaults to 4x the resolved lead time.

PredictiveScaler.spec.leadTime

LeadTimeSpec configures the forecast horizon. This is the reason predictive autoscaling beats reactive autoscaling. A reactive autoscaler observes demand at time T and starts a replica that is only useful at T+lead, so it is structurally always one lead time behind. presage forecasts demand at T+lead and provisions for that instead.

Field	Type	Required	Description
max	string		Default: 15m.
min	string		Min and Max clamp the resolved lead time. They bound the damage from a bad Observed query and stop the horizon from collapsing to zero (which would silently turn presage into a reactive autoscaler). Default: 30s.
observed	object		Observed is the query used when Source is Observed. It must return a single scalar in seconds -- typically a high quantile of the time from pod creation to readiness.
source	Static | Observed		LeadTimeSource selects how the provisioning lead time is determined. Default: Static.
static	string		Static is the lead time used when Source is Static. Default: 2m.

PredictiveScaler.spec.leadTime.observed

Observed is the query used when Source is Observed. It must return a single scalar in seconds -- typically a high quantile of the time from pod creation to readiness.

Field	Type	Required	Description
address	string	yes	Address is the base URL of the query endpoint, e.g. "http://vmselect.monitoring:8481/select/0/prometheus".
bearerTokenSecretRef	object		BearerTokenSecretRef optionally supplies an Authorization bearer token.
insecureSkipVerify	boolean		InsecureSkipVerify disables TLS verification. Not recommended.
query	string	yes	Query must evaluate to exactly one series. If it returns more than one, the PredictiveScaler goes Degraded rather than silently picking one.

PredictiveScaler.spec.leadTime.observed.bearerTokenSecretRef

BearerTokenSecretRef optionally supplies an Authorization bearer token.

Field	Type	Required	Description
key	string	yes
name	string	yes

PredictiveScaler.spec.policy

PolicySpec is the decision layer: how a predictive distribution becomes a replica count.

Field	Type	Required	Description
headroom	int-or-string		Headroom is extra capacity applied on top of the forecast, as an absolute number of signal units or a percentage. Default: 10%.
maxReplicas	integer	yes
minReplicas	integer		Default: 1.
reactiveFloor	object		ReactiveFloor keeps a conventional reactive computation running alongside the forecast and takes the maximum of the two. With it enabled, forecast error can only ever cause over-provisioning -- presage is then strictly safer than the reactive policy it replaces. Disabling it is what unlocks scale-to-zero, at the cost of that guarantee. MaxReplicas and MaxScaleUpRate remain hard constraints and can bind below the floor; the floor removes forecast error as a cause of under-provisioning, not operator-configured limits.
scaleDownQuantile	string		ScaleDownQuantile is the lower quantile used to measure how confident the forecast is. It never sets the target -- its only job is to feed ScaleDownUncertaintyGuard. Default: 0.5.
scaleDownUncertaintyGuard	object		ScaleDownUncertaintyGuard refuses to release capacity while the forecast is too uncertain. Adding capacity is deliberately never gated this way.
stabilization	object		StabilizationSpec damps oscillation.
targetQuantile	string		TargetQuantile is the service level capacity is sized to: the workload is provisioned for the demand this quantile of the forecast implies, in both directions. Raising it buys protection against being wrong in the expensive direction. Note that a more uncertain forecast has a fatter upper tail, so this automatically provisions more when the model is unsure. Uncertainty should buy capacity, not hesitation. Default: 0.9.

PredictiveScaler.spec.policy.reactiveFloor

ReactiveFloor keeps a conventional reactive computation running alongside the forecast and takes the maximum of the two. With it enabled, forecast error can only ever cause over-provisioning -- presage is then strictly safer than the reactive policy it replaces. Disabling it is what unlocks scale-to-zero, at the cost of that guarantee. MaxReplicas and MaxScaleUpRate remain hard constraints and can bind below the floor; the floor removes forecast error as a cause of under-provisioning, not operator-configured limits.

Field	Type	Required	Description
bufferSize	int-or-string		BufferSize is the spare capacity the reactive floor insists on, as an absolute number of replicas or a percentage of current demand. Default: 10%.
enabled	boolean		Default: True.

PredictiveScaler.spec.policy.scaleDownUncertaintyGuard

ScaleDownUncertaintyGuard refuses to release capacity while the forecast is too uncertain. Adding capacity is deliberately never gated this way.

Field	Type	Required	Description
enabled	boolean		Default: True.
maxRelativeSpread	string		MaxRelativeSpread is the largest (upper - lower) / max(lower, 1) that still permits a scale-down. Lower values are more conservative. Default: 0.25.

PredictiveScaler.spec.policy.stabilization

StabilizationSpec damps oscillation.

Field	Type	Required	Description
maxScaleDownRate	int-or-string		MaxScaleDownRate caps a single step's decrease. Default: 20%.
maxScaleUpRate	int-or-string		MaxScaleUpRate caps a single step's increase, as replicas or a percentage of current replicas. Default: 100%.
scaleDownWindow	string		ScaleDownWindow is how long the recommendation must stay below the current replica count before a scale-down is allowed. Scale-up is deliberately not delayed by default: the whole point is to be early. Default: 15m.

PredictiveScaler.spec.scaleTargetRef

ScaleTargetRef identifies the workload whose replica count is being managed. Two families of target are supported: - Anything exposing the standard scale subresource (Deployment, StatefulSet, ReplicaSet, and most custom resources that implement it). This is the default and requires no target-specific support in presage. - An Agones Fleet, which is NOT scaled directly. Instead presage serves a FleetAutoscaler webhook for it; see AgonesFleetTarget.

Field	Type	Required	Description
agones	object		Agones carries options that only apply when Kind is "Fleet" in the agones.dev group. When set, presage does not write replicas directly; it publishes the recommendation on its FleetAutoscaler webhook endpoint so that Agones remains the single writer of Fleet replicas.
apiVersion	string	yes	APIVersion of the target, e.g. "apps/v1".
kind	string	yes	Kind of the target, e.g. "Deployment".
name	string	yes	Name of the target. Must be in the same namespace as the PredictiveScaler.

PredictiveScaler.spec.scaleTargetRef.agones

Agones carries options that only apply when Kind is "Fleet" in the agones.dev group. When set, presage does not write replicas directly; it publishes the recommendation on its FleetAutoscaler webhook endpoint so that Agones remains the single writer of Fleet replicas.

Field	Type	Required	Description
maxRecommendationAge	string		MaxRecommendationAge is how stale a cached recommendation may be before the webhook starts refusing to answer (returning an error so that a Chain policy falls through to its next entry). Keep this comfortably above the reconcile Interval. Default: 5m.

PredictiveScaler.spec.signal

Signal is the single-signal form, paired with the top-level Capacity. Exactly one of Signal or Signals must be set.

Field	Type	Required	Description
history	string		History is how much past data to feed the model. Capped by the backend's maximum context length. Two to four weeks is a reasonable default for workloads with weekly seasonality. Default: 336h.
prometheus	object		Prometheus reads the signal from a Prometheus-compatible range query endpoint (Prometheus, Thanos, Mimir, VictoriaMetrics vmselect, ...).
resolution	string		Resolution is the bucket width the series is sampled at. This is the single most consequential tuning knob: a foundation model sees a fixed number of points, so resolution decides how far back its context reaches. At 5m with a 16k-point context you get ~57 days, which comfortably covers weekly seasonality. At 1m you get ~11 days, which does not. Default: 5m.

PredictiveScaler.spec.signal.prometheus

Prometheus reads the signal from a Prometheus-compatible range query endpoint (Prometheus, Thanos, Mimir, VictoriaMetrics vmselect, ...).

Field	Type	Required	Description
address	string	yes	Address is the base URL of the query endpoint, e.g. "http://vmselect.monitoring:8481/select/0/prometheus".
bearerTokenSecretRef	object		BearerTokenSecretRef optionally supplies an Authorization bearer token.
insecureSkipVerify	boolean		InsecureSkipVerify disables TLS verification. Not recommended.
query	string	yes	Query must evaluate to exactly one series. If it returns more than one, the PredictiveScaler goes Degraded rather than silently picking one.

PredictiveScaler.spec.signal.prometheus.bearerTokenSecretRef

BearerTokenSecretRef optionally supplies an Authorization bearer token.

Field	Type	Required	Description
key	string	yes
name	string	yes

PredictiveScaler.spec.signals

NamedSignal is one demand dimension in a multi-signal scaler. Each signal is converted to a replica requirement independently and the largest binds, the way an HPA combines multiple metrics. A workload has to be big enough for every dimension it serves, so summing or averaging them would let a quiet dimension mask a busy one.

Field	Type	Required	Description
capacity	object	yes	Capacity converts this signal's units into replicas. Required, because there is no sensible shared default across dimensions measured in different units.
history	string		Default: 336h.
name	string	yes	Name identifies the signal in status and metrics. Must be unique within the scaler.
prometheus	object	yes	Prometheus reads this signal from a Prometheus-compatible endpoint.
resolution	string		Default: 5m.

PredictiveScaler.spec.signals.capacity

Capacity converts this signal's units into replicas. Required, because there is no sensible shared default across dimensions measured in different units.

Field	Type	Required	Description
perReplica	int-or-string		PerReplica is how many units of the signal one replica serves. If the signal is already expressed in replicas (for example, forecasting allocated GameServers directly), set this to 1. Default: 1.
query	object		Query optionally derives per-replica capacity from live data instead of a constant, e.g. average capacity across the fleet. Takes precedence over PerReplica when set.

PredictiveScaler.spec.signals.capacity.query

Query optionally derives per-replica capacity from live data instead of a constant, e.g. average capacity across the fleet. Takes precedence over PerReplica when set.

Field	Type	Required	Description
address	string	yes	Address is the base URL of the query endpoint, e.g. "http://vmselect.monitoring:8481/select/0/prometheus".
bearerTokenSecretRef	object		BearerTokenSecretRef optionally supplies an Authorization bearer token.
insecureSkipVerify	boolean		InsecureSkipVerify disables TLS verification. Not recommended.
query	string	yes	Query must evaluate to exactly one series. If it returns more than one, the PredictiveScaler goes Degraded rather than silently picking one.

PredictiveScaler.spec.signals.capacity.query.bearerTokenSecretRef

BearerTokenSecretRef optionally supplies an Authorization bearer token.

Field	Type	Required	Description
key	string	yes
name	string	yes

PredictiveScaler.spec.signals.prometheus

Prometheus reads this signal from a Prometheus-compatible endpoint.

Field	Type	Required	Description
address	string	yes	Address is the base URL of the query endpoint, e.g. "http://vmselect.monitoring:8481/select/0/prometheus".
bearerTokenSecretRef	object		BearerTokenSecretRef optionally supplies an Authorization bearer token.
insecureSkipVerify	boolean		InsecureSkipVerify disables TLS verification. Not recommended.
query	string	yes	Query must evaluate to exactly one series. If it returns more than one, the PredictiveScaler goes Degraded rather than silently picking one.

PredictiveScaler.spec.signals.prometheus.bearerTokenSecretRef

BearerTokenSecretRef optionally supplies an Authorization bearer token.

Field	Type	Required	Description
key	string	yes
name	string	yes

PredictiveScaler.status

PredictiveScalerStatus is the observed state of a PredictiveScaler.

Field	Type	Required	Description
breakdown	object		RecommendationBreakdown records how the number was arrived at, so that a surprising replica count can be explained without re-deriving it.
conditions	[]object
currentReplicas	integer		CurrentReplicas last read from the target.
lastForecast	object		LastForecast describes the binding signal's forecast.
lastScaleTime	string
observedGeneration	integer
recommendedReplicas	integer		RecommendedReplicas is what presage would apply (and does apply in Enforce mode).
scaleDownCandidateSince	string		ScaleDownCandidateSince tracks the start of the scale-down stabilization window. Cleared whenever the recommendation stops being below current.
signalStatuses	[]object		SignalStatuses carries one entry per configured signal, so a multi-signal scaler can be debugged without guessing which dimension produced which number.

PredictiveScaler.status.breakdown

RecommendationBreakdown records how the number was arrived at, so that a surprising replica count can be explained without re-deriving it.

Field	Type	Required	Description
bindingSignal	string		BindingSignal names the signal that required the most replicas. With several signals this answers "which dimension is driving the size of this workload", which is the first thing anyone asks.
constraint	string		Constraint names the binding constraint, if any: one of "MinReplicas", "MaxReplicas", "ReactiveFloor", "ForecastUncertainty", "ScaleDownWindow", "MaxScaleUpRate", "MaxScaleDownRate", or "" when the forecast bound.
predictive	integer	yes	Predictive is the replica count implied by the forecast alone.
reactive	integer		Reactive is the replica count the reactive floor would have chosen.

PredictiveScaler.status.conditions

Condition contains details for one aspect of the current state of this API Resource.

Field	Type	Required	Description
lastTransitionTime	string	yes	lastTransitionTime is the last time the condition transitioned from one status to another. This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable.
message	string	yes	message is a human readable message indicating details about the transition. This may be an empty string.
observedGeneration	integer		observedGeneration represents the .metadata.generation that the condition was set based upon. For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date with respect to the current state of the instance.
reason	string	yes	reason contains a programmatic identifier indicating the reason for the condition's last transition. Producers of specific condition types may define expected values and meanings for this field, and whether the values are considered a guaranteed API. The value should be a CamelCase string. This field may not be empty.
status	True | False | Unknown	yes	status of the condition, one of True, False, Unknown.
type	string	yes	type of condition in CamelCase or in foo.example.com/CamelCase.

PredictiveScaler.status.lastForecast

LastForecast describes the binding signal's forecast.

Field	Type	Required	Description
backend	string	yes	Backend that produced it.
generatedAt	string	yes	GeneratedAt is when the forecast was produced.
leadTimeSeconds	integer	yes	LeadTimeSeconds actually used for this forecast.
model	string		Model identifier reported by the backend, if any.
point	string	yes	Point is the point forecast at the lead time.
quantiles	object		Quantiles maps quantile to forecast value at the lead time.
revision	string		Revision of the model weights, when the backend pins one. presage does not vendor weights, so recording which revision produced a forecast is the only way to explain a behaviour change that came from the model rather than from configuration.

PredictiveScaler.status.signalStatuses

SignalStatus is the per-signal view of one evaluation.

Field	Type	Required	Description
forecast	string	yes	Forecast at the lead time, at the target quantile.
gapSteps	integer		GapSteps is how many steps of the query window were gap-filled.
name	string	yes
observed	string	yes	Observed is the latest sampled value.
replicas	integer	yes	Replicas this signal alone would have required.