New production platforms fail KSail's config check: no server left for the snapshot build #267

🤖 Generated by the Agentic Engineer (interactive Claude Code session)

What is wrong

KSail rejects the template's production cluster settings before it does anything, so a platform created from the template with its default node counts cannot create or update its production cluster. The settings use every Hetzner server the cluster may own and leave none for the temporary server KSail starts to build the Talos snapshot that nodes boot from.

Evidence (2026-10-25, main at 679fe8b)

Loaded ksail.prod.yaml through KSail's own configuration loader at v7.202.70, the version every template workflow pins (the same loader ksail cluster create and ksail cluster update use). It fails with:

autoscaler configuration leaves no Hetzner server slot for the Talos snapshot build: reachableTotal(10) leaves no slot free of serverLimit(10); keep it at or below 9 (serverLimit minus 1 reserved for the snapshot build's temporary server), or raise serverLimit: controlPlanes(3)+workers(4)+poolCapacity(3), maxNodesTotal(10)

• 3 control planes + 4 static workers + 3 autoscaler slots (pools capped at 1 + 2) = 10, and maxNodesTotal: 10 allows all of them, which equals the default server limit of 10.
• Lowering maxNodesTotal to 9 makes the same load pass. Nothing else changes.
• ksail workload validate, which the template's own CI runs, does not run this check, so the template's checks stay green.
• docs/node-autoscaling.md still describes 3 static workers and a total of 10. The config moved to 4 workers without the total moving.

Who it affects

Anyone creating a production platform from the template, and any platform that kept these default counts, whose production deploys run ksail cluster update.

Proposed direction

Set maxNodesTotal: 9 in ksail.prod.yaml, keeping the 4 static workers and allowing up to 2 autoscaled nodes. Update the autoscaling guide to the real counts and explain the reserved snapshot-build slot. ksail.prod.yaml belongs to each platform once it is created, so existing platforms need the same one-line edit.

Acceptance criteria

• ksail.prod.yaml loads through KSail's validated loader at the pinned version with no error.
• The autoscaling guide matches the configured counts and explains the free slot.

Size

XS.