From 9a9b4ff11a0ab26140114b295d9c8b903688fc55 Mon Sep 17 00:00:00 2001
From: Luca De Petrillo <972242+lukakama@users.noreply.github.com>
Date: Tue, 5 May 2026 16:54:36 +0000
Subject: [PATCH] Added information about container memory limit handling by 
 ballooning.

---
 readme.md | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/readme.md b/readme.md
index a5d258e..c4b586e 100644
--- a/readme.md
+++ b/readme.md
@@ -174,7 +174,7 @@ kubectl apply -f https://raw.githubusercontent.com/dockur/windows/refs/heads/mas
 
   By default, the VM is allocated the full amount of RAM configured via `RAM_SIZE` for its entire lifetime.
 
-  If you want the container to dynamically reclaim unused guest RAM based on host memory pressure, you can enable memory ballooning:
+  If you want the container to dynamically reclaim unused guest RAM based on host memory pressure, you can enable memory ballooning. It is also used to prevent the guest from exceeding the container's memory limit, even when the limit is changed at runtime:
 
   ```yaml
   environment:
@@ -205,6 +205,9 @@ kubectl apply -f https://raw.githubusercontent.com/dockur/windows/refs/heads/mas
 > [!NOTE]
 > Memory ballooning uses Linux PSI (`/proc/pressure/memory`) for progressive pressure detection. Between `BALLOONING_PSI_PRESSURE` and `BALLOONING_PSI_PRESSURE_MAX` the PSI ceiling linearly lowers the maximum balloon target from guest max memory down to the configured minimum. If PSI is unavailable (kernel lacks `CONFIG_PSI`), both thresholds are silently skipped and ballooning continues using host memory usage alone.
 
+> [!WARNING]
+> If the container memory limit is reduced at runtime below the guest VM's current memory usage, the container may be killed by the OOM killer if the ballooning driver cannot reclaim memory from the guest fast enough.
+
 ### How do I configure the username and password?
 
   By default, a user called `Docker` is created and its password is `admin`.