Skip to content

feat(cluster): bootstrap RAM preflight sets a 2GB minimum with a memory breakdown#215

Merged
incognick merged 1 commit into
mainfrom
feat/ram-preflight-2gb
Jul 4, 2026
Merged

feat(cluster): bootstrap RAM preflight sets a 2GB minimum with a memory breakdown#215
incognick merged 1 commit into
mainfrom
feat/ram-preflight-2gb

Conversation

@incognick

Copy link
Copy Markdown
Contributor

Dogfooding showed 1GB runs the control plane but is exhausted the moment a public site adds the ingress controller and cert-manager (kswapd thrashing, k3s API TLS-handshake timeouts), so the bootstrap RAM preflight now treats 2GB as the honest minimum: it refuses below roughly 2GB unless --yes and prints a breakdown of what uses the memory (k3s, Postgres, burrowd, and the ingress controller plus cert-manager for a public site), noting that 1-2GB is control-plane and internal-only and under 1GB will not start k3s.

Thresholds

  • minBootstrapRAM = 1900 MiB — the 2GB honest minimum (set under a nominal 2GB so a real 2GB box passes once the kernel reserves its share). Below it bootstrap refuses unless --yes; at or above it proceeds silently.
  • k3sMinRAM = 960 MiB — below this k3s itself is unlikely to start; used only to branch the refusal's sub-message.

Message

The refusal (and the --yes warning) leads with the breakdown:

Burrow's minimum is 2GB of RAM. This machine has <N> MiB.
Roughly: k3s ~500MB, Postgres ~150MB, burrowd ~100MB — plus, for a public site,
ingress-nginx ~100MB and cert-manager ~200MB — before any headroom for your app.

then a tier-specific reason:

  • < ~1GiB: "Below ~1GB, k3s itself likely will not start (512MB is known to fail)."
  • 1-2GiB: "1-2GB runs the control plane and internal apps, but a public site (the ingress controller and cert-manager) will exhaust it."

and, when refusing, "Re-run with --yes to bootstrap anyway." With --yes it prints the breakdown + reason and "Proceeding anyway because --yes was set."

The --yes flag, the memory-reader seam, the ordering before confirmBootstrap, and the already-running fast path are all unchanged.

Tests

  • TestBootstrapRefusesSubGiBRAMWithoutYes (was TestBootstrapRefusesUndersizedRAMWithoutYes) — 512 MiB, no --yes: refuses, asserts the 2GB minimum, the breakdown (cert-manager), and the k3s-won't-start reason.
  • TestBootstrapRefusesTightRAMWithoutYes (replaces TestBootstrapWarnsTightRAM) — 1.5 GiB, no --yes: now refuses (was warn-and-proceed), asserts the public-site reason and the breakdown, and that Install never runs.
  • TestBootstrapProceedsUndersizedRAMWithYes — 512 MiB + --yes: proceeds, breakdown still printed.
  • TestBootstrapProceedsTightRAMWithYes (new) — 1.5 GiB + --yes: proceeds, public-site warning + breakdown printed.
  • TestBootstrapComfortableRAMNoWarning (2 GiB) and TestBootstrapSkipsRAMCheckWhenUnreadable unchanged and green; the full-flow tests still use a comfortable 4 GiB reading.

Light gate passes: go build, go vet, gofmt -l (empty), go test ./..., and scripts/check-spdx.sh.

…ry breakdown

Dogfooding showed 1GB runs the control plane but is exhausted the moment a
public site adds the ingress controller and cert-manager (kswapd thrashing,
k3s API TLS-handshake timeouts), so the bootstrap RAM preflight now treats 2GB
as the honest minimum: it refuses below roughly 2GB unless --yes and prints a
breakdown of what uses the memory (k3s, Postgres, burrowd, and the ingress
controller plus cert-manager for a public site), noting that 1-2GB is
control-plane and internal-only and under 1GB will not start k3s.

Signed-off-by: Nicholas Phillips <nsphilli@gmail.com>
@incognick incognick added the pr-ready A PR is open and ready for review label Jul 4, 2026
@incognick incognick enabled auto-merge July 4, 2026 14:35
@incognick incognick added this pull request to the merge queue Jul 4, 2026
Merged via the queue into main with commit 6f0d078 Jul 4, 2026
5 checks passed
@incognick incognick deleted the feat/ram-preflight-2gb branch July 4, 2026 14:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

pr-ready A PR is open and ready for review

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant