Skip to content
javahacks.dev
JVM & Performance

MaxRAMPercentage and Container Awareness for the JVM

How the JVM reads container limits: MaxRAMPercentage, InitialRAMPercentage, MinRAMPercentage, availableProcessors and how to confirm what the JVM sees.

6 min read
Summarize in AI
Flat illustration of shipping containers stacked on a ship, with the Docker, OpenJDK and Kubernetes logos.

A container with a 1 GiB memory limit runs a Java service, and the heap never grows past 256 MiB while the other 700 MiB sits idle. Or the opposite: someone sets -Xmx1g on a 1 GiB container, and the kernel kills the process an hour later with exit code 137, because the heap is not the only memory a JVM uses. Both problems come from the same place, how the JVM decides its own size inside a cgroup. This post shows what the JVM sees, what each percentage flag does, how to pick a number, and how to verify it from inside a running container. The examples assume JDK 25 and a Linux container runtime with cgroups v2.

What the JVM sees

Since JDK 10 (and backported to 8u191) the JVM is container aware. It reads the memory and CPU limits from the cgroup filesystem instead of looking at the host. You can prove it with a few lines:

src/main/java/dev/javahacks/jvm/WhatISee.javajava
package dev.javahacks.jvm;

public class WhatISee {

    public static void main(String[] args) {
        Runtime rt = Runtime.getRuntime();
        System.out.println("processors  = " + rt.availableProcessors());
        System.out.println("max heap MiB = " + rt.maxMemory() / (1024 * 1024));
    }
}

Run it in a container capped at 2 CPUs and 1 GiB:

Shell
docker run --rm --cpus=2 --memory=1g -v "$PWD":/work -w /work eclipse-temurin:25-jdk \
  java -XX:+UseG1GC dev/javahacks/jvm/WhatISee.java
Text
processors  = 2
max heap MiB = 256

The JVM saw 2 processors and sized the default maximum heap at 25 percent of the 1024 MiB limit, which is 256 MiB. The default of 25 percent is conservative on purpose: the heap is only a part of the memory a JVM process needs, as explained in JVM memory areas.

The three percentage flags

FlagDefaultWhat it sets
-XX:MaxRAMPercentage25Maximum heap as a share of available memory
-XX:InitialRAMPercentage1.5625Heap size at startup
-XX:MinRAMPercentage50Maximum heap for tiny memory (under about 256 MiB)

The odd one is MinRAMPercentage. Despite the name, it is not a minimum heap. It is the maximum-heap percentage used instead of MaxRAMPercentage when the available memory is very small, because 25 percent of 128 MiB is too little to run anything. Most services never reach that branch.

Set the maximum to 70 and look at the result:

Shell
docker run --rm --memory=1g -v "$PWD":/work -w /work eclipse-temurin:25-jdk \
  java -XX:MaxRAMPercentage=70 dev/javahacks/jvm/WhatISee.java
Text
processors  = 4
max heap MiB = 716

1024 times 0.70 is 716.8, and the JVM reports 716. The processor count is the host's, here 4, because this run passed no --cpus limit.

Why percentages instead of -Xmx

An absolute -Xmx512m is correct for exactly one container size. When the same image runs with a 512 MiB limit in a test namespace and 4 GiB in production, the fixed number is wrong in one of them: too big and the process is killed, or too small and the memory is wasted. A percentage scales with the limit, so one image and one flag work everywhere.

Precedence matters. If -Xmx is present, it wins and the percentage is ignored. A stray -Xmx baked into a base image or in JAVA_TOOL_OPTIONS silently disables your MaxRAMPercentage. Find out which options reached the JVM, as described in [setting JVM options in Docker with JAVA_TOOL_OPTIONS](/library/java-tool-options-docker-set-jvm).

How much to allow

The heap is not the process. A JVM also holds metaspace, thread stacks, code cache, garbage collector structures, direct byte buffers and native libraries. A rough budget for a service with 200 threads:

AreaTypical sizeNotes
Heapwhat you setMax RAM percentage times the limit
Metaspace80 to 200 MiBGrows with classes loaded
Thread stacks200 threads x 1 MiB = 200 MiBVirtual threads cost far less
Code cache48 to 240 MiBBounded by ReservedCodeCacheSize
GC and misc5 to 10 percent of heapLarger for G1 with a huge heap

On a 1 GiB container, 75 percent heap is 768 MiB, which leaves 256 MiB for everything else. With 200 platform threads and a large metaspace that is not enough, and the container is killed by the kernel when the total crosses the limit. The symptom and the evidence trail are in diagnosing a container killed by OOMKilled.

A workable starting point:

  • Limit under 512 MiB: 50 percent, since the fixed overhead is a large share.
  • Limit 1 to 4 GiB: 60 to 70 percent.
  • Limit above 8 GiB: 75 to 80 percent, because the overhead no longer scales with the heap.

These are starting points, not laws. The way to settle it is to run the service under realistic load and read the resident memory against the limit. A detailed method, with measured headroom, is in Java heap size in a container with real numbers.

Where to set it

Choose the place that survives the next person's edit.

DockerfileDockerfile
FROM eclipse-temurin:25-jre
COPY target/app.jar /app/app.jar
ENV JAVA_TOOL_OPTIONS="-XX:MaxRAMPercentage=70 -XX:InitialRAMPercentage=50"
ENTRYPOINT ["java", "-jar", "/app/app.jar"]

In Kubernetes, override it per environment without rebuilding the image:

deployment.yamlYAML
containers:
  - name: shop
    image: registry.example.test/shop:1.4.2
    resources:
      limits:
        memory: 1Gi
        cpu: "2"
    env:
      - name: JAVA_TOOL_OPTIONS
        value: "-XX:MaxRAMPercentage=70"

Setting InitialRAMPercentage close to the maximum, as in the Dockerfile, makes the heap start large and avoids repeated resizing during warmup. The price is that the process commits that memory early, so it fits a service that will use it anyway and not a sidecar.

Checking container support

Do not trust a flag you have not read back. Ask the running JVM:

Shell
java -XX:+PrintFlagsFinal -XX:MaxRAMPercentage=70 -version | grep -E 'MaxRAMPercentage|MaxHeapSize|UseContainerSupport'
Text
   double MaxRAMPercentage = 70.000000                {product} {command line}
    uintx MaxHeapSize      = 751828992                {product} {ergonomic}
     bool UseContainerSupport = true                  {product} {default}

UseContainerSupport is on by default. If a legacy image or a wrapper script turns it off with -XX:-UseContainerSupport, the JVM reads the host's memory and sizes the heap for a machine that you do not have. Inside a running container you can also read the raw limit the JVM reads:

Shell
cat /sys/fs/cgroup/memory.max
Text
1073741824

A value of max means no limit, and the JVM falls back to host memory. The flags and their defaults are documented in the java command reference, including the container support section.

CPU consequences

The CPU limit has an equal effect that people miss. availableProcessors() is derived from --cpus (rounded up), and a great many things size themselves from it: the common fork-join pool, the number of GC threads, the default sizing of parallel streams and many library thread pools. A service allowed 0.5 CPU sees 1 processor. Tune pools deliberately, as in sizing thread pools for CPU and I/O, rather than trusting the derived number. If the derived value is wrong for your workload, -XX:ActiveProcessorCount=4 overrides it.

Where this does not apply

If the limit is an unbounded max, these flags scale with the host instead, which is rarely what you want on a shared node, so set a limit. A JVM running outside a container has the whole machine as its limit, and a plain -Xmx is clearer there. And a workload dominated by off-heap memory, such as a service using large direct buffers or memory-mapped files, needs a lower heap percentage than the table suggests, because the heap is the smaller part of its footprint.

Also inDevOps
Share

Keep reading

Get new posts by email

We send one email when a new post is published. No spam.

Unsubscribe in one click. No spam, ever.