idleReplicas. When the Engine wakes, it scales back to activeReplicas.
An Engine counts as idle when there is no monitored activity. After a wake, scale-down is blocked for the wake protection period. Auto-stop is not autoscaling: the Engine runs at either idleReplicas or activeReplicas, never anything in between, and query volume doesn’t change the replica count.
Configure auto-stop
You can place the policy on an EngineClass. If an Engine sets
spec.autoStop, the entire Engine policy replaces the class policy. Individual auto-stop fields are not merged.
When auto-stop is enabled, avoid managing spec.replicas with another controller. The Firebolt Operator writes that field to enforce the configured active and idle levels.
Scale-down behavior
Each Engine pod reports how long it has had no auto-stop-eligible work. The Firebolt Operator uses the shortest idle duration across the active generation, so activity on any pod blocks scale-down. It does not scale down after a failed scrape or when the metric is missing or invalid. An active schedule window keeps the Engine atactiveReplicas. Outside schedule windows, an Engine can scale down to idleReplicas once the idle timeout has elapsed and wake protection has expired.
Enabling or re-enabling auto-stop uses the Engine’s existing idle history. If the Engine has already been idle for idleTimeout, the first successful check can scale it down. Enabling auto-stop does not start a fresh timeout.
Inspect the decision and timestamps in Engine status:
Wake a stopped Engine with the Gateway
Gateway wake-up starts a stopped Engine when a query arrives and holds the query while the Engine becomes available. It requires auto-stop to be enabled on the Engine andwakeAgent.enabled=true in the Helm values, which is the default. The Gateway must use the ServiceAccount managed by the Firebolt Operator for permission reasons.
- The Gateway holds the request while the Engine has no ready endpoints.
- The Firebolt Operator sets the Engine to
activeReplicas. - The held request proceeds after Engine endpoints become ready and the Gateway’s Envoy confirms, through a local probe of the Engine’s
/health/ready, that it can route to them.
spec.tls.gateway.clientCASecretRef.
After accepting wake demand, the Firebolt Operator temporarily protects the Engine from idle scale-down so the Gateway can deliver its waiting query. Protection is based on the configured idle timeout and survives Firebolt Operator restarts. Active schedules and activity tracking continue normally during protection.
If the Gateway reaches its held-request capacity, additional requests receive 503 with Retry-After while wake-up continues.
Wake-up applies to any zero-replica Engine with auto-stop enabled, including one whose replica count was set to zero manually. To keep an Engine stopped, disable auto-stop as well:
wakeAgent.enabled=false in the Helm values to disable Gateway-initiated Engine wake-up. Queries to running Engines are unaffected. A query for a stopped Engine returns a HTTP 503.
Setting spec.gateway.template.spec.serviceAccountName also disables wake-on-zero for that Gateway, because the Firebolt Operator does not attach its wake-agent RBAC to a user-managed identity. Leave serviceAccountName unset when wake-on-zero is required.
Poll timing
The Engine retains a monotonic idle duration, so queries that start and finish between checks still reset the idle timer. The Firebolt Operator schedules the next check for the sooner ofpollInterval or the remaining idle timeout, with a one-second minimum delay. Before scaling down, it scrapes again and moves the deadline when newer activity occurred.
A smaller pollInterval detects scrape failures and status changes sooner but does not make the idle deadline more precise.