Scale-to-zero & cold starts

When a knext service is idle, Knative drops it to zero replicas — you pay nothing for traffic you're not serving. The first request after that wakes it through the activator. This page is how that works, and how knext keeps the wake fast.

How it scales to zero

Each service runs behind a queue-proxy that reports concurrency to the Knative Pod Autoscaler (KPA). After the stable window with no requests, the KPA scales the deployment to 0. Incoming requests then route to the shared activator, which buffers the request, triggers a scale-up, and forwards once a pod is ready.

Set it per app

spec.scaling.minScale: 0 enables scale-to-zero; raise it to keep a warm floor for latency-critical services. The operator translates this to KPA annotations on the Knative Service.

Which value is right depends on the workload, not on the app. For a decision guide — when to stay at zero, when to schedule a floor over a known peak, and when a permanent replica is the only honest answer — see Warm floors by workload class.

spec:
  scaling:
    minScale: 0     # idle → zero pods
    maxScale: 20

Every scaling knob on this page — minScale, maxScale, containerConcurrency, poolMax, warmSchedule, scaleDownDelay, targetBurstCapacity, panicWindowPercentage, panicThresholdPercentage — is also settable from your kn-next.config.ts scaling: block, so the app and its autoscaling are configured from one file:

const config: KnativeNextConfig = {
  name: 'acme',
  scaling: {
    minScale: 0,
    maxScale: 20,
    containerConcurrency: 20,
    targetBurstCapacity: -1,
  },
};

Keeping the last pod for a while after traffic stops

scaleDownDelay keeps the last pod routable for a window after the traffic stops, then scales to zero as usual:

spec:
  scaling:
    minScale: 0
    maxScale: 10
    scaleDownDelay: 5m   # a duration: 30s, 5m, 1h

A request inside the window is served by a pod that never went away — measured under 100 ms, against seconds for the same request from zero — and it cannot hit the multi-second stall a request can otherwise suffer when it arrives exactly while a pod is being taken out of rotation. Outside the window nothing changes: the pod goes, and the next request pays a normal cold start.

The cost is one idle pod for the length of the window after every burst, including the database connections that pod holds open. If you have sized maxScale × poolMax against your database's connection budget, this does not raise the peak — but it does keep idle connections occupied for longer, so count them.

New apps are scaffolded with scaleDownDelay: "5m" in their kn-next.config.ts. Delete that line for immediate scale-to-zero; shorten or lengthen it to move the trade. Existing apps are unaffected until you add the field yourself.

The cold-start budget

A cold start is pod scheduling + container start + the server boot + first-request work. Only the last two are knext's to shave; the first two belong to the platform. The boot is where a Next.js app otherwise spends real CPU compiling JavaScript — so knext attacks exactly that by compiling at build time: the default target is a compiled single executable whose whole server bundle is precompiled to bytecode (measured 61 ms median process boot against the Node standalone's 884 ms); on the legacy Node standalone shape, a V8 compile cache baked into the image does the same job — see bytecode caching.

Be clear about where that win lands, though: on a real Knative cluster the pod scheduling and container start dominate the end-to-end budget — measured on the order of ~3.4–3.6 s from zero replicas to first response, comparable across the compiled and Node targets, because the platform overhead swamps the boot delta. The boot optimization is real and cuts the part knext owns, but the largest lever on the total number is the platform tier — keeping a warm window after a burst (below), min-scale, activator capacity, image pre-pull, and probe tuning.

Tuning burst response

Scale-to-zero and warm floors handle traffic you can predict. A burst you did not predict — traffic that jumps from a handful of requests to a spike faster than new pods can be scheduled — is a different problem, and spec.scaling has three knobs for it that work together:

spec:
  scaling:
    maxScale: 10
    containerConcurrency: 20
    poolMax: 5                       # keep maxScale × poolMax within your database's connection budget
    targetBurstCapacity: -1          # keep a request buffer in front of your pods during a scale-up
    panicWindowPercentage: 10        # react to a spike faster than the normal evaluation window
    panicThresholdPercentage: 200    # how far over target traffic has to go before reacting fast

• targetBurstCapacity controls whether a buffer sits in front of your pods while they scale up. Set it to -1 to always keep that buffer in place — the safest setting for a bursty workload, at the cost of a small extra hop on every request. Set it to a specific number of requests to buffer only up to that amount. Leave it unset and the platform default applies.
• panicWindowPercentage and panicThresholdPercentage control how quickly the autoscaler notices a burst and reacts. A smaller panicWindowPercentage (as low as 1) makes it look at a shorter, more recent slice of traffic; a lower panicThresholdPercentage (as low as 110) makes it react to a smaller overshoot above your target. Leave either unset and the platform default applies.