우분투 24.04에서 Keycloak HA 클러스터를 구성하는 방법

우분투 24.04에서 Keycloak을 3개의 노드로 HA 구성하는 방법

테스트 환경

운영체제 정보

$ lsb_release -d
Description:	Ubuntu 24.04.1 LTS

Keycloak HA 아키텍처 다이어그램

다이어그램

1. 사전 준비 (전체 노드 공통)

hosts 파일 설정

cat <<EOF >> /etc/hosts

##### Keycloak
192.168.10.101 cb1
192.168.10.102 cb2
192.168.10.103 cb3
EOF

팰수 패키지 설치

sudo apt install -y unzip curl wget gnupg2 software-properties-common

Java 21 설치

sudo apt install -y openjdk-21-jdk

java -version

openjdk version "21.0.10" 2026-01-20
OpenJDK Runtime Environment (build 21.0.10+7-Ubuntu-124.04)
OpenJDK 64-Bit Server VM (build 21.0.10+7-Ubuntu-124.04, mixed mode, sharing)

2. PostgreSQL 구성 (cb1 또는 별도 서버에 설치)

apt install -y postgresql postgresql-contrib

DB 및 유저 생성

sudo -u postgres psql <<EOF
CREATE USER keycloak WITH PASSWORD 'keycloak_pass';
CREATE DATABASE keycloak OWNER keycloak;
GRANT ALL PRIVILEGES ON DATABASE keycloak TO keycloak;
EOF

외부 접속 허용

• 설정 파일 수정 (postgresql.conf)

sudo vim /etc/postgresql/*/main/postgresql.conf

listen_addresses = '*'

• 접근 제어 파일 수정 (pg_hba.conf)

sudo vim /etc/postgresql/*/main/pg_hba.conf

# IPv4 local connections:
host    all             all             0.0.0.0/0		        scram-sha-256

서비스 재시작

systemctl restart postgresql

서비스 상태

systemctl status postgresql

접속 테스트

psql -h 192.168.10.101 -U keycloak -d keycloak -c "\l"

3. Keycloak 설치 (cb1, cb2, cb3 동일 반복)

useradd -r -s /sbin/nologin keycloak
chown -R keycloak:keycloak /opt/keycloak

wget https://github.com/keycloak/keycloak/releases/download/26.6.0/keycloak-26.6.0.tar.gz
tar -xzf keycloak-26.6.0.tar.gz -C /opt/

ln -s /opt/keycloak-26.6.0 /opt/keycloak
chown -R keycloak:keycloak /opt/keycloak

data/tmp 디렉토리 생성

mkdir -p /opt/keycloak/data/tmp
chown -R keycloak:keycloak /opt/keycloak/data/tmp

4. Keycloak 설정

각 노드별로 KC_HOSTNAME과 jgroups.bind.address 만 IP 변경

sudo vim /opt/keycloak/conf/keycloak.conf

# DB 설정
db=postgres
db-username=keycloak
db-password=keycloak_pass
db-url=jdbc:postgresql://192.168.10.101:5432/keycloak

# 프록시 설정
proxy=edge
http-enabled=true
http-port=8080

# 호스트명 (LB의 공인 도메인)
hostname=https://keycloak.scbyun.com
hostname-strict=false

# 클러스터링
cache=ispn
cache-stack=tcp

5. JGroups 클러스터 설정 (핵심)

Keycloak은 내부적으로 Infinispan + JGroups로 세션을 클러스터링합니다.

JDBC_PING을 사용하면 별도 멀티캐스트 없이 DB를 통해 노드를 발견합니다.

sudo vim /opt/keycloak/conf/cache-ispn.xml

<infinispan>
  <jgroups>
    <stack name="jdbc-ping-tcp" extends="tcp">
      <JDBC_PING
        connection_url="jdbc:postgresql://192.168.10.101:5432/keycloak"
        connection_username="keycloak"
        connection_password="keycloak_pass"
        connection_driver="org.postgresql.Driver"
        initialize_sql="CREATE TABLE IF NOT EXISTS JGROUPSPING (own_addr VARCHAR(200) NOT NULL, cluster_name VARCHAR(200) NOT NULL, ping_data BYTEA, constraint PK_JGROUPSPING PRIMARY KEY (own_addr, cluster_name))"
        insert_single_sql="INSERT INTO JGROUPSPING (own_addr, cluster_name, ping_data) VALUES (?, ?, ?)"
        delete_single_sql="DELETE FROM JGROUPSPING WHERE own_addr=? AND cluster_name=?"
        select_all_pingdata_sql="SELECT ping_data FROM JGROUPSPING WHERE cluster_name=?"
        stack.combine="REPLACE"
        stack.position="MPING"/>
    </stack>
  </jgroups>
  <cache-container name="keycloak">
    <transport lock-timeout="60000" stack="jdbc-ping-tcp"/>
    <!-- 이하 기본 캐시 설정 유지 -->
  </cache-container>
</infinispan>

그리고 keycloak.conf에 추가

sudo vim /opt/keycloak/conf/keycloak.conf

cache-config-file=cache-ispn.xml

6. systemd 서비스 등록

sudo vim /etc/systemd/system/keycloak.service

[Unit]
Description=Keycloak Identity and Access Management
After=network.target

[Service]
User=keycloak
Group=keycloak
WorkingDirectory=/opt/keycloak

Environment="JAVA_OPTS_APPEND=-Xms512m -Xmx2g -Djgroups.bind.address=192.168.10.101"

ExecStart=/opt/keycloak/bin/kc.sh start
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

jgroups.bind.address는 각 노드 IP로 변경 (cb2 → 192.168.10.102, cb3 → 192.168.10.103)

systemctl daemon-reload
systemctl enable --now keycloak

로그 확인

journalctl -u keycloak -f

• 상세 로그 확인

journalctl -u keycloak -n 100 --no-pager

• 또는 직접 build 실행해서 에러 바로 확인

sudo -u keycloak /opt/keycloak/bin/kc.sh build 2>&1

7. HAProxy 로드밸런서 설정(cb1 또는 별도 서버에 설치)

apt install -y haproxy

haproxy -v

HAProxy version 2.8.16-0ubuntu0.24.04.1 2025/12/03 - https://haproxy.org/
Status: long-term supported branch - will stop receiving fixes around Q2 2028.
Known bugs: http://www.haproxy.org/bugs/bugs-2.8.16.html
Running on: Linux 6.8.0-107-generic #107-Ubuntu SMP PREEMPT_DYNAMIC Fri Mar 13 19:51:50 UTC 2026 x86_64

HAProxy 설정

sudo vim /etc/haproxy/haproxy.cfg

frontend keycloak_front
    bind *:443 ssl crt /etc/haproxy/keycloak.pem
    default_backend keycloak_back

backend keycloak_back
    balance leastconn
    option httpchk GET /health/ready
    http-check expect status 200
    cookie KC_SESSION insert indirect nocache
    server cb1 192.168.10.101:8080 check cookie cb1
    server cb2 192.168.10.102:8080 check cookie cb2
    server cb3 192.168.10.103:8080 check cookie cb3

systemctl restart haproxy

8. 클러스터 확인

Keycloak 헬스체크

curl http://192.168.10.101:8080/health/ready
curl http://192.168.10.102:8080/health/ready
curl http://192.168.10.103:8080/health/ready

클러스터 멤버 확인 (Keycloak 로그에서)

journalctl -u keycloak -f | grep "GMS: received view"