JVM in Containers: Cgroup Memory Limits and Heap Sizing

For a long time, running Java in a container meant dealing with a painful mismatch. The JVM would report the host’s total memory to Runtime.getRuntime().maxMemory(), not the container’s limit. Deploy a 4GB Java app into a Docker container with a 512MB limit and the JVM would happily try to use far more memory than the container had, leading to OOM kills, eviction, and confusing failures.

This changed starting in Java 10, when the JVM gained awareness of Linux cgroups and began respecting container memory limits. Java 11 and later versions handle this automatically. Understanding how it works helps you avoid the misconfigurations that still catch teams off guard.

This covers how the JVM detects container limits, how to configure heap sizing correctly, and what to watch for in production containerized environments. For broader JVM internals, see JVM architecture overview.

Introduction

Running Java in containers used to mean fighting a fundamental mismatch: the JVM would report the host’s total memory instead of the container’s memory limit, leading to OOM kills that puzzled many teams. Starting with Java 10, the JVM gained awareness of Linux cgroups and began respecting container memory limits automatically. Understanding how this detection works, and where it still catches teams off guard, is essential knowledge for anyone deploying Java applications in Docker or Kubernetes environments.

Container memory limits control how much RAM the kernel will allocate to all processes in a container. When a process tries to allocate beyond the limit, the OOM killer terminates the container — a failure mode that is sudden, confusing, and often misdiagnosed because the heap may appear small from the JVM’s perspective. The JVM needs this limit information to size its heap correctly, and cgroups provide exactly that mechanism on Linux.

This guide covers how the JVM detects container limits through cgroup filesystem reads, how heap sizing defaults work across Java versions, and the practical configurations that keep your containerized Java applications running reliably. You will learn when to rely on automatic detection and when to set explicit heap sizing, how to account for off-heap memory consumption, and how to diagnose the OOM kills that still catch teams despite improved JVM container awareness.

How Cgroups Work with Memory

Linux cgroups (control groups) are the mechanism by which the kernel limits and accounts for resource usage of processes. Memory cgroups track how much memory a group of processes is using and can enforce hard limits.

graph TD
    A[Container Process<br/>cgroup=/docker/abc123] --> B[memory.max<br/>= 512m]
    A --> C[memory.current<br/>= 300m]
    B --> D[Kernel Memory<br/>Accounting]
    C --> D
    D --> E{JVM Heap<br/>Allocation}
    E -->|Requests 2GB| F[OOM Kill<br/>Triggered]
    E -->|Requests 256MB| G[Success]
    F --> H[Container Killed]
    G --> I[Container Runs]

When a container is created with a memory limit, the kernel tracks memory usage in the container’s cgroup. If processes in that container try to allocate beyond the limit, the kernel either reclaims memory (if swap is available) or triggers an OOM killer for the offending process.

The JVM needs to know about these limits so it can size its heap appropriately. Without cgroup awareness, Runtime.getRuntime().maxMemory() returns the machine’s total RAM, not the container’s.

JVM Cgroup Detection

The JVM detects container limits by reading cgroup filesystem values at startup. This happens automatically in Java 10 and later when running on Linux.

# These are the cgroup files the JVM reads
# Memory limit
cat /sys/fs/cgroup/memory/memory.limit_in_bytes
# Or for cgroup v2
cat /sys/fs/cgroup/memory.max

# Current memory usage
cat /sys/fs/cgroup/memory/memory.usage_in_bytes
# Or for cgroup v2
cat /sys/fs/cgroup/memory.current

The JVM uses these values to set defaults for -Xmx, the maximum heap size. In Java 10-15, the default heap is set to 1/4 of the container memory limit. In Java 16 and later, it became 1/4 of the container limit with a minimum of 16MB and a maximum of 64GB, but these defaults can vary.

You can verify what the JVM sees by checking the diagnostic flags.

# Print effective JVM ergonomics including container detection
java -XX:+PrintFlagsFinal -version 2>&1 | grep -i "container\|heap"

# Run with container awareness tracing
java -Xlog:os+container=info -Xmx512m -jar myapp.jar

If you see UseContainerSupport = true in the output, the JVM is aware of the container limits. If you see ErgelogicHeapSummary events, the JVM is using cgroup limits to size the heap.

Container Memory Flags

Docker and Kubernetes let you set memory limits that the JVM should respect.

# Docker: 512MB container memory limit
docker run -m 512m openjdk:17 java -jar myapp.jar

# Kubernetes: equivalent pod spec
# resources:
#   limits:
#     memory: 512Mi
#   requests:
#     memory: 256Mi

With a 512MB container limit and Java 17, the JVM would set the heap to roughly 128MB by default (1/4 of 512MB). The remaining memory is used for Metaspace, thread stacks, direct buffers, and the JVM’s internal structures.

This automatic behavior is usually correct, but there are edge cases where you need to override it.

When to Use

Container-aware heap sizing works automatically in Java 10 and later, so for most containerized workloads you do not need to do anything. The JVM reads the cgroup limits and sets the heap to 1/4 of the container by default. That is a fine starting point.

Reach for -XX:MaxRAMPercentage when you want predictable heap sizing rather than depending on JVM defaults that vary between Java versions. If you have a multi-version deployment strategy or run across a fleet with different Java versions, explicit percentages keep behavior consistent.

Override the defaults when your application has significant off-heap memory usage. Native buffers, JNI allocations, and memory-mapped files all consume container memory without being counted in the heap. If your application uses 200MB of direct buffers, a 512MB container with a 128MB heap leaves only 384MB for everything else, which may not be enough. In that case, set the heap to something like 1/3 or 1/2 of container memory so combined usage stays within the limit.

Use explicit -Xmx values when you need consistent heap sizing across different container sizes in an autoscaling environment. Auto-sized heaps grow and shrink with container limits, which can lead to the same application behaving differently depending on which pod it lands in.

When NOT to Use

Do not rely on automatic container detection when running Java 8 or earlier. The JVM reports host memory, not container limits, which leads to heap sizes that blow past container limits. Either upgrade to Java 11+ or set -Xmx explicitly.

Do not use the default 1/4 container fraction when you have known off-heap memory pressure. The JVM’s default does not know about your specific buffer allocations, Metaspace growth patterns, or thread count. For a 512MB container with a default 128MB heap and 200MB of direct buffers, you are already over the limit before accounting for anything else.

Do not set container memory limits close to your target heap size. The JVM needs headroom for Metaspace, thread stacks, code cache, and internal structures. A container with a 512MB limit and -Xmx512m will regularly hit its limit and get OOM-killed. Leave at least 50% more container memory than your heap size.

Do not assume container detection works correctly on all Kubernetes distributions and container runtimes. Some older setups expose missing or incorrect cgroup values. Always verify with -Xlog:os+container=info in staging before betting on automatic detection in production.

Off-Heap Memory Considerations

The JVM uses memory beyond the heap for several components. When sizing a container, you must account for all of it.

graph TD
    A[Container Memory Limit<br/>e.g., 512MB] --> B[Metaspace<br/>~50-100MB]
    A --> C[Thread Stacks<br/>~1MB × num_threads]
    A --> D[Code Cache<br/>~50MB]
    A --> E[Direct Buffers<br/>NIO ByteBuffers]
    A --> F[JVM Internal<br/>Structures]
    A --> G[Heap<br/>Remaining]
    G -->|Default 25%| H[~128MB]
    G -->|With -Xmx256m| I[256MB]
    style G color:#000

For a 512MB container running Java 17, after Metaspace, thread stacks, code cache, and direct buffers, the available room for heap is less than the full 512MB. If your container limit is tight, plan for these overhead components.

A common rule of thumb: set the container memory limit to approximately 1.5x to 2x your expected heap size, depending on off-heap usage. A 512MB container might support a 256MB heap comfortably but struggle with a 400MB heap.

Production Failure Scenarios

Failure Scenario	Symptoms	Root Cause	Solution
OOM kill despite small heap	Container killed, exit code 137	JVM using more memory than container limit (Metaspace, buffers)	Reduce heap, increase container limit, or limit off-heap usage
JVM not respecting container limit	maxMemory() returns host RAM	Running Java 8 or older, or JVM flags override detection	Upgrade to Java 11+ or use -XX:+UseContainerSupport
Inconsistent heap across pods	Different pod uses different heap	Auto-scaling creates pods with different limits	Use explicit -Xmx rather than auto-sizing
Swap thrashing	Container slowing dramatically	Container at memory limit, kernel swapping	Set --memory-swap equal to --memory, or add more RAM
Native memory exhaustion	UnsatisfiedLinkError or native OOM	Native allocations not counted in heap	Use -XX:MaxNativeHeapSize or profile with NativeMemoryTracking

Trade-off Analysis

Understanding the tradeoffs helps you decide how to configure containers for Java workloads.

Aspect	Auto Heap Sizing	Explicit -Xmx
Simplicity	Lower configuration burden	More flags to manage
Consistency	Varies with container size	Same across all deployments
Off-heap tolerance	May oversubscribe memory	Tunable for off-heap usage
Multi-version support	Auto-adjusts per pod	May need different values per Java version
Debugging	maxMemory() is informative	May need additional flags to verify

Implementation Snippets

Checking JVM Container Awareness at Runtime

public class ContainerMemoryInfo {

    public static void main(String[] args) {
        Runtime runtime = Runtime.getRuntime();

        long maxMemory = runtime.maxMemory();
        long totalMemory = runtime.totalMemory();
        long freeMemory = runtime.freeMemory();
        long usedMemory = totalMemory - freeMemory;

        System.out.println("Max Memory (JVM sees): " + format(maxMemory));
        System.out.println("Total Memory: " + format(totalMemory));
        System.out.println("Used Memory: " + format(usedMemory));

        // Get container limits from the OS
        System.out.println("Container memory limit: " + getContainerLimit());
        System.out.println("Container memory usage: " + getContainerUsage());

        // Check if container support is enabled
        String support = System.getProperty("jdk.container.support", "unknown");
        System.out.println("Container support: " + support);
    }

    private static String format(long bytes) {
        long mb = bytes / (1024 * 1024);
        return mb + " MB";
    }

    private static long getContainerLimit() {
        try {
            // Try cgroup v2 first
            return Long.parseLong(readFile(
                "/sys/fs/cgroup/memory.max").trim());
        } catch (Exception e1) {
            try {
                // Fall back to cgroup v1
                return Long.parseLong(readFile(
                    "/sys/fs/cgroup/memory/memory.limit_in_bytes").trim());
            } catch (Exception e2) {
                return -1;  // Not in a container or unknown
            }
        }
    }

    private static long getContainerUsage() {
        try {
            return Long.parseLong(readFile(
                "/sys/fs/cgroup/memory.current").trim());
        } catch (Exception e1) {
            try {
                return Long.parseLong(readFile(
                    "/sys/fs/cgroup/memory/memory.usage_in_bytes").trim());
            } catch (Exception e2) {
                return -1;
            }
        }
    }

    private static String readFile(String path) throws Exception {
        return java.nio.file.Files.readString(
            java.nio.file.Paths.get(path));
    }
}

Docker Compose Configuration for Java

# docker-compose.yml
version: "3.8"
services:
  myapp:
    image: openjdk:17-slim
    mem_limit: 512m
    # Alternative: mem_reservation (soft limit)
    mem_reservation: 256m
    environment:
      # Override auto-detection if needed
      - JAVA_OPTS=-XX:MaxRAMPercentage=50.0
    deploy:
      resources:
        limits:
          memory: 512M
        reservations:
          memory: 256M
    command: java -XX:+UseContainerSupport -jar /app/myapp.jar

Kubernetes Pod Spec for Java Application

apiVersion: v1
kind: Pod
metadata:
  name: myapp
spec:
  containers:
    - name: myapp
      image: openjdk:17-slim
      resources:
        limits:
          memory: "512Mi"
          cpu: "500m"
        requests:
          memory: "256Mi"
          cpu: "100m"
      env:
        - name: JAVA_OPTS
          value: "-XX:+UseContainerSupport -XX:MaxRAMPercentage=50.0"
      # Or set explicit heap
      # - name: JAVA_OPTS
      #   value: "-Xmx256m"
      command: ["java", "-jar", "/app/myapp.jar"]

Observability Checklist

When running Java in containers in production, here is what to watch.

• Monitor container memory usage vs container limit (should stay below 90% of limit)
• Track JVM heap usage with jstat -gc or micrometer metrics
• Monitor for exit code 137 (OOM kill) in container logs
• Enable -Xlog:os+container=info in staging to verify container detection
• Use NativeMemoryTracking to profile off-heap usage: -XX:NativeMemoryTracking=summary
• Track Metaspace usage especially after class loading spikes
• Monitor direct buffer usage: java.nio.ByteBuffer allocation counts
• Compare JVM maxMemory() to container limit to verify awareness

Security Notes

Memory limits in containers provide a form of resource isolation, but they are not a security boundary. A container can exhaust the node’s memory if the kernel does not properly enforce cgroup limits across containers. Use proper node resource quotas and Kubernetes resource limits to prevent noisy-neighbor problems.

The -XX:+UseContainerSupport flag (enabled by default in Java 10+) does not require any special permissions. It reads from the cgroup filesystem which is typically world-readable inside a container. There is no security implication to container awareness itself.

Be careful with -XX:MaxRAMPercentage in multi-tenant environments where container sizes vary. An attacker who can control the container size could potentially influence heap sizing in ways that affect application behavior.

Common Pitfalls / Anti-Patterns

Here are the most common mistakes when running Java in containers.

Running Java 8 in a container. Java 8 (prior to update 191) does not have container awareness. It reports the host’s total memory as maxMemory(). If you must run Java 8, either upgrade to a recent enough update or use the -XX:+UseContainerSupport flag if your version supports it.

Ignoring off-heap memory. Setting -Xmx512m on a container with a 512MB limit means the total JVM memory usage can exceed 512MB. Always account for Metaspace, thread stacks, and direct buffers when sizing containers.

Setting memory limits equal to heap size. A common mistake is a container with 512MB limit and -Xmx512m. The JVM needs more memory than just the heap. Leave headroom for the JVM overhead.

Assuming auto-detection works on all container runtimes. Some container runtimes (like older Docker versions or certain Kubernetes configurations) do not expose cgroup limits correctly. Always verify with -Xlog:os+container=info in staging.

Not handling OOM kills. When the container hits its memory limit, the OOM killer terminates the JVM process. If you do not have a process supervisor that restarts the container, your service goes down silently. Set up liveness probes in Kubernetes that detect process exits.

Quick Recap Checklist

Use this checklist when deploying Java applications to containers.

• Verify you are on Java 10 or later for automatic container awareness
• Set container memory limit to at least 1.5x your expected heap size
• Use -XX:MaxRAMPercentage rather than hardcoding -Xmx if you want fraction-based sizing
• Account for Metaspace, thread stacks, and direct buffers in your memory budget
• Enable -Xlog:os+container=info in staging to verify detection
• Monitor container memory usage and track when it approaches the limit
• Handle exit code 137 (OOM kill) with proper restart policies
• Use NativeMemoryTracking if you suspect off-heap memory issues
• Test with the same container limits in staging that you use in production
• Set liveness probes that detect container failures from OOM kills

Interview Questions

Further Reading

• JEP 423: Region-based Memory NIC - Background on container memory awareness in the JVM and how the heap is sized based on cgroup limits.
• JVM Container Awareness Implementation - OpenJDK documentation on how the JVM reads cgroup files and determines container memory limits.
• NativeMemoryTracking: JVM Profiling - Oracle guide to using NativeMemoryTracking to profile off-heap memory usage including Metaspace and code cache.
• cgroup v2 vs cgroup v1 Memory Limits - Linux kernel documentation comparing cgroup v1 and v2 memory controller interfaces that the JVM reads.
• Metaspace and Off-Heap Memory Management - JMX documentation for monitoring Metaspace and off-heap memory consumption in running JVMs.

Conclusion

Container awareness has made running Java in Docker and Kubernetes significantly more manageable. The JVM now reads cgroup limits and sizes the heap automatically, reducing the frequency of OOM kills from memory misconfiguration. The defaults work well for many applications, but you still need to understand how off-heap memory consumption affects total container memory usage.

The most important thing you can do is monitor actual memory usage against container limits in production. Use jstat, container metrics, and JVM diagnostics to verify that the JVM behaves as expected. When the defaults do not fit, -XX:MaxRAMPercentage gives you explicit control over heap sizing as a fraction of container memory.