Description

The documentation currently states that KC should have a number of owners of at least two for some caches:

https://www.keycloak.org/server/caching#_configuring_caches_for_availability

Instead of documenting this, the KC code should enforce this: For those caches, if the number of owners is only 1, it should be set to 2 at runtime, and KC should print a warning that it adjusted them.

Once this has been implemented, the paragraph can be removed from the docs.

Configuring caches for availability

Distributed caches replicate cache entries on a subset of nodes in a cluster and assigns entries to fixed owner nodes.
Each distributed cache, that is a primary source of truth of the data (authenticationSessions, loginFailures and actionTokens) has two owners per default, which means that two nodes have a copy of the specific cache entries. Non-owner nodes query the owners of a specific cache to obtain data. When one of the owners becomes unavailable, the data is restored from the remaining owner and rebalanced across the remaining nodes. When both owner nodes are offline, all data is lost.
The default number of two owners is the minimum number is necessary to survive one node (owner) failure or a rolling restart in a cluster setup with at least two nodes. A higher number increases the availability of the data, but at the expense of slower writes as more nodes need to be updated. Therefore, changing the number of owners for the caches authenticationSessions, loginFailures and actionTokens is not recommended.

Discussion

No response

Motivation

Simplify the docs and make KC safe to run. It is complicated as different caches have different number of owners and the settings depend on if persistent sessions are enabled or not.

An opinionated setup should provide a lower total cost of ownership for people running Keycloak.

Details

As part of the change, the paragraph listed above should be removed from the docs.

We want to backport this to KC 26.2 to benefit from this simplification and to prevent problematic configurations.