diff --git a/docs/documentation/release_notes/topics/24_0_0.adoc b/docs/documentation/release_notes/topics/24_0_0.adoc index 8ca20b429c5..6772329a357 100644 --- a/docs/documentation/release_notes/topics/24_0_0.adoc +++ b/docs/documentation/release_notes/topics/24_0_0.adoc @@ -430,13 +430,14 @@ mappers would never be used. The supported options were updated to only include - `urn:oasis:names:tc:SAML:2.0:nameid-format:persistent` - `urn:oasis:names:tc:SAML:2.0:nameid-format:transient` -= Different JVM memory settings when running in container += Different JVM memory settings when running in a container Instead of specifying hardcoded values for the initial and maximum heap size, {project_name} uses relative values to the total memory of a container. -The JVM options `-Xms`, and `-Xmx` were replaced by `-XX:InitialRAMPercentage`, and `-XX:MaxRAMPercentage`. +The JVM options `-Xms` and `-Xmx` were replaced by `-XX:InitialRAMPercentage` and `-XX:MaxRAMPercentage`. -For more details, see the -https://www.keycloak.org/server/containers[Running Keycloak in a container] guide. +WARNING: It can significantly impact memory consumption, so executing particular actions might be required. + +For more details, see the link:{upgradingguide_link}[{upgradingguide_name}]. ifeval::[{project_community}==true] = GELF log handler has been deprecated diff --git a/docs/documentation/upgrading/topics/changes/changes-24_0_0.adoc b/docs/documentation/upgrading/topics/changes/changes-24_0_0.adoc index 5eb502c191c..40b92c70765 100644 --- a/docs/documentation/upgrading/topics/changes/changes-24_0_0.adoc +++ b/docs/documentation/upgrading/topics/changes/changes-24_0_0.adoc @@ -488,6 +488,17 @@ For custom extensions there may be some changes needed: The algorithm that {project_name} uses to sign internal tokens (a JWT which is consumed by {project_name} itself, for example a refresh or action token) is being changed from `HS256` to the more secure `HS512`. A new key provider named `hmac-generated-hs512` is now added for realms. Note that in migrated realms the old `hmac-generated` provider and the old `HS256` key are maintained and still validate tokens issued before the upgrade. The `HS256` provider can be manually deleted when no more old tokens exist following the {adminguide_link}#rotating-keys[rotating keys guidelines]. += Different JVM memory settings when running in a container + +The JVM options `-Xms` and `-Xmx` were replaced by `-XX:InitialRAMPercentage` and `-XX:MaxRAMPercentage` when running in a container. +Instead of the static maximum heap size settings, {project_name} specifies the maximum as 70% of the total container memory. + +As the heap size is dynamically calculated based on the total container memory, you should *always set the memory limit* for the container. + +WARNING: If the memory limit is not set, the memory consumption rapidly increases as the maximum heap size grows up to 70% of the total container memory. + +For more details, see the https://www.keycloak.org/server/containers#_specifying_different_memory_settings[Running Keycloak in a container] guide. + ifeval::[{project_community}==true] = GELF log handler has been deprecated diff --git a/docs/guides/server/containers.adoc b/docs/guides/server/containers.adoc index 9307da61851..c4eb4364a2c 100644 --- a/docs/guides/server/containers.adoc +++ b/docs/guides/server/containers.adoc @@ -238,17 +238,25 @@ The `-XX:MaxRAMPercentage` option represents the maximum heap size as 70% of the The `-XX:InitialRAMPercentage` option represents the initial heap size as 50% of the total container memory. These values were chosen based on a deeper analysis of {project_name} memory management. +As the heap size is dynamically calculated based on the total container memory, you should *always set the memory limit* for the container. +Previously, the maximum heap size was set to 512 MB, and in order to approach similar values, you should set the memory limit to at least 750 MB. +For smaller production-ready deployments, the recommended memory limit is 2 GB. + The JVM options related to the heap might be overridden by setting the environment variable `JAVA_OPTS_KC_HEAP`. You can find the default values of the `JAVA_OPTS_KC_HEAP` in the source code of the `kc.sh`, or `kc.bat` script. -For example, you can specify the environment variable as follows: + +For example, you can specify the environment variable and memory limit as follows: [source,bash,subs="attributes+"] ---- -podman|docker run --name mykeycloak -p 8080:8080 \ +podman|docker run --name mykeycloak -p 8080:8080 -m 1g \ -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=change_me \ -e JAVA_OPTS_KC_HEAP="-XX:MaxHeapFreeRatio=30 -XX:MaxRAMPercentage=65" \ quay.io/keycloak/keycloak:{containerlabel} \ start-dev ---- +WARNING: If the memory limit is not set, the memory consumption rapidly increases as the heap size can grow up to 70% of the total container memory. +Once the JVM allocates the memory, it is returned to the OS reluctantly with the current {project_name} GC settings. +