Auto-stop and wake-up

Auto-stop is an activity-based on/off policy. It moves an Engine between activeReplicas and idleReplicas; it does not add replicas in proportion to query volume.

Configure auto-stop

apiVersion: compute.firebolt.io/v1alpha1
kind: FireboltEngine
metadata:
  name: my-engine
  namespace: firebolt
spec:
  instanceRef: my-instance
  replicas: 2
  autoStop:
    enabled: true
    activeReplicas: 2
    idleReplicas: 0
    idleTimeout: 30m
    pollInterval: 1m
    schedule:
      - start: "08:00"
        end: "18:00"
        days: [Mon, Tue, Wed, Thu, Fri]

Field	Default	Description
`enabled`	`false`	Lets the Firebolt Operator manage `spec.replicas`.
`activeReplicas`	Required when enabled	Replica count while active or scheduled.
`idleReplicas`	`0`	Replica count after the idle timeout. Zero fully stops compute.
`idleTimeout`	`30m`	Quiet period before scale-down.
`pollInterval`	`1m`	Query-activity sampling interval.
`schedule`	Empty	UTC windows that keep the Engine at `activeReplicas`. An end time before the start time crosses midnight.

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

The Firebolt Operator treats running and suspended queries as activity. It does not scale down after a failed metrics scrape because unavailable metrics must not be interpreted as an idle Engine. An active schedule window keeps the Engine at activeReplicas. Outside schedule windows, an Engine scales to idleReplicas after the idle timeout. Inspect the decision and timestamps in Engine status:

Field	Meaning
`status.lastActivityTime`	Most recent observed activity, or the first quiet observation that started the idle timer.
`status.lastScaledAt`	Most recent auto-stop replica change.
`status.autoStopReason`	Current decision, such as `ScheduleActive`, `ActivityObserved`, `Idle`, `ScrapeFailed`, `WakeRequested`, or `Disabled`.

Wake a stopped Engine with the Gateway

With Helm value wakeAgent.enabled=true (the default) and the Firebolt Operator-managed Gateway ServiceAccount, a query sent through the Instance Gateway can wake an Engine at zero replicas:

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.

The first query pays the full Engine cold-start time, which can take tens of seconds when images or volumes must be prepared. Set the client timeout accordingly. 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:

spec:
  replicas: 0
  autoStop:
    enabled: false

Direct connections to the Engine Service cannot wake a stopped Engine because the Service has no endpoints. Route through the Instance Gateway when you rely on wake-up. The Gateway answers its /healthz endpoint itself, before any wake handling, so health checks and uptime monitors pointed at the Gateway never wake a stopped Engine. Set wakeAgent.enabled=false in the Helm values to disable Gateway wake-up. Queries to running Engines are unaffected; a query for a stopped Engine returns 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; annotations on the Firebolt Operator-managed ServiceAccount remain available for workload-identity integrations.

Sampling limitations

Auto-stop samples activity once per pollInterval:

A query shorter than the polling interval might not reset the idle timer.
Scale-down can occur up to one polling interval earlier than the configured idleTimeout.

Choose a shorter polling interval when workloads consist primarily of brief queries, and account for the additional metrics traffic.

Overview

Performance and Observability

Security

Self-Managed

Managed service

Guides

SQL reference

Release notes

API reference

Legal

Configure auto-stop

Scale-down behavior

Wake a stopped Engine with the Gateway

Sampling limitations

​Configure auto-stop

​Scale-down behavior

​Wake a stopped Engine with the Gateway

​Sampling limitations

Configure auto-stop

Scale-down behavior

Wake a stopped Engine with the Gateway

Sampling limitations