Keycloak and JDBC Ping

Monday, August 12 2019, posted by Sebastian Łaskaiwec

A few months back, we had a great article about clustering using JDBC_PING protocol. Since then, we introduced some improvements for the Keycloak container image that can simplify the setup. So, before diving into this blog post, I highly encourage you to visit the Keycloak Cluster Setup article.

What has changed in our Container Image?

Probably the most important change is configuring the JGroups discovery protocol by using variables (see the Pull Request). Once the change got in, we could configure the JGroups discovery by setting two properties:

  • JGROUPS_DISCOVERY_PROTOCOL
  • JGROUPS_DISCOVERY_PROPERTIES

Let's apply the changes, shall we...

The JDBC_PING-based setup works fine in all scenarios, where we connect all Keyclaok instances to the same database. Since JDBC_PING can be configured to obtain a database connection using JNDI binding, it can easily connect to the Keycloak database. All we need to do is to add two parameters to our docker image:

  • JGROUPS_DISCOVERY_PROTOCOL=JDBC_PING
  • JGROUPS_DISCOVERY_PROPERTIES=datasource_jndi_name=java:jboss/datasources/KeycloakDS

You may find an end-to-end scenario here.

Additional configuration

In some scenarios, you may need additional configuration. All additional settings might be added to the JGROUPS_DISCOVERY_PROPERTIES. Here are some hints and common problems, that you may find:

Problem description Possible solution
The initialization SQL needs to be adjusted In this case, you might want to look at initialize_sql JDBC_PING property
When Keycloak crashes, the database is not cleared Turn remove_old_coords_on_view_change property on
When Keycloak crashes, the database is not cleared Also, when a cluster is not too large, you may turn the remove_all_data_on_view_change property on
Sometimes, Keycloak doesn't write its data into the database You may lower the info_writer_sleep_time and info_writer_max_writes_after_view property values


Haven fun and don't forget to let us know what you think about this blog post using the User Mailing List.
Sebastian Łaskawiec and the Keycloak Team