How To Configure Java Heap Size Inside a Docker Container

我不是女神ヾ 2023-01-23 02:55 11阅读 0赞

# How To Configure Java Heap Size Inside a Docker Container #

> copy from: https://www.baeldung.com/ops/docker-jvm-heap-size  
> Last modified: May 28, 2021  
> by [baeldung][]

## 1. Overview ##

When we run Java within a container, we may wish to tune it to make the best use of the available resources.

In this tutorial, we’ll see how to set [JVM parameters][] in a container that runs a Java process. Although the following applies to any JVM setting, we’ll focus on the common `-Xmx` and `-Xms` flags.

We’ll also look at common issues containerizing programs that run with certain versions of Java and how to set flags in some popular containerized Java applications.

## 2. Default Heap Settings in Java Containers ##

The JVM is pretty good at determining appropriate default memory settings.

In the past, [the JVM was not aware of the memory and CPU allocated to the container][]. So, Java 10 introduced a new setting: +UseContainerSupport (enabled by default) to fix the root cause, and developers backported the fix to Java 8 in 8u191. The JVM now calculates its memory based on the memory allocated to the container.

However, we may still wish to change the settings from their defaults in certain applications.

### 2.1. Automatic Memory Calculation ###

**When we don’t set -Xmx and -Xmx parameters, the JVM sizes the heap based on the system specifications.**

Let’s look at that heap size:

$ java -XX:+PrintFlagsFinal -version | grep -Ei "maxheapsize|maxram"

This outputs:

openjdk version "15" 2020-09-15
    OpenJDK Runtime Environment AdoptOpenJDK (build 15+36)
    OpenJDK 64-Bit Server VM AdoptOpenJDK (build 15+36, mixed mode, sharing)
       size_t MaxHeapSize      = 4253024256      {product} {ergonomic}
     uint64_t MaxRAM           = 137438953472 {pd product} {default}
        uintx MaxRAMFraction   = 4               {product} {default}
       double MaxRAMPercentage = 25.000000       {product} {default}
       size_t SoftMaxHeapSize  = 4253024256   {manageable} {ergonomic}

Here, we see that the JVM sets its heap size to approximately 25% of the available RAM. In this example, it allocated 4GB on a system with 16GB.

For the purposes of testing, let’s create a program that prints the heap sizes in megabytes:

public static void main(String[] args) {
        
      int mb = 1024 * 1024;
      MemoryMXBean memoryBean = ManagementFactory.getMemoryMXBean();
      long xmx = memoryBean.getHeapMemoryUsage().getMax() / mb;
      long xms = memoryBean.getHeapMemoryUsage().getInit() / mb;
      LOGGER.log(Level.INFO, "Initial Memory (xms) : {0}mb", xms);
      LOGGER.log(Level.INFO, "Max Memory (xmx) : {0}mb", xmx);
    }

Let’s place that program in an empty directory, in a file named PrintXmxXms.java.

We can test it on our host, assuming we have an installed JDK. In a Linux system, we can compile our program and run it from a terminal opened on that directory:

$ javac ./PrintXmxXms.java
    $ java -cp . PrintXmxXms

On a system with 16Gb of RAM, the output is:

INFO: Initial Memory (xms) : 254mb
    INFO: Max Memory (xmx) : 4,056mb

Now, let’s try that in some containers.

### 2.2. Before JDK 8u191 ###

Let’s add the following Dockerfile in the folder that contains our Java program:

FROM openjdk:8u92-jdk-alpine
    COPY *.java /src/
    RUN mkdir /app \
        && ls /src \
        && javac /src/PrintXmxXms.java -d /app
    CMD ["sh", "-c", \
         "java -version \
          && java -cp /app PrintXmxXms"]

Here we’re using a container that uses an older version of Java 8, which predates the container support that’s available in more up-to-date versions. Let’s build its image:

$ docker build -t oldjava .

The CMD line in the Dockerfile is the process that gets executed by default when we run the container. **Since we didn’t provide the -Xmx or -Xms JVM flags, the memory settings will be defaulted.**

Let’s run that container:

$ docker run --rm -ti oldjava
    openjdk version "1.8.0_92-internal"
    OpenJDK Runtime Environment (build 1.8.0_92-...)
    OpenJDK 64-Bit Server VM (build 25.92-b14, mixed mode)
    Initial Memory (xms) : 198mb
    Max Memory (xmx) : 2814mb

Let’s now constrain the container memory to 1GB.

$ docker run --rm -ti --memory=1g oldjava
    openjdk version "1.8.0_92-internal"
    OpenJDK Runtime Environment (build 1.8.0_92-...)
    OpenJDK 64-Bit Server VM (build 25.92-b14, mixed mode)
    Initial Memory (xms) : 198mb
    Max Memory (xmx) : 2814mb

As we can see, the output is exactly the same. This proves the older JVM does not respect the container memory allocation.

### 2.3. After JDK 8u130 ###

With the same test program, let’s use a more up to date JVM 8 by changing the first line of the Dockerfile:

FROM openjdk:8-jdk-alpine

We can then test it again:

$ docker build -t newjava .
    $ docker run --rm -ti newjava
    openjdk version "1.8.0_212"
    OpenJDK Runtime Environment (IcedTea 3.12.0) (Alpine 8.212.04-r0)
    OpenJDK 64-Bit Server VM (build 25.212-b04, mixed mode)
    Initial Memory (xms) : 198mb
    Max Memory (xmx) : 2814mb

Here again, it is using the whole docker host memory to calculate the JVM heap size. However, if we allocate 1GB of RAM to the container:

$ docker run --rm -ti --memory=1g newjava
    openjdk version "1.8.0_212"
    OpenJDK Runtime Environment (IcedTea 3.12.0) (Alpine 8.212.04-r0)
    OpenJDK 64-Bit Server VM (build 25.212-b04, mixed mode)
    Initial Memory (xms) : 16mb
    Max Memory (xmx) : 247mb

This time, the JVM calculated the heap size based on the 1GB of RAM available to the container.

Now we understand how the JVM calculates its defaults and why we need an up-to-date JVM to get the correct defaults, let’s look at customizing the settings.

## 3. Memory Settings in Popular Base Images ##

### 3.1. OpenJDK and AdoptOpenJDK ###

Instead of hard-coding the JVM flags directly on our container’s command, it’s good practice to use an environment variable such as JAVA\_OPTS. We use that variable within our Dockerfile, but it can be modified when the container is launched:

FROM openjdk:8u92-jdk-alpine
    COPY src/ /src/
    RUN mkdir /app \
     && ls /src \
     && javac /src/com/baeldung/docker/printxmxxms/PrintXmxXms.java \
        -d /app
    ENV JAVA_OPTS=""
    CMD java $JAVA_OPTS -cp /app \ 
        com.baeldung.docker.printxmxxms.PrintXmxXms

Let’s now build the image:

$ docker build -t openjdk-java .

We can choose our memory settings at runtime by specifying the JAVA\_OPTS environment variable:

$ docker run --rm -ti -e JAVA_OPTS="-Xms50M -Xmx50M" openjdk-java
    INFO: Initial Memory (xms) : 50mb
    INFO: Max Memory (xmx) : 48mb

We should note that there is a slight difference between the -Xmx parameter and the Max memory reported by the JVM. This is because Xmx sets the maximum size of the memory allocation pool, which includes the heap, the garbage collector’s survivor space, and other pools.

### 3.2. Tomcat 9 ###

A Tomcat 9 container has its own startup scripts, so to set JVM parameters, we need to work with those scripts.

The `bin/catalina.sh` script requires us to **set the memory parameters in the environment variable CATALINA\_OPTS.**

Let’s first [create a war file][] to deploy to Tomcat.

Then, we’ll containerize it using a simple Dockerfile, where we declare the CATALINA\_OPTS environment variable:

FROM tomcat:9.0
    COPY ./target/*.war /usr/local/tomcat/webapps/ROOT.war
    ENV CATALINA_OPTS="-Xms1G -Xmx1G"

Then we build the container image and run it:

$ docker build -t tomcat .
    $ docker run --name tomcat -d -p 8080:8080 \
      -e CATALINA_OPTS="-Xms512M -Xmx512M" tomcat

We should note that when we run this, we’re passing a new value to CATALINA\_OPTS. If we don’t provide this value, though, we gave some defaults in line 3 of the Dockerfile.

We can check the runtime parameters applied and verify that our options -Xmx and -Xms are there:

$ docker exec -ti tomcat jps -lv
    1 org.apache.catalina.startup.Bootstrap <other options...> -Xms512M -Xmx512M

## 4. Using Build Plugins ##

Maven and Gradle offer plugins that allow us to create container images without a Dockerfile. The generated images can generally be parameterized at runtime through environment variables.

Let’s look at a few examples.

### 4.1. Using Spring Boot ###

Since Spring Boot 2.3, the Spring Boot [Maven][] and [Gradle][] plugins can [build an efficient container without a Dockerfile][].

With Maven, we add them to a block within the spring-boot-maven-plugin:

<?xml version="1.0" encoding="UTF-8"?>
    <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
      <groupId>com.baeldung.docker</groupId>
      <artifactId>heapsizing-demo</artifactId>
      <version>0.0.1-SNAPSHOT</version>
      
      <build> 
        <plugins> 
          <plugin> 
            <groupId>org.springframework.boot</groupId> 
            <artifactId>spring-boot-maven-plugin</artifactId> 
            <configuration>
              <image>
                <name>heapsizing-demo</name>
              </image>
       
            </configuration>
          </plugin>
        </plugins>
      </build>
    </project>

To build the project, run:

$ ./mvnw clean spring-boot:build-image

This will result in an image named :. In this example demo-app:0.0.1-SNAPSHOT. Under the hood, Spring Boot uses [Cloud Native Buildpacks][] as the underlying containerization technology.

**The plugin hard-codes the memory settings of the JVM**. However, we can still override them by setting the environment variables *`JAVA_OPTS`* or *`JAVA_TOOL_OPTIONS`*:

$ docker run --rm -ti -p 8080:8080 \
      -e JAVA_TOOL_OPTIONS="-Xms20M -Xmx20M" \
      --memory=1024M heapsizing-demo:0.0.1-SNAPSHOT

The output will be similar to this:

Setting Active Processor Count to 8
    Calculated JVM Memory Configuration: [...]
    [...]
    Picked up JAVA_TOOL_OPTIONS: -Xms20M -Xmx20M 
    [...]

### 4.2. Using Google JIB ###

Just like the Spring Boot maven plugin, [Google JIB][] creates efficient Docker images without a Dockerfile. The Maven and Gradle plugins are configured in a similar fashion. Google JIB also uses the environment variable *`JAVA_TOOL_OPTIONS`* as the JVM parameters’ overriding mechanism.

We can use the Google JIB Maven plugin in any Java framework capable of generating executable jar files. For example, it’s possible to use it in a Spring Boot application in place of the spring-boot-maven plugin to generate container images:

<?xml version="1.0" encoding="UTF-8"?>
    <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
        
        
    
        <build>
            <plugins>
                
                <plugin>
                    <groupId>com.google.cloud.tools</groupId>
                    <artifactId>jib-maven-plugin</artifactId>
                    <version>2.7.1</version>
                    <configuration>
                        <to>
                            <image>heapsizing-demo-jib</image>
                        </to>
                    </configuration>
                </plugin>
            </plugins>
        </build>
    </project>

The image is built using the maven jib:DockerBuild target:

$ mvn clean install && mvn jib:dockerBuild

We can now run it as usual:

$ docker run --rm -ti -p 8080:8080 \
    -e JAVA_TOOL_OPTIONS="-Xms50M -Xmx50M" heapsizing-demo-jib
    Picked up JAVA_TOOL_OPTIONS: -Xms50M -Xmx50M
    [...]
    2021-01-25 17:46:44.070  INFO 1 --- [           main] c.baeldung.docker.XmxXmsDemoApplication  : Started XmxXmsDemoApplication in 1.666 seconds (JVM running for 2.104)
    2021-01-25 17:46:44.075  INFO 1 --- [           main] c.baeldung.docker.XmxXmsDemoApplication  : Initial Memory (xms) : 50mb
    2021-01-25 17:46:44.075  INFO 1 --- [           main] c.baeldung.docker.XmxXmsDemoApplication  : Max Memory (xmx) : 50mb

## 5. Conclusion ##

In this article, we covered the need to use an up-to-date JVM to get default memory settings that work well in a container.

We then looked at best practices for setting -Xms and -Xmx in custom container images and how to work with existing Java application containers to set the JVM options in them.

Finally, we saw how to advantage of build tools to manage the containerization of a Java application.

As always, the source code for the examples is available over on [GitHub][].

[baeldung]: https://www.baeldung.com/author/baeldung/
[JVM parameters]: https://www.baeldung.com/jvm-parameters
[the JVM was not aware of the memory and CPU allocated to the container]: https://developers.redhat.com/blog/2017/03/14/java-inside-docker/
[create a war file]: https://www.baeldung.com/spring-boot-war-tomcat-deploy
[Maven]: https://docs.spring.io/spring-boot/docs/current/maven-plugin/reference/htmlsingle/#build-image
[Gradle]: https://docs.spring.io/spring-boot/docs/current/gradle-plugin/reference/htmlsingle/#build-image
[build an efficient container without a Dockerfile]: https://spring.io/guides/topicals/spring-boot-docker/
[Cloud Native Buildpacks]: https://buildpacks.io/
[Google JIB]: https://www.baeldung.com/jib-dockerizing
[GitHub]: https://github.com/eugenp/tutorials/tree/master/docker