# Autoscaling

> Scale replicas up and down based on live CPU and memory. Pay for what you use, not what you provisioned.

**Horizontal autoscaling** adds replicas to your deployment under load and removes them when traffic drops, based on live CPU and memory usage. Turn it on for any web or worker deployment and Ownkube owns the replica count from then on.

Enable it from the deployment **Settings** tab in your [dashboard](https://app.ownkube.io/dashboard).

## How it works

Autoscaling watches your containers' average CPU and memory usage. When usage crosses a target threshold, it adds replicas; when usage drops back below the threshold, it removes them. Scaling reacts within seconds of a sustained change.

### CPU-based

Scale up when average CPU exceeds your target (e.g. 70%).

### Memory-based

Scale up when average memory exceeds your target (e.g. 80%).

You can use one signal, both, or neither. Autoscaling acts on whichever threshold is crossed first.

## What you configure

- **Min replicas**: the floor. Autoscaling won't go below this number.
- **Max replicas**: the ceiling. Capped at **100** per deployment.
- **Target CPU utilization**: percentage of the CPU **request** (e.g. 70 means scale up once containers average 70% CPU).
- **Target memory utilization**: percentage of the memory **request**.

Resource **requests** matter when autoscaling is on. The target utilization is measured against the request, so an honest request gives you honest scaling. Set your request to your app's steady-state floor, not a wishful peak.

## A typical setup

For a web service that sees variable traffic through the day:

| Setting | Value |
|---|---|
| Min replicas | 2 |
| Max replicas | 10 |
| Target CPU utilization | 70% |
| Target memory utilization | 80% |
| CPU request | 250m |
| Memory request | 256Mi |

This keeps at least two replicas always warm, bursts up to ten under load, and scales back down once traffic drops.

## When autoscaling takes over

Once autoscaling is enabled, the **fixed replica count** field is ignored. Autoscaling owns replica count from that point forward. Turn autoscaling off to return to a manual replica count.

Autoscaling is supported on **web** and **worker** deployments. **Jobs** run to completion and don't scale; **databases** have their own scaling model described on the [Databases page](/docs/features/databases).

## Scaling the underlying compute

Replica scaling is only half of it. When your replicas need more room than the cluster currently has, Ownkube scales the **worker capacity** underneath them too, so scaling is end to end.

#### EKS (Production)

Worker capacity scales automatically. If a deployment scales up and the cluster is out of room, Ownkube adds capacity, and reclaims it when your workloads scale back down. There's nothing to configure; it's on by default.

#### K3s (Starter)

Starter runs on a single AWS instance by default. Enable the optional **automatic scaling** add-on when you create the cluster to let a Starter cluster add worker capacity on demand beyond the base instance, and reclaim it when idle. With the add-on off, replica count scales within the capacity of your one instance; if you hit the ceiling, resize to a larger instance type from the cluster detail page. See [Clusters](/docs/features/clusters) for the instance size table.

## The Scaling agent

The **Scaling agent** is Ownkube's predictive layer for capacity. It reads your deployment's infrastructure signals, CPU and memory trends, traffic shape, and past load, and forecasts the capacity your workload is about to need.

The Scaling agent is **advisory**: it predicts and recommends, it does not change your replica count or scaling settings itself. Horizontal autoscaling does the acting. Think of the agent as the forecast and autoscaling as the actuator.

On the Scaling agent's roadmap:

- **Predictive pre-scaling** ahead of historical traffic patterns, so you stop hitting cold-start penalties on the morning rush
- **Schedule-aware** recommendations (e.g. "traffic climbs at 9am on weekdays, drops after 7pm")
- **Custom signals**: forecast on queue depth, request rate, or app-specific metrics
- **Scale-to-zero** guidance for non-production environments during idle periods

## Limits and constraints

- **Max replicas** is capped at **100** per deployment
- **Scale-to-zero** isn't supported yet. Minimum is 1 when autoscaling is on; you can pause a deployment to 0 manually.
- Autoscaling **uses resource requests** as its baseline. Deployments without requests can't autoscale reliably.

- [Deployments](/docs/features/deployments)
- [Cost optimization](/docs/features/cost-optimization)

---

**Don't see a feature you need?** Email [support@ownkube.io](mailto:support@ownkube.io?subject=Feature%20request). Ownkube is shaped by the teams using it and we ship what our users ask for.