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

# Session volume autoscaling

> Automatically expand session persistent volumes when disk usage crosses a configurable high watermark on EKS clusters.

Cake Agents can automatically grow each session's persistent volume as it fills up. The control plane periodically reads disk usage for every running session from the kubelet and expands the session's PersistentVolumeClaim when usage crosses a high watermark. Autoscaling is enabled by default in the Helm chart.

## Why autoscaling helps

* Sessions clone large repositories or produce build artifacts that outgrow the initial volume size.
* You want to keep `sessionVolume.initialSize` small and pay only for storage that sessions actually use. See the [Helm values reference](/admin/getting-started-kubernetes#values-reference) for the `sessionVolume` block.

If autoscaling is disabled, sessions keep their initial volume size and can run out of disk space during long or storage-heavy work.

## When to disable autoscaling

Set `diskAutoscale.enabled: false` when your cluster cannot meet the prerequisites below, such as clusters that are not on EKS or that lack kubelet fine-grained authorization.

## Prerequisites

* An EKS cluster with kubelet fine-grained authorization enabled. The control plane reads volume telemetry directly from each node's kubelet, which must accept the control plane's service account token.
* A StorageClass with `allowVolumeExpansion: true` for session volumes. Cake Agents skips expansion when the StorageClass does not allow it.
* `rbac.enabled: true` in the Helm chart. When autoscaling is enabled, the chart adds a ClusterRole that grants the control plane `get` on `nodes/metrics` and `storageclasses`.

## Configure with Helm values

Tune or disable autoscaling through the `diskAutoscale` block:

```yaml theme={null}
diskAutoscale:
  enabled: true
  # How often the control plane checks session volumes (cron syntax).
  cronExpression: '* * * * *'
  # Expand when used bytes exceed this fraction of the volume's current size.
  highWatermarkRatio: 0.9
  # Target size multiplier applied to current usage when expanding.
  scaleFactor: 1.5
  # Smallest amount a volume grows in a single expansion.
  minIncrement: 1Gi
  # Volumes never grow beyond this size.
  maxVolumeSize: 128Gi
```

| Value                | Default     | Description                                                                                          |
| -------------------- | ----------- | ---------------------------------------------------------------------------------------------------- |
| `enabled`            | `true`      | Turns session volume autoscaling on or off.                                                          |
| `cronExpression`     | `* * * * *` | Reconciliation schedule. The default checks every minute.                                            |
| `highWatermarkRatio` | `0.9`       | Usage threshold that triggers expansion. Must be between 0 and 1, exclusive.                         |
| `scaleFactor`        | `1.5`       | Multiplier applied to current usage to compute the new size. Must be greater than 1.                 |
| `minIncrement`       | `1Gi`       | Minimum growth per expansion, as a Kubernetes storage quantity (`Ki`, `Mi`, `Gi`, `Ti`, `Pi`, `Ei`). |
| `maxVolumeSize`      | `128Gi`     | Hard cap on any session volume's size.                                                               |

The chart maps these values to `SESSION_DISK_AUTOSCALE_*` environment variables on the control plane. The control plane validates the configuration at startup and rejects invalid ratios, scale factors, storage quantities, and cron expressions.

## Configure in the UI

You can also manage autoscaling from the organization settings:

1. Go to **Settings → Organization → Data Plane**.
2. In the **Autoscaling** section, toggle **Enabled** on.
3. Adjust the fields:
   * **Starting Volume Size** — the size each new session volume starts at. Whole GiB values only, at least 1 Gi, and no larger than the max volume size. Applies to newly created sessions.
   * **High Watermark Ratio** — usage fraction that triggers expansion. Must be between 0 and 1, exclusive.
   * **Max Volume Size** — hard cap on any session volume's size. Must be at least 1 Gi.
   * **Minimum Increment** — smallest amount a volume grows in a single expansion.
   * **Scale Factor** — multiplier applied to current usage to compute the new size. Must be greater than 1.
4. Select **Save**.

Changes apply only when you save. The form validates all fields together and rejects a starting volume size that exceeds the max volume size. Saved changes take effect on the next scheduled reconciliation run without a control plane restart.

### Settings precedence

* Until you save autoscaling settings in the UI, the control plane uses the Helm values (`diskAutoscale` and `sessionVolume.initialSize`).
* Once saved, UI settings replace the Helm values for the expansion policy and the starting volume size.
* Disabling autoscaling in the UI turns it off even when `diskAutoscale.enabled` is `true` in Helm.
* The reconciliation schedule (`cronExpression`) always comes from Helm.

## How expansion works

On each scheduled run, the control plane:

1. Lists running session pods and collects filesystem telemetry for each session volume from the node's kubelet. Stale or malformed telemetry is rejected and logged, and that volume is skipped for the run.
2. Compares used bytes against the volume's current size. Volumes below `highWatermarkRatio` are left unchanged.
3. Computes the new size as the larger of `current size + minIncrement` and `used bytes × scaleFactor`, capped at `maxVolumeSize`.
4. Patches the PersistentVolumeClaim with the new size. The storage provider then expands the underlying volume.

Volumes already at `maxVolumeSize` are never expanded further. Expansion is one-way: Cake Agents never shrinks a session volume.

## Autoscaling inside sessions

Only files under `/workspace` are persistent in a session. `/workspace` is backed by the session volume and survives restarts. Files anywhere else, such as `/tmp` or `/root`, are ephemeral. The default agent prompt instructs agents to keep important files under `/workspace`.

When autoscaling is enabled, session agents also get a `wait_for_volume_autoscale` tool. If a write to `/workspace` fails because the disk is full, the agent can call this tool to wait for the volume to grow, then retry. The tool:

* Waits up to a configurable timeout (default 300 seconds, maximum 900) and returns as soon as `/workspace` capacity has grown.
* Returns immediately with the reason and suggested next steps when the autoscaler decides not to expand, for example when usage is below the high watermark, the volume is at its maximum size, or the StorageClass does not allow expansion.
* Reports that autoscaling is disabled if it was turned off after the session started.

The tool is only registered in sessions created while autoscaling is enabled.