From f4d5fa68c1159fd03de93a27cbef3d7f46a50e75 Mon Sep 17 00:00:00 2001 From: Pedro Ruivo Date: Fri, 20 Jun 2025 17:45:22 +0100 Subject: [PATCH] Update documentation about volatile sessions Closes #40639 Signed-off-by: Pedro Ruivo Signed-off-by: Alexander Schwartz Co-authored-by: Alexander Schwartz --- .../topics/changes/changes-26_3_0.adoc | 13 +++++------ docs/guides/server/caching.adoc | 22 ++----------------- .../impl/embedded/CacheConfigurator.java | 4 ++-- 3 files changed, 9 insertions(+), 30 deletions(-) diff --git a/docs/documentation/upgrading/topics/changes/changes-26_3_0.adoc b/docs/documentation/upgrading/topics/changes/changes-26_3_0.adoc index 6a2cf9dca2b..a2834eb84f0 100644 --- a/docs/documentation/upgrading/topics/changes/changes-26_3_0.adoc +++ b/docs/documentation/upgrading/topics/changes/changes-26_3_0.adoc @@ -46,9 +46,12 @@ To enhance security, only users with the `admin` role in the `master` realm (ser === Problematic cache configurations ignored -Previous versions {project_name} warned about problematic configurations, for example, if a wrong number of owners was configured or a cache size was set when it should not have been set when enabling volatile user sessions. -The current version will still warn about those settings, but will also ignore them to ensure a correct behavior and to avoid data loss. +Previous versions of {project_name} warned about problematic configurations, for example, if a wrong number of owners was configured or a cache size was set when it should not have been set when enabling volatile user sessions. +The docs also stated to update the `cache-ispn.xml` configuration file for volatile user sessions. +The current version will always use safe settings for the number of owners and maximum cache size for the affected user and client session caches, and will log only an INFO message. +With this behavior, there is no need any more to update the `cache-ispn.xml` configuration file. +If you previously used a custom `cache-ispn.xml` in order to use volatile user sessions, we recommend reverting those changes and use the standard configuration file. === Email verification is now automatically set when using a OpenID Connect broker with `Trust email` is enabled and `Sync Mode` is `FORCE` @@ -111,12 +114,6 @@ Previously the default *browser* flow had a *Browser - Conditional OTP* conditio Upgraded realms will not be changed. The updated flow will only be available for new realms. Take this change into consideration if you have automated the realm creation. -=== Volatile Session Cache Defaults - -If the `persistent-user-sessions` feature is disabled, i.e. volatile sessions are configured, {project_name} now prevents -`num_owners=1` being configured unless a shared persistent store is also configured. This is to prevent data loss on cache -rebalances. - == Deprecated features The following sections provide details on deprecated features. diff --git a/docs/guides/server/caching.adoc b/docs/guides/server/caching.adoc index 04ab4535ce7..10028c091d4 100644 --- a/docs/guides/server/caching.adoc +++ b/docs/guides/server/caching.adoc @@ -138,35 +138,17 @@ Since all the sessions in this setup are stored in-memory, there are two side ef * Increased memory consumption. When using volatile user sessions, the cache is the source of truth for user and client sessions. -Therefore, it is necessary to not define an upper limit on the total number of entries that can be stored via the setting `max-count`. -Similarly, it's crucial that we replicate each entry to two nodes to prevent data loss on node failures and rolling restarts. +{project_name} automatically adjusts the number of entries that can be stored in memory, and increases the number of copies to prevent data loss. [WARNING] ==== -When using volatile user sessions, the `max-count` setting for the offline session is ignored. - It is not recommended to use volatile user sessions when using offline sessions extensively due to potentially high memory usage. For volatile sessions, the time offline sessions are cached in memory can be limited with the SPI options `spi-user-sessions--infinispan--offline-client-session-cache-entry-lifespan-override` and `spi-user-sessions--infinispan--offline-session-cache-entry-lifespan-override`. ==== Follow these steps to enable this setup: -1. Edit {project_name}'s cache config file (`conf/cache-ispn.xml`) for caches `sessions`, `clientSessions`, `offlineSessions` and `offlineClientSessions` with the following update: -+ --- -* Remove the `++` -* Change `owners` attribute of the `distributed-cache` tag to 2 or more --- -+ -An example of the resulting configuration for the `sessions` cache would look as follows. -+ -[source,xml] ----- - - - ----- -2. Disable `persistent-user-sessions` feature using the following command: +1. Disable `persistent-user-sessions` feature using the following command: + ---- bin/kc.sh start --features-disabled=persistent-user-sessions ... diff --git a/model/infinispan/src/main/java/org/keycloak/spi/infinispan/impl/embedded/CacheConfigurator.java b/model/infinispan/src/main/java/org/keycloak/spi/infinispan/impl/embedded/CacheConfigurator.java index 5188d832ecd..311dc96ae29 100644 --- a/model/infinispan/src/main/java/org/keycloak/spi/infinispan/impl/embedded/CacheConfigurator.java +++ b/model/infinispan/src/main/java/org/keycloak/spi/infinispan/impl/embedded/CacheConfigurator.java @@ -222,13 +222,13 @@ public final class CacheConfigurator { throw cacheNotFound(name); } if (builder.memory().maxCount() != -1) { - logger.warnf("Persistent user sessions disabled and memory limit is set. Ignoring cache limits to avoid losing sessions for cache %s.", name); + logger.infof("Persistent user sessions disabled and memory limit is set. Ignoring cache limits to avoid losing sessions for cache %s.", name); builder.memory().maxCount(-1); } if (builder.clustering().hash().attributes().attribute(HashConfiguration.NUM_OWNERS).get() == 1 && builder.persistence().stores().stream().noneMatch(p -> p.attributes().attribute(AbstractStoreConfiguration.SHARED).get()) ) { - logger.warnf("Persistent user sessions disabled with number of owners set to default value 1 for cache %s and no shared persistence store configured. Setting num_owners=2 to avoid data loss.", name); + logger.infof("Persistent user sessions disabled with number of owners set to default value 1 for cache %s and no shared persistence store configured. Setting num_owners=2 to avoid data loss.", name); builder.clustering().hash().numOwners(2); } }