> ## 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.

# Engine rollouts

> Configure Engine rollout strategy, readiness, and query draining.

The Firebolt Operator uses blue-green generations for Engine changes. The active generation continues serving while the desired generation starts, then the Engine Service switches to the ready replacement.

## Choose a rollout strategy

| Strategy   | Behavior                                                                                                             | Use when                                                       |
| ---------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| `graceful` | Switches traffic to the ready generation, waits for old pods to finish queries, then removes them.                   | Query continuity matters. This is the default.                 |
| `recreate` | Switches traffic to the ready generation and removes old pods without waiting for the Firebolt Operator drain check. | Faster cleanup matters more than preserving in-flight queries. |

Configure the strategy on an Engine:

```yaml theme={"theme":{"light":"css-variables","dark":"css-variables"}}
spec:
  rollout: graceful
```

You can also set a default on `FireboltEngineClass.spec.rollout`. An Engine value takes precedence.

## Plan capacity

The old and desired generations coexist during startup and, for graceful rollouts, while queries drain. Plan enough cluster capacity for both generations. A rollout remains in `creating` if the desired pods cannot schedule or become ready; the active generation continues serving.

Persistent volume claims are generation-specific. Ensure the storage provisioner and quota can satisfy the replacement generation before the old generation is removed.

## Readiness and traffic switching

The Engine Service switches only after every desired Engine pod is ready. Readiness includes every sidecar with a readiness probe. Add readiness probes to sidecars that must be available before the pod receives queries; a sidecar without a probe is considered ready as soon as its process starts.

During pod termination, the Engine readiness endpoint stops advertising the pod before its process exits. The Gateway retries requests that reach an Engine already entering shutdown.

## Configure graceful drain checks

During a graceful rollout, the Firebolt Operator waits until old-generation pods report no running or suspended queries. It reads these Engine metrics:

* `firebolt_running_queries`
* `firebolt_suspended_queries`

A pod is drained when their sum is zero.

| Field                     | Default    | Description                                              |
| ------------------------- | ---------- | -------------------------------------------------------- |
| `spec.drainCheckEnabled`  | `true`     | Set to `false` to skip the Firebolt Operator drain gate. |
| `spec.drainCheckInterval` | `5s`       | Interval between drain checks.                           |
| `spec.rollout`            | `graceful` | Set to `recreate` to skip the drain phase.               |

The Engine process still waits for unfinished queries during Kubernetes termination when the Firebolt Operator drain gate is disabled. The Engine pod termination grace period is fixed at 60 seconds, and the Engine reserves the final 5 seconds for shutdown.

## Select the metrics transport

Drain checks and auto-stop use `FireboltInstance.spec.metricScrapeMode`:

* `PodIP` connects directly to each Engine pod and is the default.
* `ApiserverProxy` uses the Kubernetes API server `pods/proxy` endpoint. Enable Helm value `rbac.apiserverProxyGrant=true` for this mode.

If a drain scrape fails or a required metric is missing, the Firebolt Operator keeps the old generation and reports `Ready=False` with reason `DrainCheckFailing`. Fix pod network reachability, metrics availability, or the API-server proxy permission before retrying. To accept interrupted queries and continue immediately, set `spec.rollout: recreate`.