Document heap vs memory request relationship in config comments (#60248)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: heiskr

config/kubernetes/default/deployments/webapp.yaml

@@ -25,6 +25,9 @@ spec:
             requests:
               cpu: 1000m
               memory: 4500Mi
+              # Keep ~600 MB headroom above --max-old-space-size in
+              # config/moda/configuration/default/env.yaml for Node
+              # off-heap memory and OS overhead.
             limits:
               cpu: 8000m
               memory: 16Gi

config/kubernetes/production/deployments/webapp.yaml

@@ -34,6 +34,9 @@ spec:
               # Absolute minimum to start app is 4500Mi
               # Would increase with more pages, versions, or languages supported
               # The additional memory helps during traffic surges
+              # Keep ~600 MB headroom above --max-old-space-size in
+              # config/moda/configuration/production/env.yaml for Node
+              # off-heap memory and OS overhead.
             limits:
               cpu: 16000m
               memory: 16Gi

config/moda/configuration/default/env.yaml

@@ -1,6 +1,12 @@
 data:
   MODA_APP_NAME: docs-internal
   NODE_ENV: production
+  # V8 heap limit (--max-old-space-size) should leave at least ~600 MiB
+  # below the K8s memory request for Node off-heap memory (Buffers,
+  # V8 code cache, libuv) and OS overhead. If you change the memory
+  # request in config/kubernetes/default/deployments/webapp.yaml,
+  # update this value to match.
+  # Current: 4500 MiB request, 4096 MiB heap = 404 MiB headroom
   NODE_OPTIONS: '--max-old-space-size=4096'
   PORT: '4000'
   ENABLED_LANGUAGES: 'en,es,ja,pt,zh,ru,fr,ko,de'

config/moda/configuration/production/env.yaml

@@ -1,6 +1,12 @@
 data:
   MODA_APP_NAME: docs-internal
   NODE_ENV: production
+  # V8 heap limit (--max-old-space-size) should leave at least ~600 MiB
+  # below the K8s memory request for Node off-heap memory (Buffers,
+  # V8 code cache, libuv) and OS overhead. If you change the memory
+  # request in config/kubernetes/production/deployments/webapp.yaml,
+  # update this value to match.
+  # Current: 8.0 Gi (8192 MiB) request, 7168 MiB heap = 1024 MiB headroom
   NODE_OPTIONS: '--max-old-space-size=7168'
   PORT: '4000'
   ENABLED_LANGUAGES: 'en,es,ja,pt,zh,ru,fr,ko,de'