Modified understanding how to override JVM max heap size section

Author: subhtk

modules/nodes-cluster-resource-configure-jdk.adoc

@@ -29,29 +29,25 @@ this documentation, and may involve setting multiple additional JVM options.
 == Understanding how to override the JVM maximum heap size
 
 For many Java workloads, the JVM heap is the largest single consumer of memory.
-Currently, the OpenJDK defaults to allowing up to 1/4 (1/`-XX:MaxRAMFraction`)
-of the compute node's memory to be used for the heap, regardless of whether the
-OpenJDK is running in a container or not. It is therefore *essential* to
-override this behavior, especially if a container memory limit is also set.
-
-There are at least two ways the above can be achieved:
 
-* If the container memory limit is set and the experimental options are
-   supported by the JVM, set `-XX:+UnlockExperimentalVMOptions
-   -XX:+UseCGroupMemoryLimitForHeap`.
+Currently, on bare metal or VM setups, the OpenJDK's default heap value is 25%, 1/4th of the compute node’s memory. However, within containers using cgroups detection (v1 and v2 for JDK 11/17), Xmx was set as 50% of the max memory resource limits by default. In ubi9 - RHEL 9 images, the default allocation is 80%(set via -XX:MaxRAMPercentage), leaving 20% for native use. It is therefore *essential* to
+override this behavior, especially if a container memory limit is also set.
 +
-[NOTE]
+[IMPORTANT]
 ====
-The `UseCGroupMemoryLimitForHeap` option has been removed in JDK 11. Use `-XX:+UseContainerSupport` instead.
+The `UseContainerSupport` flag is on by default in the JVM. It helps the JVM recognize Docker container operations, automatically fetching container-specific details like CPU count and total memory. Therefore, it is not necessary to manually define `JAVA_MAX_INITIAL_MEM`, as the JVM obtains maximum memory allocation from the pods directly.
 ====
-+
-This sets `-XX:MaxRAM` to the container memory limit, and the maximum heap size
-(`-XX:MaxHeapSize` / `-Xmx`) to 1/`-XX:MaxRAMFraction` (1/4 by default).
 
-* Directly override one of `-XX:MaxRAM`, `-XX:MaxHeapSize` or `-Xmx`.
+To acheive this, directly override one of `-XX:MaxRAM`, `-XX:MaxHeapSize` or `MaxRAMPercentage`.
++
+This option involves hard-coding a value, but has the advantage of allowing a safety margin to be calculated.
 +
-This option involves hard-coding a value, but has the advantage of allowing a
-safety margin to be calculated.
+[IMPORTANT]
+----
+Prior to JDK17, note that `MaxRAMPercentage` used `MaxRAM`, instead of system memory. The default maximum value for `MaxRAM` is set to 128g. This means that in a container with a 200g memory limit, using `-XX:MaxRAMPercentage=50` will result in a 64g maximum heap, not 100g.
+
+To address this issue in environments with more than 128g of available memory, a workaround is to explicitly set `MaxRAM` to a higher value. For instance, using `-XX:MaxRAMPercentage=50` `-XX:MaxRAM=200g` would result in a 100g maximum heap within a container with a 200g memory limit.
+----
 
 [id="nodes-cluster-resource-configure-jdk-unused_{context}"]
 == Understanding how to encourage the JVM to release unused memory to the operating system