Configuration reference

Caution

⚠ Provisional - pending finalization. The values below are accurate for the current 0.1.x chart and operator, but the final flag set, names, and defaults are being settled alongside the licensing and run-mode work in a later release. Treat this as a working reference, not a frozen contract. Once the final flags land, this section will be promoted to stable and the provisional marker removed.

Every Helm value maps to an environment variable on the operator container (set by the chart’s Deployment template). You normally configure via Helm values; the env column is useful for local runs and for understanding the pod spec.

4.1 Scope and scheduling

Helm value	Env var	Default	Meaning
watchNamespaces	STEPSCALE_WATCH_NAMESPACES	"" (all)	Comma-separated namespaces to watch. Empty watches all namespaces. Example: prod,api.
intervalSeconds	STEPSCALE_INTERVAL_SECONDS	300	Seconds between reconcile ticks. Also drives the leader-lease duration (3× this value).
replicaCount	-	1	Operator replicas. 2+ is safe with leader election (only the leader mutates).

4.2 Metrics

Helm value	Env var	Default	Meaning
metrics.prometheusUrl	STEPSCALE_PROMETHEUS_URL	""	Prometheus base URL. Set it for real history backfill; empty falls back to slow HPA-status accumulation. Example: http://prometheus.monitoring.svc:9090.
metrics.windowDays	STEPSCALE_METRICS_WINDOW_DAYS	14	Days of history to backfill per workload from Prometheus.
metrics.stepSeconds	STEPSCALE_METRICS_STEP_SECONDS	300	Sampling step (seconds) for Prometheus history queries.
metrics.promqlCpu	STEPSCALE_PROMQL_CPU	(built-in)	PromQL override for CPU utilization. Supports {ns} / {deploy} placeholders. Defaults to a kube-state-metrics + cAdvisor query.
metrics.promqlReplicas	STEPSCALE_PROMQL_REPLICAS	(built-in)	PromQL override for replica count.
metrics.promqlQueue	STEPSCALE_PROMQL_QUEUE	(built-in)	PromQL override for queue depth (queue-based workloads).

4.3 Safety (probation and rollback)

Helm value	Env var	Default	Meaning
safety.probationWindowMinutes	STEPSCALE_PROBATION_WINDOW_MINUTES	45	Minutes an applied change stays on probation before the verify pass judges its health. Clamped to a minimum of 1.
safety.rollbackEnabled	STEPSCALE_ROLLBACK_ENABLED	true	Auto-revert a probationary change when health degrades. When false, a degraded change is held in degraded for re-judgement instead of reverted.
safety.healthCpuMargin	STEPSCALE_HEALTH_CPU_MARGIN	0.15	Headroom over the target CPU fraction tolerated before a change is judged degraded.

4.4 Leader election (high availability)

Helm value	Env var	Default	Meaning
leaderElection.enabled	STEPSCALE_ENABLE_LEADER_ELECTION	true	Elect a single leader so replicaCount: 2+ never double-applies; only the leader mutates.
leaderElection.leaseName	STEPSCALE_LEASE_NAME	stepscale-autoscaler-leader	Name of the coordination.k8s.io Lease.
leaderElection.leaseNamespace	STEPSCALE_LEASE_NAMESPACE	"" (release ns)	Namespace for the Lease; empty uses the operator’s own namespace.

4.5 Predictive forecasting

Off by default. Requires Prometheus history and a genuinely periodic workload; flat or random workloads are left reactive.

Helm value	Env var	Default	Meaning
forecasting.enabled	STEPSCALE_ENABLE_FORECASTING	false	Forecast recurring peaks and pre-scale the floor ahead of them.
forecasting.minHistoryDays	STEPSCALE_FORECAST_MIN_HISTORY_DAYS	14	Minimum days of history before a forecast is attempted (needs ≥ 2 weekly cycles).
forecasting.binMinutes	STEPSCALE_FORECAST_BIN_MINUTES	60	Seasonal grid bin size in minutes (168 hourly bins per week by default).
forecasting.quantile	STEPSCALE_FORECAST_QUANTILE	0.95	Quantile of per-bin demand used for the forecast (safety headroom). Clamped to [0, 1].
forecasting.periodicityThreshold	STEPSCALE_PERIODICITY_THRESHOLD	0.3	Minimum lag-24h/7d autocorrelation for a workload to count as periodic.
forecasting.prescaleLeadMinutes	STEPSCALE_PRESCALE_LEAD_MINUTES	10	Minutes of head start to raise the floor before each forecasted peak.

4.6 LLM provider (bring-your-own key)

Helm value	Env var	Default	Meaning
llm.provider	STEPSCALE_LLM_PROVIDER	openai	openai, anthropic, or none (deterministic rules-only).
llm.model	STEPSCALE_LLM_MODEL	gpt-4o-mini	Model name passed to the provider.
llm.apiKey	OPENAI_API_KEY (see note)	""	Your API key. Setting it makes the chart create a Secret.
llm.existingSecret	-	""	Name of an existing Secret holding the key under apiKey, used instead of llm.apiKey.

Note

Note. The chart injects the key as the OPENAI_API_KEY environment variable sourced from the Secret key apiKey, for both providers; the operator reads either OPENAI_API_KEY or ANTHROPIC_API_KEY. (bedrock is planned but not yet wired.)

4.7 Licensing

See Licensing for the model and lifecycle. Values:

Helm value	Env var	Default	Meaning
license.publicKey	STEPSCALE_LICENSE_PUBKEY	""	base64-encoded 32-byte ed25519 public key that verifies the license offline. Required to apply.
license.payload	(via Secret)	""	The license JSON payload. Setting it (with signature) makes the chart create the license Secret.
license.signature	(via Secret)	""	The detached ed25519 signature for the payload.
license.existingSecret	STEPSCALE_LICENSE_SECRET (derived)	""	Name of an existing Secret holding license + signature keys.
license.gracePeriodDays	STEPSCALE_LICENSE_GRACE_DAYS	14	Days past expiry to keep applying before degrading.

4.8 Resources and service account

Helm value	Default	Meaning
image.repository	ghcr.io/stepscale/stepscale-autoscaler	Image repository (override for a mirrored registry).
image.tag	"" (chart appVersion)	Image tag.
image.pullPolicy	IfNotPresent	Image pull policy.
serviceAccount.name	stepscale-autoscaler	Service account the operator runs as.
resources.requests	cpu: 50m, memory: 64Mi	Resource requests.
resources.limits	cpu: 250m, memory: 128Mi	Resource limits.

4.9 Run modes (provisional)

A dedicated recommend-only flag is part of the run-mode work being finalized in a later release. Today, to run the operator as a pure advisor, either omit the license (the operator then runs analysis-only and will not apply) or simply never approve recommendations. See Operating §7.4 for current run-mode guidance.