12.2.1.4 Java JVM Memory

Java JVM memory configuration within a container requires particular attention, since the JVM's default memory behavior wasn't originally designed with container resource limits in mind, and a misconfigured JVM can either be needlessly restrictive or, worse, attempt to use more memory than the container's actual limit allows.

Why JVM Memory Defaults Require Specific Attention in Containers

Modern JVM versions are generally container-aware, automatically detecting a container's memory limit and sizing the heap accordingly — but this awareness depends on the JVM version and specific configuration, making explicit verification worthwhile rather than simply assuming correct behavior.

docker run --memory=512m myapp:1.0 java -XX:+PrintFlagsFinal -version | grep MaxHeapSize

Checking the actual heap size the JVM selects, given a specific container memory limit, confirms whether its container-aware sizing is behaving as expected.

Explicitly Setting Heap Size for More Predictable Behavior

Rather than relying entirely on automatic detection, explicitly setting maximum heap size provides more predictable, deliberate control.

CMD ["java", "-Xmx400m", "-jar", "/app/myapp.jar"]

docker run --memory=512m myapp:1.0

Setting an explicit heap maximum somewhat below the container's overall memory limit leaves headroom for the JVM's own non-heap memory usage, reducing the risk of the container being OOM-killed.

Why Heap Size Alone Isn't the JVM's Total Memory Footprint

The JVM uses additional memory beyond the heap — for metaspace, thread stacks, and other internal structures — meaning the container's memory limit needs to account for more than just the configured maximum heap size.

CMD ["java", "-Xmx400m", "-XX:MaxMetaspaceSize=100m", "-jar", "/app/myapp.jar"]

Monitoring Actual Memory Usage to Validate Configuration

Confirming the application's actual memory usage stays comfortably within the container's limit, under realistic load, validates the chosen configuration.

docker stats myapp

Why Java JVM Memory Matters

Deliberately and explicitly configuring JVM memory settings, with awareness of the JVM's total memory footprint beyond just heap size, is an important practice for avoiding both wasted resources and an unexpected out-of-memory container termination.