Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 0 additions & 13 deletions docs/guides/server/caching.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -164,19 +164,6 @@ apply the upper bound to. For example, to apply an upper-bound of `1000` to the

Setting a maximum cache size for `sessions`, `clientSessions`, `offlineSessions` and `offlineClientSessions` is not supported when volatile sessions are enabled.

=== 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.

=== Specify your own cache configuration file

To specify your own cache configuration file, enter this command:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -34,15 +34,20 @@
import org.infinispan.transaction.lookup.EmbeddedTransactionManagerLookup;
import org.jboss.logging.Logger;
import org.keycloak.Config;
import org.keycloak.connections.infinispan.InfinispanConnectionProvider;

import static org.keycloak.connections.infinispan.InfinispanConnectionProvider.ACTION_TOKEN_CACHE;
import static org.keycloak.connections.infinispan.InfinispanConnectionProvider.ALL_CACHES_NAME;
import static org.keycloak.connections.infinispan.InfinispanConnectionProvider.AUTHENTICATION_SESSIONS_CACHE_NAME;
import static org.keycloak.connections.infinispan.InfinispanConnectionProvider.AUTHORIZATION_CACHE_NAME;
import static org.keycloak.connections.infinispan.InfinispanConnectionProvider.AUTHORIZATION_REVISIONS_CACHE_DEFAULT_MAX;
import static org.keycloak.connections.infinispan.InfinispanConnectionProvider.AUTHORIZATION_REVISIONS_CACHE_NAME;
import static org.keycloak.connections.infinispan.InfinispanConnectionProvider.CLIENT_SESSION_CACHE_NAME;
import static org.keycloak.connections.infinispan.InfinispanConnectionProvider.CLUSTERED_CACHE_NAMES;
import static org.keycloak.connections.infinispan.InfinispanConnectionProvider.CRL_CACHE_DEFAULT_MAX;
import static org.keycloak.connections.infinispan.InfinispanConnectionProvider.CRL_CACHE_NAME;
import static org.keycloak.connections.infinispan.InfinispanConnectionProvider.LOCAL_CACHE_NAMES;
import static org.keycloak.connections.infinispan.InfinispanConnectionProvider.LOCAL_MAX_COUNT_CACHES;
import static org.keycloak.connections.infinispan.InfinispanConnectionProvider.LOGIN_FAILURE_CACHE_NAME;
import static org.keycloak.connections.infinispan.InfinispanConnectionProvider.OFFLINE_CLIENT_SESSION_CACHE_NAME;
import static org.keycloak.connections.infinispan.InfinispanConnectionProvider.OFFLINE_USER_SESSION_CACHE_NAME;
import static org.keycloak.connections.infinispan.InfinispanConnectionProvider.REALM_CACHE_NAME;
Expand Down Expand Up @@ -102,7 +107,7 @@ public static void configureLocalCaches(Config.Scope keycloakConfig, Configurati
*/
public static void applyDefaultConfiguration(ConfigurationBuilderHolder holder) {
var configs = holder.getNamedConfigurationBuilders();
for (var name : InfinispanConnectionProvider.ALL_CACHES_NAME) {
for (var name : ALL_CACHES_NAME) {
configs.computeIfAbsent(name, cacheName -> DEFAULT_CONFIGS.getOrDefault(cacheName, TO_NULL).get());
}
}
Expand Down Expand Up @@ -157,7 +162,7 @@ public static void validateWorkCacheConfiguration(ConfigurationBuilderHolder hol
*/
public static void removeClusteredCaches(ConfigurationBuilderHolder holder) {
logger.debug("Removing clustered caches");
Arrays.stream(InfinispanConnectionProvider.CLUSTERED_CACHE_NAMES).forEach(holder.getNamedConfigurationBuilders()::remove);
Arrays.stream(CLUSTERED_CACHE_NAMES).forEach(holder.getNamedConfigurationBuilders()::remove);
}

/**
Expand Down Expand Up @@ -245,12 +250,40 @@ public static void configureSessionsCachesForVolatileSessions(ConfigurationBuild
if (builder.clustering().hash().attributes().attribute(HashConfiguration.NUM_OWNERS).get() != 1 &&
builder.persistence().stores().stream().noneMatch(p -> p.attributes().attribute(AbstractStoreConfiguration.SHARED).get())
) {
logger.infof("Setting a memory limit implies to have exactly one owne. Setting num_owners=1 to avoid data loss.", name);
logger.infof("Setting a memory limit implies to have exactly one owner. Setting num_owners=1 to avoid data loss.", name);
builder.clustering().hash().numOwners(1);
}
}
}

/**
* Configures the caches "actionToken", "authenticationSessions", and "loginFailures" with the minimum number of
* owners to prevent data loss in a single instance crash.
* <p>
* The data in those caches only exist in memory, therefore they must have more than one owner configured.
*
* @param holder The {@link ConfigurationBuilderHolder} where the caches are configured.
* @throws IllegalStateException if an Infinispan cache is not defined in the {@code holder}. This could indicate a
* missing or incorrect configuration.
*/
public static void ensureMinimumOwners(ConfigurationBuilderHolder holder) {
for (var name : Arrays.asList(
LOGIN_FAILURE_CACHE_NAME,
AUTHENTICATION_SESSIONS_CACHE_NAME,
ACTION_TOKEN_CACHE)) {
var builder = holder.getNamedConfigurationBuilders().get(name);
if (builder == null) {
throw cacheNotFound(name);
}
var hashConfig = builder.clustering().hash();
var owners = hashConfig.attributes().attribute(HashConfiguration.NUM_OWNERS).get();
if (owners < 2) {
logger.infof("Setting num_owners=2 (configured value is %s) for cache '%s' to prevent data loss.", owners, name);

@ryanemerson ryanemerson Aug 5, 2025 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we agreed that this should be a warning (detailed in the GH issue) so that the user is more aware that their configuration is not being applied as provided.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I know, but the other methods that change the number of owners for session caches are logged as INFO, not WARN.
Should I still change this to warn?

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good point. Given that we explicitly changed the behaviour from WARN to INFO in 26.3, it doesn't feel right to change this again. Let's be consistent and use INFO everywhere.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A late comment from my side:

We changed those messages from WARN to INFO as we didn't want to force users to change the XML file when they disabled or enabled persistent sessions.

This might be slightly different as someone is putting (manually) something wrong in the XML file. Still I'm fine with the INFO message here.

hashConfig.numOwners(2);
}
}
}

// private methods below

private static void configureRevisionCache(ConfigurationBuilderHolder holder, String baseCache, String revisionCache, long defaultMaxEntries) {
Expand Down Expand Up @@ -284,7 +317,7 @@ private static IllegalStateException cacheNotFound(String cache) {

public static ConfigurationBuilder getCrlCacheConfig() {
var builder = createCacheConfigurationBuilder();
builder.memory().whenFull(EvictionStrategy.REMOVE).maxCount(InfinispanConnectionProvider.CRL_CACHE_DEFAULT_MAX);
builder.memory().whenFull(EvictionStrategy.REMOVE).maxCount(CRL_CACHE_DEFAULT_MAX);
return builder;
}

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -213,6 +213,7 @@ private static void singleSiteConfiguration(Config.Scope config, ConfigurationBu
CacheConfigurator.checkCachesExist(holder, Arrays.stream(ALL_CACHES_NAME));
CacheConfigurator.configureCacheMaxCount(config, holder, Arrays.stream(CLUSTERED_MAX_COUNT_CACHES));
CacheConfigurator.validateWorkCacheConfiguration(holder);
CacheConfigurator.ensureMinimumOwners(holder);
KeycloakModelUtils.runJobInTransaction(factory, session -> JGroupsConfigurator.configureJGroups(config, holder, session));
configureMetrics(config, holder);
}
Expand Down