This section is intended when you want to understand the considerations and best practices on how to configure thread pools connection pools for Keycloak. For a configuration where this is applied, visit Deploy Keycloak for HA with the Keycloak Operator.
JGroups communications, which is used in single-site setups for the communication between Keycloak nodes, benefits from the use of virtual threads which are available in OpenJDK 21. This reduces the memory usage and removes the need to configure thread pool sizes. Therefore, the use of OpenJDK 21 is recommended.
Keycloak requests, as well as blocking probes, are handled by an executor pool. Depending on the available CPU cores, it has a maximum size of 50 or more threads.
Threads are created as needed, and will end when no longer needed, so the system will scale up and down automatically.
Keycloak allows configuring the maximum thread pool size by the http-pool-max-threads configuration option. See Deploy Keycloak for HA with the Keycloak Operator for an example.
When running on Kubernetes, adjust the number of worker threads to avoid creating more load than what the CPU limit allows for the Pod to avoid throttling, which would lead to congestion. When running on physical machines, adjust the number of worker threads to avoid creating more load than the node can handle to avoid congestion. Congestion would result in longer response times and an increased memory usage, and eventually an unstable system.
Ideally, you should start with a low limit of threads and adjust it accordingly to the target throughput and response time.
When the load and the number of threads increases, the database connections can also become a bottleneck.
Once a request cannot acquire a database connection within 5 seconds, it will fail with a message in the log like Unable to acquire JDBC Connection.
The caller will receive a response with a 5xx HTTP status code indicating a server side error.
If you increase the number of database connections and the number of threads too much, the system will be congested under a high load with requests queueing up, which leads to a bad performance.
The number of database connections is configured via the Database settings db-pool-initial-size, db-pool-min-size and db-pool-max-size respectively.
Low numbers ensure fast response times for all clients, even if there is an occasionally failing request when there is a load spike.
By default, Keycloak will queue all incoming requests infinitely, even if the request processing stalls. This will use additional memory in the Pod, can exhaust resources in the load balancers, and the requests will eventually time out on the client side without the client knowing if the request has been processed. To limit the number of queued requests in Keycloak, set an additional Quarkus configuration option.
Configure http-max-queued-requests to specify a maximum queue length to allow for effective load shedding once this queue size is exceeded.
Assuming a Keycloak Pod processes around 200 requests per second, a queue of 1000 would lead to maximum waiting times of around 5 seconds.
When this setting is active, requests that exceed the number of queued requests will return with an HTTP 503 error. Keycloak logs the error message in its log.
Keycloak’s liveness probe is non-blocking to avoid a restart of a Pod under a high load.
The overall health probe and the readiness probe can in some cases block to check the connection to the database, so they might fail under a high load. Due to this, a Pod can become non-ready under a high load.
In order for Java to create threads, when running on Linux it needs to have file handles available.
Therefore, the number of open files (as retrieved as ulimit -n on Linux) need to provide head-space for Keycloak to increase the number of threads needed.
Each thread will also consume memory, and the container memory limits need to be set to a value that allows for this or the Pod will be killed by Kubernetes.