From 7d19d9ee64a053f8062b6703ecf3757f7fb1b28a Mon Sep 17 00:00:00 2001
From: Joao Detomini <joao.detomini@enterprisedb.com>
Date: Thu, 1 Oct 2026 19:14:27 -0300
Subject: [PATCH v1] doc: Document Linux cgroup memory limits

The section on Linux memory overcommit does not cover memory limits
imposed by control groups, which are commonly used for containers.
Such limits are enforced independently of vm.overcommit_memory, and
the OOM killer is invoked within the cgroup instead of allocations
failing.  Document this behavior, its consequences for the postmaster,
and what counts towards the cgroup's memory usage, including the
special case of huge pages.
---
 doc/src/sgml/runtime.sgml | 51 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)

diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index d9984910cc..059b3d3888 100644
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -1438,6 +1438,57 @@ export PG_OOM_ADJUST_VALUE=0
 
   </sect2>
 
+  <sect2 id="linux-memory-cgroups">
+   <title>Linux Control Group Memory Limits</title>
+
+   <indexterm>
+    <primary>control group</primary>
+   </indexterm>
+
+   <indexterm>
+    <primary>cgroup</primary>
+   </indexterm>
+
+   <para>
+    On Linux, the memory used by a group of processes can be limited using
+    control groups (<firstterm>cgroups</firstterm>), a mechanism commonly
+    used to limit the memory of containers.  Such a limit is enforced
+    regardless of the amount of memory available on the host and of
+    host-wide settings such as <varname>vm.overcommit_memory</varname> (see
+    <xref linkend="linux-memory-overcommit"/>).
+   </para>
+
+   <para>
+    With cgroup version 2, the limit is set in the
+    <filename>memory.max</filename> file.  (Version 1 uses different files and
+    is not covered here.)  When memory usage reaches the limit and cannot be
+    reduced by reclaiming memory, the kernel's OOM killer is invoked within
+    the cgroup.  In this case memory allocations usually do not fail with an
+    out-of-memory error; instead, the OOM killer terminates a process of the
+    cgroup.  If that is a server process other than the postmaster, the
+    postmaster treats it as a crash and, unless
+    <xref linkend="guc-restart-after-crash"/> is turned off, restarts all
+    server processes, disconnecting all sessions.  For details see the
+    kernel documentation file
+    <ulink url="https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v2.html"></ulink>.
+   </para>
+
+   <para>
+    The shared memory used by <productname>PostgreSQL</productname>
+    (including the shared buffers) and the private memory of each server
+    process count towards the memory usage of the cgroup.  Therefore,
+    <xref linkend="guc-shared-buffers"/>, plus the memory that concurrent
+    sessions might use (see <xref linkend="guc-work-mem"/>,
+    <xref linkend="guc-hash-mem-multiplier"/>,
+    <xref linkend="guc-maintenance-work-mem"/>, and
+    <xref linkend="guc-max-connections"/>), should be chosen so that the
+    total stays below the limit.  Memory allocated from the huge page pool
+    (see <xref linkend="guc-huge-pages"/>) is by default not counted towards
+    the memory usage of the cgroup.
+   </para>
+
+  </sect2>
+
   <sect2 id="linux-huge-pages">
    <title>Linux Huge Pages</title>
 
-- 
2.50.1 (Apple Git-155)