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

> Scale, stop, resume, and update a Firebolt Engine.

Set `spec.replicas` to choose how many Engine pods serve queries. Replica and pod-shaping changes use the Engine's configured [rollout strategy](./engine-rollouts).

## Scale an Engine

Patch the replica count:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
kubectl patch fireng my-engine -n firebolt \
  --type merge -p '{"spec":{"replicas":2}}'
```

The Firebolt Operator creates the desired generation, waits for it to become ready, switches the Engine Service, and retires the old generation. During a graceful rollout, both generations can exist at the same time. Ensure the cluster has enough CPU, memory, and storage capacity for that overlap.

If auto-stop is enabled, the Firebolt Operator owns `spec.replicas` and may replace manual replica changes with `activeReplicas` or `idleReplicas`. See [Auto-stop and wake-up](./auto-stop-and-wake-up).

## Stop and resume an Engine

Set the replica count to `0` to stop compute without deleting the Engine resource:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
kubectl patch fireng my-engine -n firebolt \
  --type merge -p '{"spec":{"replicas":0}}'
```

The Engine reports phase `stopped` and `Ready=False` with reason `Stopped`. Its query Service has no ready endpoints.

Scale-to-zero retires the previous generation. Persistent volumes belonging to that retired generation are deleted according to the generated StatefulSet retention policy; Engine storage is treated as a regenerable local cache rather than durable object storage.

Resume by setting a positive replica count:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
kubectl patch fireng my-engine -n firebolt \
  --type merge -p '{"spec":{"replicas":2}}'
```

If you use auto-stop and want a query to resume a stopped Engine automatically, send traffic through the Instance Gateway. Direct Engine Service traffic cannot wake an Engine with no endpoints.

## Update an Engine image

Set the `engine` container image on the Engine template for a per-Engine override:

```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
  template:
    spec:
      containers:
        - name: engine
          image: example.com/firebolt/engine:tag
```

The image resolves in this order:

1. `FireboltEngine.spec.template.spec.containers[name="engine"].image`
2. The referenced `FireboltEngineClass` Engine container image
3. The Firebolt Operator default image

Use a class image when several Engines should roll to the same version together. Use the Engine template when one Engine needs a different image.

Image pull policy resolves independently with the same Engine-then-class precedence. Without an explicit policy, mutable `latest`, `dev`, and untagged images use `Always`; other tags use `IfNotPresent`.

## Changes that roll an Engine

Changes that alter the rendered Engine pod or configuration create a generation, including:

* `spec.replicas`
* `spec.template`, including image, resources, scheduling, volumes, sidecars, and init containers
* `spec.storage`
* `spec.customEngineConfig`
* `spec.uiSidecar`
* matching inherited settings changed on the referenced EngineClass
* Instance-wide authentication or Engine TLS configuration used by the Engine

The rollout policy fields `rollout`, `drainCheckEnabled`, and `drainCheckInterval` take effect without changing the pod by themselves. Auto-stop policy changes also take effect without forcing a rollout unless they change `spec.replicas`.

## Monitor progress

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
kubectl get fireng my-engine -n firebolt -w
```

Normal rollout phases are `creating`, `switching`, `draining`, and `cleaning`. Completion is `stable` with `Ready=True`, or `stopped` when the desired replica count is zero.

If progress stops, inspect the Engine and its pods:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
kubectl describe fireng my-engine -n firebolt
kubectl get pods -n firebolt -l firebolt.io/engine=my-engine
```

The Engine `Ready` condition can include warnings emitted for the StatefulSet, such as a failure to create pods with an unavailable ServiceAccount. Pod scheduling and volume-binding failures are normally reported on the affected Pods or PVCs, so inspect those resources as well. See [Troubleshooting](../troubleshooting) for recovery steps.