> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ankra.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Cluster Autoscaling

> Automatically scale node groups on Ankra-provisioned Hetzner, OVHcloud, and UpCloud clusters based on pod demand.

Ankra-provisioned clusters (Hetzner, OVHcloud, and UpCloud - both k3s and kubeadm) can automatically scale worker node groups based on pod demand. Ankra runs the upstream [Kubernetes Cluster Autoscaler](https://github.com/kubernetes/autoscaler) inside your cluster and wires it to the Ankra platform, which provisions and removes the actual cloud servers.

When pods are unschedulable because a node group is full, the autoscaler adds nodes (up to the group's **max**). When nodes sit underutilised and their pods fit elsewhere, it drains and removes them (down to the group's **min**), respecting PodDisruptionBudgets throughout.

***

## How it works

Autoscaling is configured per node group with three settings:

| Setting     | Meaning                                                     |
| ----------- | ----------------------------------------------------------- |
| **Enabled** | Whether the autoscaler manages this group's node count      |
| **Min**     | The group never shrinks below this many nodes (minimum `1`) |
| **Max**     | The group never grows beyond this many nodes (up to `100`)  |

Behind the scenes:

1. The **Cluster Autoscaler** runs in your cluster and watches for unschedulable pods and underutilised nodes.
2. It talks to the **Ankra agent** in-cluster (over mutual TLS), which forwards scaling decisions to the Ankra platform.
3. The **platform** creates or drains/deletes the actual cloud servers through the same provisioning pipeline used for manual scaling - every change shows up as an operation and an audit entry attributed to `cluster-autoscaler`.

Scale-down drains nodes before removal and honours PodDisruptionBudgets. Scale-up clones the group's existing worker configuration (instance type, labels, taints).

<Note>
  Enabling autoscaling requires a recent `ankra-agent` (the platform tells you the minimum version if the cluster's agent is too old). The Cluster Autoscaler itself is installed automatically the first time you enable autoscaling on any group - no manual Helm work needed.
</Note>

***

## Enable at cluster creation

In the create wizard for Hetzner, OVHcloud, or UpCloud, toggle **Enable autoscaling** on a node group and set **Min**/**Max**. The node count becomes the group's *initial* count and must lie within the bounds.

Via the API, include an `autoscaling` object per node group:

```json theme={null}
{
  "node_groups": [
    {
      "name": "default",
      "instance_type": "cx33",
      "count": 2,
      "autoscaling": { "enabled": true, "min_count": 1, "max_count": 5 }
    }
  ]
}
```

***

## Enable on an existing cluster

### Via the Platform UI

<Steps>
  <Step title="Open the Nodes settings">
    Go to your cluster's **Settings** > **Nodes**.
  </Step>

  <Step title="Toggle autoscaling on the node group">
    On the node group card, switch **Autoscaling** on and set **Min** and **Max**. The manual node-count stepper becomes read-only ("Managed by autoscaler").
  </Step>

  <Step title="Save">
    Saving persists the bounds and installs the Cluster Autoscaler (plus metrics-server) on first enable.
  </Step>
</Steps>

### Via the CLI

```bash theme={null}
# Show current settings
ankra cluster node-group autoscaling get <cluster_id> <group_name>

# Enable with bounds
ankra cluster node-group autoscaling set <cluster_id> <group_name> \
  --enabled --min 1 --max 5

# Disable (the group keeps its current node count)
ankra cluster node-group autoscaling set <cluster_id> <group_name> --enabled=false
```

The cloud provider is detected automatically from the cluster.

### Via the API

```bash theme={null}
# Read
GET /api/v1/clusters/{provider}/{cluster_id}/node-groups/{group_name}/autoscaling

# Write
PUT /api/v1/clusters/{provider}/{cluster_id}/node-groups/{group_name}/autoscaling
{ "enabled": true, "min_count": 1, "max_count": 5 }
```

***

## Interaction with manual scaling

Per-group manual scaling stays available while autoscaling is enabled, but the requested count is **clamped into `[min, max]`** - you cannot manually push an autoscaled group outside its bounds. The legacy whole-cluster worker scale (`ankra cluster scale`) is refused while any group is autoscaling-enabled, since it removes workers across all groups indiscriminately. To take full manual control again, disable autoscaling first.

New nodes added by the autoscaler carry the group's labels and taints, plus the canonical `ankra.cloud/node-group` label Ankra uses to track group membership.

***

## Behaviour details

* **Scale-down is conservative by default**: a node must be unneeded for \~10 minutes, and scale-down pauses for 10 minutes after any scale-up.
* **Failed provisioning is self-healing**: if a cloud server fails to create or join, the autoscaler is told about the failure and backs off; stuck half-created servers are garbage-collected automatically.
* **Node upgrades and autoscaling do not fight**: a node the autoscaler is draining for removal is skipped by Kubernetes version upgrades.
* **Control planes are never autoscaled** - only worker node groups.

## Limitations (v1)

* **Min must be at least 1.** Scale-to-zero is not supported yet: the autoscaler templates new nodes from a live node of the group.
* While a group has zero *Ready* nodes, scale-up is degraded for the same reason.
* Deleting a node group removes its autoscaling settings with it.

<Tip>
  Operators can globally suspend autoscaler-driven scaling without touching clusters by setting `AUTOSCALER_ENDPOINTS_ENABLED=false` on the platform - the in-cluster autoscaler keeps observing, but its scaling requests are refused until the switch is turned back on.
</Tip>