How-to: Implement Keycloak Load Balancing Across Multiple UCS Backup Nodes

Knowledge Base Community
, , , ,
1

Howto:

Implement Keycloak Load Balancing Across Multiple UCS Backup Nodes (BDN)

When deploying Keycloak across multiple Univention Corporate Server (UCS) Backup Domain Nodes (BDN) with a multi-node database cluster, maintaining a unified logical configuration across all Keycloak instances is essential. Because Keycloak requires identical database and LDAP configuration parameters across nodes, node-specific routing must be resolved via custom host-to-IP mappings.

Standard modifications to the host system’s /etc/hosts file do not propagate into Docker containers. Furthermore, direct edits to the /etc/hosts file within a Docker container are volatile and reset upon every container restart or removal.

This article provides a step-by-step guide to configuring node-specific IP mappings using Docker Compose overrides in UCS. This approach ensures an update-safe, persistent, and long-term consistent load-balancing architecture.

Architectural Approach

To prevent manual, volatile edits to /etc/hosts after every container restart, Docker Compose supports overriding the primary configuration with a local override file (docker-compose.override.yml). The Univention App Center automatically detects, merges, and applies this override file when generating the container runtime configuration.

1. Navigate to the Compose Directory

Access the directory where the Univention App Center manages the Docker Compose configuration files for the Keycloak application:

cd /var/lib/univention-appcenter/apps/keycloak/compose/

2. Create the Override File

Create a new configuration file to hold local, node-specific customizations:

nano docker-compose.override.yml

3. Define Custom IP Mappings

Configure the node-specific IP addresses and DNS names for the respective BDN node.

Important: Ensure strict adherence to YAML indentation standards using spaces (do not use tabs).

services:
  keycloak:
    extra_hosts:
      - "your-database-dns-name.internal:xxx.xxx.xxx.xxx"
      - "your-ldap-dns-name.internal:xxx.xxx.xxx.xxx"

4. Reinitialize the Container Environment

To instruct the Univention App Center to read the new override file, regenerate the runtime configuration, and rebuild the container instance, execute the following command:

univention-app reinitialize keycloak

5. Verify the Configuration

After the container has restarted, verify that the host entries have been successfully injected into the container’s runtime environment:

docker exec -it keycloak cat /etc/hosts

Expected Output (Example):

127.0.0.1       localhost
::1             localhost ip6-localhost ip6-loopback
fe00::0         ip6-localnet
ff00::0         ip6-mcastprefix
ff02::1         ip6-allnodes
ff02::2         ip6-allrouters
192.168.1.51    your-database-dns-name.internal
192.168.1.101   your-ldap-dns-name.internal
172.16.1.2      4642f3a2a809

Note: The manually defined host entries must appear near the end of the file, preceding the dynamic container IP assignment.

Key Benefits of This Architecture

  • Update-Safe (Upgrade Persistence): During Keycloak app upgrades via the Univention App Center, the official docker-compose.yml file is overwritten. Because docker-compose.override.yml is not part of the standard application package, it remains untouched and is automatically re-merged during post-upgrade startup.
  • Centralized & Consistent Administration: The logical configuration (DNS names) in Keycloak remains completely identical across all nodes, while physical network routing is cleanly encapsulated per node at the container orchestration level.
1 Like