docs(postgresql): solution for Bus error (exit 135) on hugepage-enabled nodes

[SuJinpei]

Adds a Troubleshooting solution for PostgreSQL dying with Bus error / exit 135 on nodes where hugepages are enabled.

Why

Reported from a customer environment (Harbor's PostgreSQL crash-looping after vm.nr_hugepages was set for a business workload). The failure is not PostgreSQL-specific and not NUMA-specific: on any node with a hugepage pool, kubelet writes hugetlb.<size>.limit_in_bytes = 0 on the pod slice of every pod that does not request hugepages. Reservation is global so mmap(MAP_HUGETLB) succeeds; the limit is charged at page-fault time, where a refusal has no errno and the kernel sends SIGBUS. PostgreSQL's default huge_pages=try only falls back when mmap itself fails, so it dies.

The single most useful thing in here: the cgroup counters visible inside the pod cannot show this. The container scope reads unlimited with failcnt stuck at 0 while the parent pod slice refuses every charge. Reading the wrong level is what sent the original investigation down a false path for days.

Validation

Reproduced and every remedy run end-to-end on ACP 4.2 / k8s 1.33.7 / containerd 1.7.29 / cgroup v1, on a single-NUMA node with no CPU pinning — vm.nr_hugepages=512 alone is sufficient to break every PostgreSQL bootstrap on the node. Covered both the CloudNativePG operator (v1.29.1-acp.1, PG 18.4) and the Zalando operator (spilo v4.3.0-beta.36, PG 13-17).

Measured, not inferred:

• pod slice limit=0, failcnt 0 → 25 across one failing initdb; container scope unlimited, 0 → 0
• the huge_pages GUC alone does not fix a fresh bootstrap (the operator writes postgresql.conf after initdb) — a cluster with only that setting still crash-loops
• initdb -c huge_pages=off works on PG 16/17/18 and does not exist on 13/15
• requesting hugepages-2Mi works and PostgreSQL genuinely consumes the pages
• the same default shared_buffers reports 75 pages on a 2 MiB-page node and 1 on a 512 MiB-page node — the sizing value is a page count, not a size

Test environment fully restored afterwards (pool back to 0, kubelet restarted, allocatable back to its original value).

Review

Ran the three-pass protocol before opening this:

• Static (shell/YAML semantics) — caught a $(… | tr) that swallowed kubectl failure into an empty UID with exit status 0.
• Independent domain cold-read — caught that shared_memory_size_in_huge_pages does not exist before PG 15 while the version table routed PG 13/14 readers straight at it.
• Self-test of every recommended command — caught that the sizing command cannot run as written (needs -D/PGDATA, and has no pre-bootstrap form) and the page-count/page-size unit trap above.

The two review modalities caught disjoint defect classes; both independently found the bootstrap.initdb.options caution listed 5 discarded fields when it discards 10.

One reviewer recommendation was not taken: for a CloudNativePG bootstrap that has already exhausted its Job backoff, the suggested "delete the failed Job" does not recover the cluster. Testing showed patching does nothing, deleting the Job does nothing, and deleting the dangling PVC is actively harmful (it trips a second unrecoverable branch advising restore-from-backup). The documented recovery is delete-and-recreate the Cluster with the fix in the spec, which is safe only because bootstrap never completed.

Notes for reviewers

• EN only — docs/zh/ is generated by the translation pipeline.
• No id: field, so CI's add_id.sh assigns one from the H1 title. Please keep the title stable.
• Version-specific claims are scoped to what was tested; the cgroup layout is explicitly scoped to the systemd cgroup driver, with the cgroupfs shape given as an alternative.

🤖 Generated with Claude Code