Skip to main content
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 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:
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.