Auto-Scaling

Automatically scale your services horizontally based on CPU and memory usage. The platform monitors container metrics in real time and adds or removes replicas to match demand — including scaling all the way down to zero when idle.

Overview

Auto-scaling is a per-service feature that horizontally scales your containers based on resource utilisation. When load increases, the platform spins up additional Docker containers behind the same Traefik router, distributing traffic automatically. When load decreases, excess containers are gracefully removed.

Metric-Driven

Scaling decisions are based on real CPU and memory usage, sampled every 10 seconds from running containers.

Automatic Load Balancing

All replicas share the same Traefik router and are balanced automatically — no additional configuration required.

Scale-to-Zero

Services with min replicas set to 0 can shut down entirely when idle, saving resources until a request wakes them.

Up to 10 Replicas

Scale from zero to ten containers per service, with configurable thresholds and cooldown periods.

Configuration

Auto-scaling is configured per service in the service settings panel. Toggle it on, then adjust the parameters to match your workload.

Replica Limits

minReplicas

Minimum number of running containers. Set to 0 to enable scale-to-zero, or 1 to keep at least one container always running.

Range: 0–10 · Default: 1

maxReplicas

Maximum number of containers the autoscaler will create. The service will never exceed this count regardless of load.

Range: 1–10 · Default: 3

Thresholds

cpuThreshold

Average CPU utilisation across all replicas that triggers a scaling action.

Default: 70%

memThreshold

Average memory utilisation across all replicas that triggers a scaling action.

Default: 80%

Timing

scaleUpDelay

How long metrics must remain above the threshold before adding a replica. Prevents scaling on brief spikes.

Default: 30s

scaleDownDelay

How long metrics must remain below the threshold before removing a replica. A longer delay avoids flapping under variable load.

Default: 120s

cooldown

Minimum time between consecutive scaling actions. This ensures the previous scale event has time to take effect before another is triggered.

Default: 60s

idleTimeout

Time with no incoming requests before a scale-to-zero service is put to sleep. Only applies when minReplicas is 0.

Default: 15 minutes

How It Works

The autoscaler runs a continuous loop that evaluates your service every 10 seconds:

Collect metrics— The autoscaler reads CPU and memory utilisation from every running container for the service via the Docker stats API.
Calculate averages— CPU and memory percentages are averaged across all current replicas.
Evaluate thresholds— If either average exceeds its configured threshold for the duration of the scale-up delay, a scale-up is triggered. If both are below threshold for the scale-down delay, a scale-down is triggered.
Check cooldown— If a scaling action occurred within the cooldown window, the action is deferred until the window expires.
Scale— A new Docker container is created (scale up) or an existing one is gracefully stopped (scale down). All containers are registered under the same Traefik service router, so traffic is automatically load-balanced across replicas.

Note:Each new replica is an identical Docker container with the same image, environment variables, and network configuration. Containers share the service's Traefik labels, meaning Traefik discovers them automatically and distributes incoming requests across all healthy replicas.

Scale-to-Zero

When minReplicas is set to 0, the service can be fully stopped when idle. This is ideal for staging environments, internal tools, or low-traffic services where you want to reclaim resources when they are not in use.

How sleep and wake works

After no requests are received for the idle timeout period (default 15 minutes), all containers are stopped and the service enters the sleeping state.
A lightweight wake proxy takes over the service's Traefik route. It listens for incoming requests while the service is asleep.
When a request arrives, the wake proxy holds the connection and immediately starts a container.
Once the container is healthy and accepting connections, the proxy forwards the held request and removes itself from the routing chain.

Cold start latency:The first request to a sleeping service will experience a delay while the container starts. Typical cold start times are 1–5 seconds depending on image size and application startup time. Subsequent requests are served normally.

Status Indicators

The dashboard and API expose a scaling status for each service. The status reflects the current state of the autoscaler:

stable

The service is running within its configured thresholds. No scaling action is pending.

scaling-up

Metrics have exceeded the threshold for the required delay period. A new replica is being created.

scaling-down

Metrics have been below the threshold for the required delay period. A replica is being removed.

sleeping

All containers are stopped (scale-to-zero). The wake proxy is listening for incoming requests.

API

Auto-scaling can be configured and queried programmatically. All endpoints require a valid API key passed via the Authorization: Bearer <token> header.

GET/api/projects/{id}/services/{serviceId}/scale

Get scaling configuration and status

Returns the current auto-scaling configuration, number of running replicas, and scaling status for the service.

Example request

bash

curl -H "Authorization: Bearer $API_KEY" \
  https://system.rouic.com/api/projects/proj_abc123/services/svc_xyz789/scale

Example response

json

{
  "enabled": true,
  "minReplicas": 1,
  "maxReplicas": 5,
  "currentReplicas": 2,
  "cpuThreshold": 70,
  "memThreshold": 80,
  "scaleUpDelay": 30,
  "scaleDownDelay": 120,
  "cooldown": 60,
  "idleTimeout": 900,
  "status": "stable",
  "lastScaleEvent": "2026-04-12T14:23:00Z"
}

POST/api/projects/{id}/services/{serviceId}/scale

Update scaling configuration

Update one or more auto-scaling parameters. Any fields not included in the request body are left unchanged.

Example request

bash

curl -X POST -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "minReplicas": 0,
    "maxReplicas": 8,
    "cpuThreshold": 60,
    "memThreshold": 75,
    "idleTimeout": 600
  }' \
  https://system.rouic.com/api/projects/proj_abc123/services/svc_xyz789/scale

Example response

json

{
  "enabled": true,
  "minReplicas": 0,
  "maxReplicas": 8,
  "currentReplicas": 1,
  "cpuThreshold": 60,
  "memThreshold": 75,
  "scaleUpDelay": 30,
  "scaleDownDelay": 120,
  "cooldown": 60,
  "idleTimeout": 600,
  "status": "stable",
  "lastScaleEvent": "2026-04-12T14:23:00Z"
}

Example Configurations

Here are recommended configurations for common workload patterns.

Production Web Application

Always-on with headroom for traffic spikes

{
  "enabled": true,
  "minReplicas": 2,
  "maxReplicas": 8,
  "cpuThreshold": 70,
  "memThreshold": 80,
  "scaleUpDelay": 30,
  "scaleDownDelay": 120,
  "cooldown": 60
}

Keeps at least 2 replicas running for redundancy. Scales up quickly (30s) to absorb traffic spikes and scales down conservatively (120s) to avoid flapping.

Staging / Preview Environment

Scale-to-zero when not in use

{
  "enabled": true,
  "minReplicas": 0,
  "maxReplicas": 2,
  "cpuThreshold": 70,
  "memThreshold": 80,
  "scaleUpDelay": 15,
  "scaleDownDelay": 60,
  "cooldown": 30,
  "idleTimeout": 900
}

Sleeps after 15 minutes of inactivity. Fast scale-up delay (15s) since staging does not need spike protection. Wakes automatically when a developer visits the preview URL.

Background Worker / Queue Consumer

CPU-heavy, scale based on processing load

{
  "enabled": true,
  "minReplicas": 1,
  "maxReplicas": 10,
  "cpuThreshold": 50,
  "memThreshold": 70,
  "scaleUpDelay": 15,
  "scaleDownDelay": 180,
  "cooldown": 30
}

Lower CPU threshold (50%) to scale up sooner as workers process jobs. Higher max replicas and a longer scale-down delay (180s) to avoid killing workers mid-job.

Internal Tool / Admin Panel

Low traffic, save resources when idle

{
  "enabled": true,
  "minReplicas": 0,
  "maxReplicas": 1,
  "cpuThreshold": 80,
  "memThreshold": 85,
  "scaleUpDelay": 30,
  "scaleDownDelay": 60,
  "cooldown": 60,
  "idleTimeout": 600
}

Single container maximum — no horizontal scaling needed. Sleeps after 10 minutes of inactivity and wakes on demand. Ideal for dashboards or tools used a few times per day.

Next up

API Reference →

Object Storage