> ## Documentation Index
> Fetch the complete documentation index at: https://firebolt-aggregate-helm-docs-pr-79.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Auto-stop and wake-up

> Stop idle Engines and wake them when Gateway traffic arrives.

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

```yaml theme={"theme":{"light":"css-variables","dark":"css-variables"}}
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:

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.

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:

```yaml theme={"theme":{"light":"css-variables","dark":"css-variables"}}
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.