Problem: Keycloak Upgrade Fails Due to Incorrect PostgreSQL Version Detection in Multi Node Environments

Problem

When upgrading the Keycloak app on a UCS Backup node, the process fails due to an incorrect detection of the PostgreSQL version. The system reports that PostgreSQL 11 is in use, even though Keycloak is actively connected to a PostgreSQL 15 database on the Backup node.

This issue occurs in scenarios where Keycloak was previously installed and removed from the Primary node, and later installed and configured on the Backup node. The upgrade script does not correctly detect the active domain wide Keycloak database instance and instead assumes the local PostgreSQL installation on the Primary is relevant.

Error Message

During the upgrade, the following message is shown:

It seems you are using Postgres 11 as the database management system for Keycloak.

Starting with Keycloak 26, at least Postgres 12 is required.

Please update Postgres. You may want to follow this article: https://help.univention.com/t/updating-from-postgresql-11-to-postgresql-15/22162

You can skip this test by setting the UCR variable "keycloak/check-postgres-version" to "false".

But be aware that Keycloak 26 will not work with PostgreSQL 11.

Running prescript of 5.0/keycloak=26.1.4-ucs2 failed. Aborting...

Environment

  • UCS domain with multiple nodes (Primary and Backup)
  • Keycloak installed and actively used on a Backup node
  • PostgreSQL 15 in use on the Backup node (where Keycloak is installed)
  • PostgreSQL 11 still present on the Primary node (unused)
  • Keycloak upgrade to version 26.1.4-ucs2 fails

Root Cause

After initial installation the Keycloak app may leave behind configuration entries on the Primary node even if it has been uninstalled there. As documented in the Keycloak app guide under After Initial Installation, the upgrade script uses the saved database host setting without verifying that it points to the actual active instance. This leads to the version check targeting an outdated local database rather than the live domain wide database on the Backup node.

See official documentation for details 6. Database configuration — Univention Keycloak app manual 26.2.5
and
Bug 58451

Solution

Before proceeding with the upgrade, verify which node hosts the active PostgreSQL database for Keycloak. On that system, ensure that the PostgreSQL version is 12 or higher.

You can inspect the currently running PostgreSQL versions on each node using the following command:

pg_lsclusters -h

Typical output for an active system using PostgreSQL 15:

15 main 5432 online postgres /var/lib/postgresql/15/main /var/log/postgresql/postgresql-15-main.log

If the active database is already running PostgreSQL 12 or higher, and the upgrade script still blocks the process, you may bypass the version check by temporarily setting the following UCR variable:

ucr set keycloak/check-postgres-version=false

:warning: Important: This override should only be used if you have confirmed that the actual Keycloak database is not running on an unsupported version. Using Keycloak 26 with PostgreSQL 11 is not supported and will lead to failures.

Related Documentation

For instructions on upgrading PostgreSQL from version 11 to 15, please refer to the official Univention article:

Updating from PostgreSQL 11 to PostgreSQL 15

Recommendation

Univention recommends verifying the active database backend configuration for Keycloak prior to upgrading. In multi node UCS environments, administrators should ensure that the upgrade checks reflect the actual database usage and not outdated or unused local installations.