Scaling & Autoscaling

Web Applications and Background Workers run as one or more identical instances. You can set the instance count yourself, or turn on CPU autoscaling and let the platform adjust it within a range you choose. This page covers both, plus the CPU and memory settings that apply to each instance.

Databases and Object Storage buckets are not scaled this way: a Database’s instances are managed by the platform, and a bucket has no instances at all.

Scale manually

Scaling needs the deploy permission on the project (see Access Control).

In the dashboard, open the app’s Overview page. The Replicas row shows the current count with + and − buttons next to it. Scaling down to zero stops the app entirely, so the dashboard asks you to confirm first. You can also set the replica count on the app’s Settings tab — that save goes through the same form as CPU and memory, so it needs the manage permission rather than deploy.

With the CLI, use paas scale:

paas scale 3 -o acme -p shop -e production -a web

Scaling to 0 stops the app; scale back up to start it again. Check the running instances with:

paas ps -o acme -p shop -e production -a web

The change rolls out automatically — you do not need to trigger a deployment.

Scaling is checked against your Organization’s plan limits, since each added instance consumes capacity. If a scale request would exceed them, it is rejected with a limit-exceeded error; see Plans, Limits & Usage. An app stopped by the monthly transfer cap can’t be scaled until the allocation is raised or the month rolls over — see Monthly transfer allocation.

Running on more than one server

Run two or more instances (or autoscale) and the platform spreads them evenly across its servers, so a server failure leaves the others serving; maintenance moves one instance at a time. A single-instance app is unavailable while its one instance is moved — run at least two if that matters.

CPU and memory per instance

Every instance of an app runs with the same CPU and memory limits. Set them on the app’s Settings tab in the dashboard (this needs the manage permission):

• CPU Limit — for example 500m (half a CPU core) or 1 (one full core).
• Memory Limit — for example 512Mi or 1Gi.

Saving rolls the change out to all instances automatically. Like replicas, these sizes count against your plan’s capacity, so raising them for a heavily scaled app can hit a limit.

Autoscaling

Instead of picking a fixed count, you can have the platform scale the app on CPU usage. Autoscaling is opt-in and per app, and is available for Web Applications and Background Workers.

On the app’s Overview page, the Autoscaling row shows the current state. Click Enable… and set:

• Min replicas — the count the app never drops below (at least 1).
• Max replicas — the ceiling; must be greater than or equal to the minimum.
• Target CPU % — the average CPU use (1–100) the autoscaler aims for, as a percentage of each instance’s baseline of 0.1 core (100m, or the CPU Limit if that is lower), not of its CPU Limit. For example, 70 adds instances once they average 70m. When instances run hotter than the target, more are added, up to the max; when they run cooler, instances are removed, down to the min.

While autoscaling is on, the Replicas row is marked (managed by autoscaler) and the manual +/− buttons disappear. To see how many instances are actually running, check the running instances (for example with paas ps). Plan limits are enforced against the configured max, since that is the real peak the app can reach.

To go back to a fixed count, click Disable on the Autoscaling row. Your previous min/max/target values are remembered, so re-enabling later does not reset them.

With the CLI, passing any of --autoscaling-min, --autoscaling-max or --autoscaling-cpu-target to paas apps update (or paas apps create) turns autoscaling on; an unset target means 70:

paas apps update web --autoscaling-min 2 --autoscaling-max 6 --autoscaling-cpu-target 70 -o acme -p shop -e production

To turn it off, pass --autoscaling false; the app goes back to its fixed instance count:

paas apps update web --autoscaling false -o acme -p shop -e production

Manual scaling conflicts with autoscaling

While autoscaling is on, the autoscaler owns the replica count — a manual value would just be overwritten. A paas scale (or a scale request from any other client) is therefore rejected with a conflict:

$ paas scale 5 -o acme -p shop -e production -a web
Error: CONFLICT: autoscaling is enabled; disable it to set a fixed replica count

Disable autoscaling first, then scale manually.

Singleton apps

A singleton app runs at most one instance. Deployments and restarts stop the old instance before starting the new one, so expect a few seconds of downtime. Use it for bots and other apps that must never run twice.

Normally a deployment starts the new instance before stopping the old one, so the app stays up throughout — but for a moment two copies run side by side. For most apps that is harmless. For a bot that keeps one live connection per token to a chat service, two copies mean two sessions on the same token: duplicate replies, or the service disconnecting both.

A singleton never overlaps. Every rollout — a deployment, a restart, or a configuration change — stops the old instance first and only then starts the new one. The cost is a gap while the old instance stops and the new one starts, so leave it off for Web Applications that need to stay up through deployments. How long the gap lasts depends on how quickly your app shuts down: the platform sends it SIGTERM and waits for it to exit. An app that exits promptly on SIGTERM is down for a few seconds; one that ignores it is force-stopped after 30 seconds, so its gap is about 30 seconds longer.

Singleton is off by default and available for Web Applications and Background Workers. A singleton app:

• can’t autoscale — turn off autoscaling first (click Disable in the app’s Autoscaling row, or paas apps update <app> --autoscaling false);
• runs at most one instance — the replica count can be 1, or 0 to stop the app. Scaling a singleton above 1 is rejected with a conflict:

$ paas scale 2 -o acme -p shop -e production -a bot
Error: CONFLICT: singleton apps run at most one instance; turn off singleton to scale out

In the dashboard, open the app’s Overview page and tick Run at most one instance in the Singleton row. It applies right away (this needs the manage permission). If the app is autoscaling or running more than one instance, the box stays disabled until you turn off autoscaling or scale down to one.

With the CLI, pass --singleton true to paas apps update (or to paas apps create):

paas apps update bot --singleton true -o acme -p shop -e production

Add --replicas 1 if the app runs more than one instance today. Pass --singleton false to turn it off again; paas apps info shows whether an app is a singleton.

Or set singleton: true in d2o-paas.yaml; the checkbox then shows as set by your code.

Next steps

• Metrics — watch CPU and memory usage to pick sensible limits and targets
• Restarting an App — roll all instances without changing the count
• Plans, Limits & Usage — how scaling counts against your Organization’s capacity