Java rightsizing on Kubernetes means coordinating the JVM heap ceiling, total container memory limit, and scheduler request. Read JVM heap and GC signals alongside container memory usage. A high committed heap is not the same as live application data, and a low used heap does not prove that the whole process can safely fit in a smaller container.
The practical goal is to remove unnecessary reservations while retaining capacity for live heap, allocation bursts, native memory, and workload peaks. Measure a representative cycle, including startup and scheduled jobs, before changing resources.
Key takeaways
- Heap usage, committed heap, resident memory, and container working set measure different things.
- Requests guide scheduling; container limits must cover heap plus non-heap and native memory.
- Coordinate heap flags and container resources in one tested rollout.
- Use representative peaks and GC objectives rather than a universal percentile or headroom ratio.
Why Java workloads defeat normal rightsizing

A container working-set metric is useful across runtimes, but it does not explain the composition of memory usage. Java requires additional heap and GC context; other runtimes also need workload-specific validation rather than a universal percentile rule.
A JVM reserves virtual address space, commits heap capacity, and uses resident physical pages as needed. Garbage collectors differ in whether and when they return memory to the operating system. Collector, JDK version, flags, allocation patterns, and minimum heap settings all matter.
Container memory metrics report the whole process, which is not just the heap. Metaspace, thread stacks, direct buffers, and GC bookkeeping add 100 to 200 MiB on a small service. With 400 threads and a NIO-heavy stack they can exceed 1 GiB.
Keep four quantities separate: -Xmx caps Java heap capacity; committed heap is memory available for JVM allocation; RSS measures resident pages; container working set is a cgroup-derived usage metric. Reserved or committed address space is not automatically resident physical memory, and working set is not a precise measure of unreclaimable bytes.
Why a growing heap looks like a leak when it is not
Used heap includes live objects and garbage awaiting collection. After a collection it can help estimate the live set, but collector behavior and measurement timing matter. Modern collectors can uncommit unused heap under supported conditions; the speed and extent depend on configuration and runtime version.
Setting -Xms equal to -Xmx keeps the minimum heap at its maximum size and limits shrinking. It does not by itself mean every page is resident. -XX:+AlwaysPreTouch touches allocated heap pages during startup, which can increase initial resident memory and startup work.
Metaspace, threads, direct buffers, and the code cache
Metaspace, thread stacks, direct buffers, code cache, GC structures, and native libraries consume memory outside the heap. Stack defaults depend on platform and JVM; reserved stack address space is not equivalent to resident usage. Measure the actual process rather than multiplying thread count by an assumed resident stack size.
None appear in a heap chart. All of them count against the cgroup limit, so a limit sized from heap alone leaves no margin. That is why Java pods OOMKill at comfortable heap utilization.
How should heap and non-heap affect the container’s request and limit?
Three numbers govern Java memory on Kubernetes, and each does a different job. -Xmx caps the heap, the container limit caps the whole process, and the request tells the scheduler what to reserve.
Most teams conflate at least two, usually by setting the limit equal to -Xmx, since that strips the headroom protecting the process.
The three numbers
| Number | What sets it | Too low | Too high | How to derive it |
|---|---|---|---|---|
-Xmx (heap ceiling) | JVM startup flag, or MaxRAMPercentage times the limit | Collector cannot keep up, constant GC thrash, OutOfMemoryError: Java heap space | Heap claims memory the app never uses, inflating committed memory | Live-set trends, allocation bursts, collector behavior, and pause/throughput objectives; correlate with GC logs. Avoid forcing GC in production merely to obtain a sizing sample |
| Container memory limit | resources.limits.memory, enforced by the cgroup | Process exceeds it and gets SIGKILL (exit 137), invisible to the JVM | Allows a larger possible burst; scheduling reservation is primarily driven by the request | Heap ceiling plus measured non-heap/native needs and workload-specific safety headroom |
| Memory request | resources.requests.memory, used by the scheduler | Node overcommits, pods get evicted under pressure | Pods reserve capacity they never use, wasting fleet capacity | Representative whole-container demand with peak, startup, eviction, and QoS requirements considered |
Requests govern scheduling; limits bound container memory consumption. Choose heap and container limits together, and validate whole-process peaks. There is no universal heap-to-limit ratio or P95 request rule. See Kubernetes requests and limits for scheduling and enforcement behavior.
Container-aware JVM flags and version caveats
Container awareness became standard in JDK 10 and was backported to supported Java 8 updates, including 8u191. Older builds and cgroup v2 support need version-specific checks. Verify the running JVMโs detected limits and effective heap rather than inferring support from the major version alone.
Once container awareness is active, -XX:MaxRAMPercentage sets the max heap as a percentage of the container limit. The default is 25%, and it is a ceiling, not an initial size. Treat no percentage as universal, since one that works at 512 MiB breaks at 8 GiB. For most production services explicit -Xmx is better, because it reads plainly and survives limit changes. Reserve percentages for workloads whose limits vary across environments.
# Illustrative JDK 17 deployment; validate resources for your workload.
apiVersion: apps/v1
kind: Deployment
metadata:
name: checkout-api
spec:
replicas: 6
selector:
matchLabels:
app: checkout-api
template:
metadata:
labels:
app: checkout-api
spec:
containers:
- name: checkout-api
image: registry.example.com/checkout-api:2.14.3
resources:
requests:
memory: "1536Mi" # illustrative request; validate peak demand
cpu: "500m"
limits:
memory: "2048Mi" # illustrative whole-process limit
cpu: "1500m"
env:
- name: JAVA_TOOL_OPTIONS
value: >-
-Xms768m
-Xmx1200m
-XX:+UseG1GC
-XX:+HeapDumpOnOutOfMemoryError
# Limit-relative sizing instead of explicit -Xmx:
# - name: JAVA_TOOL_OPTIONS
# value: >-
# -XX:MaxRAMPercentage=58.6
# -XX:InitialRAMPercentage=37.5
# -XX:+UseG1GCJAVA_TOOL_OPTIONS affects JVMs started in the container. Avoid adding arbitrary metaspace or direct-memory caps without measurements. HeapDumpOnOutOfMemoryError can respond to a Java memory error but not a kernel SIGKILL. Exit code 137 indicates SIGKILL, not uniquely an OOM event; confirm the container termination reason and node evidence. See diagnosing OOMKilled and exit code 137.
How do I rightsize Java memory from actual heap usage?
Read JVM heap and non-heap pools alongside container usage, GC activity, and native-memory diagnostics. These metrics have different accounting boundaries; subtracting JVM pool usage from container working set does not produce an exact native-memory measurement.
Exporters use different metric names and labels. The examples below assume Micrometer-style JVM metrics and cAdvisor container metrics, with one JVM per application container. Adjust selectors to your real labels and avoid duplicate scrapes. An explicit container="checkout-api" filter excludes other containers; container!="" alone does not exclude sidecars.
Reading committed vs used heap: the signal that separates demand from reservation
Committed versus used heap is the whole game here, because only one of them tracks demand. Used heap is live data plus garbage awaiting collection, so after a major collection it approximates the requirement. Committed heap is what the OS has promised the JVM. It stays high after demand falls, so sizing from it sizes you from a reservation.
# Current heap usage: sum all heap pools, not their maximum.
# Correlate samples with GC logs; this does not identify post-GC samples.
sum by (namespace, pod) (
jvm_memory_used_bytes{job="checkout-api",area="heap"}
)
# Committed heap
sum by (namespace, pod) (
jvm_memory_committed_bytes{job="checkout-api",area="heap"}
)
# JVM-reported non-heap pools (not all native allocations)
sum by (namespace, pod) (
jvm_memory_used_bytes{job="checkout-api",area="nonheap"}
)
# P95 of the app container's working set; confirm actual scrape labels.
quantile_over_time(0.95,
container_memory_working_set_bytes{container="checkout-api"}[7d]
)
# Mean recorded GC pause duration, not p99 or major-GC-only latency.
sum by (namespace, pod) (rate(jvm_gc_pause_seconds_sum{job="checkout-api"}[5m]))
/
sum by (namespace, pod) (rate(jvm_gc_pause_seconds_count{job="checkout-api"}[5m]))Use Native Memory Tracking, process mappings such as smaps_rollup, and allocator-specific tools to investigate unexplained memory. NMT covers JVM-managed native allocations, not every third-party native allocation. Look for consistent trends and peaks instead of treating a fixed residual percentage as normal.
What to alert on
Alert on confirmed OOM kills, sustained proximity to the container limit, growing post-GC live set, and GC regressions against application SLOs. Choose thresholds for the workload. A large committed-to-used ratio is an investigation signal, not proof that shrinking the heap is safe. Track scheduled jobs and startup peaks before acting.
kubectl top pod shows current usage rather than peak, so it confirms a change rather than sizing one.
A worked example: the wrong graph vs the right one
Consider an illustrative service with eight replicas. Its existing request is 3 GiB per container. Before proposing a reduction, the team measures heap, native memory, container peaks, and GC behavior across startup and its nightly batch. This is a sizing example, not a measured customer result.
Suppose a controlled canary with a 1,200 MiB heap ceiling shows acceptable GC behavior, whole-container P95 usage of 1,350 MiB, and a representative peak of 1,650 MiB. Those observations must be collected after the proposed change; an old working-set graph cannot establish them.
A 2,048 MiB container limit would leave 398 MiB above that observed peak. Whether this is adequate depends on allocation bursts and workloads outside the test window. Keep the larger limit if peak coverage is incomplete.
Use GC logs, NMT, and process-level diagnostics to explain the memory footprint. Setting an explicit -Xmx does not automatically eliminate native allocations or allocator fragmentation.
A 1,536 MiB request would sit above the example P95 but below the observed peak. That can be acceptable only if the team deliberately accepts bursting and the associated scheduling and eviction implications. A latency-sensitive workload may need a higher request.
The heap ceiling remains below the whole-container limit so that non-heap and native memory have room. Validate this relationship throughout the test, rather than computing a universal percentage from a single live-set sample.
Roll out only after the canary covers the relevant batch and startup patterns. Repeat the comparison under representative load and retain a rollback path.
The result is a tested configuration with explicit assumptions. If the application still needs 2.4 GiB of physical memory, do not lower its limit to 2 GiB merely because a heap chart looks smaller.
What if agent injection is blocked or the JVM is old?
Not every cluster allows JMX agent injection, since security teams block init containers and managed platforms restrict the pod’s process tree. Older JVMs add a second problem, because container awareness only landed in 8u191. Both need a path outside the pod spec.
Endpoint scraping and external JMX
The first fallback is endpoint scraping. If the service exposes a JMX or Prometheus endpoint, point your scraper at it, since many Spring Boot services already serve /actuator/prometheus on the management port, unwired.
An external JMX exporter can use remote JMX when the JVM is configured for it. Secure RMI with authentication, TLS, restricted network access, and correctly configured ports and advertised addresses. Compatibility and permissions must be checked for the runtime; it is not an automatic or universally available fallback.
Without JVM metrics, use conservative whole-container observations across representative peaks and canary any reduction. A percentile alone cannot distinguish live heap, committed capacity, native growth, or a memory leak. Restore the previous configuration if error rates, GC, or memory behavior deteriorate.
For heap sizing and pause diagnosis, see Java heap size and GC pauses on Kubernetes. That post covers what to set, while this one covers the container around it.
When an old JDK is the real problem
Java 8 needs its own caveat, because the container-awareness backport only arrived in 8u191. On an older build the JVM sizes its heap from host memory and dies on the cgroup limit rather than a heap error. Fixing the JDK is the rightsizing task.
What an automated rightsizer must do differently for JVMs
Any rightsizer can produce unsafe Java recommendations if it lowers container limits without considering heap configuration, native memory, and workload peaks. A JVM-aware workflow coordinates those settings and validates application behavior.
Three behaviors a generic rightsizer lacks
Read the right signal. Sizing from container_memory_working_set_bytes with a fixed percentile assumes the working set tracks demand. A JVM works differently. Size from heap used after major collection, non-heap used by area, GC pause and frequency, and thread count instead. Those describe what the application needs, while working set answers the separate question of the limit and request.
Respect the -Xmx floor. A limit below the heap ceiling produces a pod the cgroup kills before the JVM can throw an error. The heap ceiling is a hard lower bound, so both move in the same transaction. Lowering the limit alone turns an optimization into an outage.
Apply a headroom policy for JVM overhead. Non-heap does not scale linearly with heap. A policy that works at 512 MiB fails at 4 GiB, so heap and non-heap need separate treatment.
Rolling out a resize without an incident

Update heap flags, request, and limit together in the same pod-template change, using a separate canary deployment or controlled rollout. Observe a representative workload cycle, including scheduled jobs and startup. Define rollback criteria for OOM events, latency, error rates, GC overhead, and memory headroom. Restore the prior configuration if those criteria fail; changing a Deployment template does not selectively alter only one existing replica.
How Cast AI handles JVM workloads
A JVM signal changes one thing in a rightsizer: it separates demand from reservation. Request and limit still follow whole-process memory, because the cgroup enforces them. Once JVM metrics are visible, the agent can tell a real 2.4 GiB working set from a heap ceiling holding pages nobody reuses.
What the agent does with that signal
Cast AI supports JVM metrics collection through supported auto-instrumentation, configured metrics endpoints, or a custom Prometheus source. These are configuration choices, not a guaranteed automatic fallback when injection is blocked. Check the current JVM optimization documentation for supported runtimes, permissions, endpoint format, and workload configuration.
Recommendations write -Xms and -Xmx into the workload’s options variable. The agent detects it from JAVA_OPTS, JVM_OPTS, JAVA_TOOL_OPTIONS, JDK_JAVA_OPTIONS, _JAVA_OPTIONS, or CATALINA_OPTS. The heap ceiling is fixed at startup, so a recommendation that moves -Xmx triggers a restart and moves the limit with it. In-place pod resize covers the container only, never the JVM.
Review the active scaling policyโs memory overhead, recommendation percentile, look-back period, constraints, and OOM handling. The demo views illustrate these container-level controls; they are not JVM heap measurements or evidence of a specific OOM reduction. For rollout safeguards, see automated rightsizing safety.
Conclusion
Size the container for the whole process and coordinate heap changes with container resources. Inspect one representative service, canary the proposed settings, and validate the outcome. Learn how automated workload rightsizing fits the wider workflow, or start a free trial with a read-only cluster assessment.
FAQ
Why does my Java pod get OOMKilled when heap usage looks fine?
The cgroup limit covers the whole process, not just the heap. Metaspace, thread stacks, direct buffers, the code cache, and native overhead all count against it. A pod sized from heap data alone can hit the limit while the heap sits at 60%. The kernel sends SIGKILL, so the process exits with code 137 and the JVM never sees it. HeapDumpOnOutOfMemoryError does not fire either.
Should I set -Xmx or use MaxRAMPercentage?
Set -Xmx explicitly if your limits are stable, because it is readable and predictable, and use MaxRAMPercentage when limits vary across environments. Its default is 25%, and it sets a ceiling, so verify with jvm_memory_max_bytes that the value took effect.
Does the JVM return memory to Kubernetes after a peak?
Some collectors can return unused heap memory to the operating system. Behavior depends on the collector, JDK version, minimum heap, flags, and workload. Reserved, committed, and resident memory are different quantities, so inspect each before sizing.
What memory request should a Java pod have?
Use representative whole-container usage, startup and batch peaks, and your scheduling, QoS, and eviction requirements. P95 is one signal, not a universal safe request. Heap usage alone does not cover the full container footprint.
Can I resize Java pods without a restart?
Supported Kubernetes versions and configurations can resize some container resources in place. That does not automatically resize the JVM heap. Changing a startup heap flag such as -Xmx normally requires a new JVM process; verify runtime and platform behavior before relying on a restart-free change.
How much headroom should I leave between -Xmx and the limit?
Leave room for measured non-heap and native memory, transient allocations, and uncertainty in the workload sample. There is no universal percentage. Validate a proposed limit with representative peak traffic, GC objectives, and a controlled rollback plan.


