How to Build a Production-Ready High-Availability Keycloak Cluster

In modern microservice and cloud‑native environments, a unified and secure Identity and Access Management (IAM) solution is essential; Keycloak provides a powerful open‑source option with flexible protocol support and an extensible architecture.

Architecture Design: Core Elements

Multi‑instance Cluster : Deploy at least two Keycloak instances behind a load balancer (e.g., Nginx or HAProxy) for traffic distribution and failover.

External Database : Store users, clients, and roles in a high‑availability external database such as PostgreSQL or MySQL instead of the default embedded H2.

Distributed Session Management : Use Infinispan as a distributed cache and JGroups for node communication, enabling shared session state across Keycloak instances.

Reverse Proxy & TLS Termination : Place Nginx or HAProxy in front to handle HTTPS termination and forward traffic to the backend Keycloak nodes.

Deployment Practice: Key Steps & Configuration

The production‑grade setup uses four servers: two for Keycloak and two for HAProxy load balancing. Below is a simplified Docker‑Compose example illustrating the core components.

# Create directory for certificates
sudo mkdir -p /app/keycloak/certs
sudo chown -R ops. /app/keycloak
cd /app/keycloak/certs/

# CA certificate
openssl req -newkey rsa:2048 -x509 -nodes -keyout ca.key -out ca.crt -days 3650 -subj "/CN=CA"

# Service certificate
openssl genrsa -out server.key 2048
openssl req -new -key server.key -out server.csr -subj "/C=CN/O=jiaxzeng/CN=keycloak.jiaxzeng.com"
openssl x509 -req -CA ca.crt -CAkey ca.key -in server.csr -out server.crt -CAcreateserial -days 3650 -extfile <(printf "subjectAltName=IP:127.0.0.1,IP:172.139.x.x,DNS:localhost,DNS:keycloak.jiaxzeng.com")

$ createuser -h 172.139.x.x -p 9999 -U postgres -W sso -P
Enter password for new role:
Enter it again:
Password:

$ createdb -h 172.139.x.x -p 9999 -O sso -U postgres -W keycloak
Password:

services:
  keycloak:
    container_name: keycloak
    image: quay.io/keycloak/keycloak:26.4
    environment:
      # Admin credentials
      KC_BOOTSTRAP_ADMIN_USERNAME: admin
      KC_BOOTSTRAP_ADMIN_PASSWORD: admin
      # Database configuration
      KC_DB: postgres
      KC_DB_URL: jdbc:postgresql://172.139.x.x:9999/keycloak?serverTimezone=Asia/Shanghai
      KC_DB_USERNAME: sso
      KC_DB_PASSWORD: xxx
      # HTTPS configuration
      KC_HTTPS_CERTIFICATE_FILE: /tmp/ssl/server.crt
      KC_HTTPS_CERTIFICATE_KEY_FILE: /tmp/ssl/server.key
      # HTTP configuration
      KC_HOSTNAME_STRICT: "false"
      KC_PROXY_HEADERS: forwarded
      KC_HTTP_ENABLED: "true"
      KC_HTTP_PORT: 18080
      KC_PROXY_TRUSTED_ADDRESSES: "172.139.x.x,172.139.x.x"
      KC_HTTP_MANAGEMENT_PORT: 19000
      KC_HEALTH_ENABLED: "true"
      KC_METRICS_ENABLED: "true"
      # Java options
      JAVA_OPTS_APPEND: '-Djgroups.bind.address=172.139.x.x'
    volumes:
      - ./certs:/tmp/ssl
    command: ["start"]
    network_mode: host

HAProxy Reverse Proxy Configuration

frontend keycloak_frontend
  bind *:18443 ssl crt /etc/haproxy/certs/keycloak.pem
  mode http
  http-request set-header Forwarded "for=%[src];host=%[req.hdr(host)];proto=https"
  acl is_public path_beg /realms/ /resources/
  use_backend keycloak_server if is_public

backend keycloak_server
  mode http
  server kc01 172.139.x.x:18080 maxconn 32 check
  server kc02 172.139.x.x:18080 maxconn 32 check

After configuring HAProxy, restart it to apply the changes.

Problem Background

Deploying a production‑grade, highly available Keycloak cluster goes beyond simply launching containers; it requires a deep understanding of its components—database, cache, instances—and careful configuration to eliminate all single points of failure. This guide aims to provide a practical reference for engineers undertaking such deployments.