Resource limits and cgroups

In the context of Docker, cgroups (control groups) are used to limit the resources of a container.

IAM containers use up to a fixed amount of 4GB of heap because IAM_JAVA_OPTS=-Xmx4G is the default. To scale with Docker resource limits instead, the option -XX:MaxRAMPercentage can be used.

Caution when using -XX:MaxRAMPercentage

The option -XX:MaxRAMPercentage limits the amount of heap available to the JVM to the specified percentage of the total amount of memory available for the container.

It is important not to set this value too high (e.g. to 100): If the JVM and additional processes running in the container (e.g. through docker exec) exceed the container's memory limit, the container may be killed.

The default value for -XX:MaxRAMPercentage is 50.

Docker CLI

docker run --rm --memory 4g --env "IAM_JAVA_OPTS=-XX:MaxRAMPercentage=50"


version: '3.7'
    image:    environment:
      - "IAM_JAVA_OPTS=-XX:MaxRAMPercentage=50"
    deploy: # Only for Docker Swarm
          memory: "4G"

Note that the -XshowSettings:vm option will log the memory consumption of the JVM. The -XshowSettings:vm option can be added to IAM_JAVA_OPTS. With the option enabled, this additional log output will be generated:

VM settings:
    Max. Heap Size (Estimated): 2.00G
    Using VM: OpenJDK 64-Bit Server VM