Skip to main content
Auto-stop stops an Engine after a period of inactivity and starts it again when a query arrives at the Gateway or a schedule window opens. By default, a stopped Engine runs zero replicas. To keep a smaller number of replicas running while idle, set 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 at activeReplicas. 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 and wakeAgent.enabled=true in the Helm values, which is the default. The Gateway must use the ServiceAccount managed by the Firebolt Operator for permission reasons.
  1. The Gateway holds the request while the Engine has no ready endpoints.
  2. The Firebolt Operator sets the Engine to activeReplicas.
  3. 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.
Wake-up happens before authentication. Engines validate credentials and the Gateway forwards requests without checking them, so any request that reaches the Gateway and names a stopped Engine starts it, including a request the Engine then rejects. The request returns no data, but the Engine runs until it is idle again. Limit who can reach the Gateway with a NetworkPolicy, or require client certificates with 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 an Engine takes longer than expected to become available, wake protection can expire before the Gateway delivers a waiting query. Idle scale-down can then race with query delivery, causing the query to fail.
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:
Wake-up works only for queries sent through the Instance Gateway. Traffic that bypasses the Gateway is unsupported and cannot wake a stopped Engine because the Engine Service has no endpoints. Set 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 of pollInterval 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.