Belajar Keycloak - High Availability & Clustering

#Pendahuluan

Di episode 26 kalian mengelola klien dalam jumlah besar. Episode 27 ini menyelesaikan pertanyaan terakhir sebelum production: bagaimana kalau satu server mati? High availability (HA) & clustering memastikan layanan autentikasi tetap berjalan meski satu node turun. Ini materi yang membedakan setup lab dari deployment yang benar-benar dipakai pengguna.

#Konsep Clustering

Keycloak dirancang untuk berjalan sebagai cluster: beberapa instance Keycloak berbagi satu database, saling berbagi cache, dan dilayani lewat satu pintu masuk. Konsep dasarnya:

• Active-active clustering — semua node melayani permintaan secara bersamaan; tidak ada node "pengangguran".
• Distributed cache (Infinispan) — cache Keycloak berjalan di atas Infinispan embedded dan di-sinkronkan antar node lewat JGroups.
• Session replication — sesi user dibagikan antar node, sehingga request berikutnya bisa dilayani node mana pun.
• Load distribution — permintaan disebar merata oleh load balancer.

Mengapa tidak cukup satu node? Karena satu instance adalah single point of failure: apapun penyebabnya — crash, pemeliharaan, atau jaringan — seluruh login terhenti. Perbandingan topologi yang umum:

#Setup Cluster

Memulai cluster Keycloak berarti menjalankan instance identik yang saling mengenal. Langkah wajibnya:

1. Multiple instances — jalankan dua node Keycloak atau lebih, idealnya di availability zone berbeda.
2. Shared database — semua node harus menunjuk database yang sama. Tanpa ini, data user dan sesi tidak konsisten.
3. Cache replication — node berkomunikasi lewat JGroups untuk menyinkronkan cache Infinispan.
4. Discovery mechanism — node harus menemukan satu sama lain; KC_CACHE_STACK menentukan metode penemuan sesuai lingkungan.

#Discovery Mechanisms

Setiap lingkungan punya cara yang berbeda untuk membuat node saling mengenal. Di AWS, gunakan stack ec2 yang memakai penemuan berbasis S3:

kc.sh start --cache-stack ec2

KC_CACHE_STACK=ec2 mengonfigurasi JGroups agar node di region yang sama saling menemukan dan membentuk cluster otomatis. Di Kubernetes, gunakan stack kubernetes yang memanfaatkan DNS-based discovery. Di jaringan datacenter biasa, mode default berbasis multicast biasanya sudah cukup. Pilih stack sesuai tempat Keycloak berjalan — jangan memaksakan metode AWS di lingkungan lain.

#Load Balancing

Di depan cluster dipasang load balancer. Dua keputusan penting:

• Sticky sessions vs session replication — dengan session replication aktif, load balancer tidak perlu menempelkan user ke node tertentu; sesi bisa dilayani node mana pun. Tanpa replication, sticky session menjadi wajib dan sebuah node yang mati akan menggugurkan semua sesi yang menempel padanya.
• Health checks — load balancer harus tahu node mana yang sehat lewat endpoint /health/ready (kesiapan melayani), /health/live (proses hidup), dan /health/started (startup selesai). Node yang tidak sehat harus dikeluarkan dari rotasi.

Contoh konfigurasi NGINX:

Load balancing NGINX dengan health check

upstream keycloak {
    server kc-01.example.com:8080;
    server kc-02.example.com:8080;
}
 
server {
    listen 443 ssl;
    server_name sso.example.com;
 
    location / {
        proxy_pass http://keycloak;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Header proxy — X-Forwarded-For dan X-Forwarded-Proto — harus diteruskan dengan benar, karena Keycloak memakainya untuk membangun URL dan memproses IP (ingat episode 24). SSL termination di load balancer juga umum: Keycloak melihat koneksi plaintext dari proxy, sehingga pastikan --proxy-headers sudah diatur agar tautan HTTPS tetap benar.

#Database Considerations

Database adalah titik paling sensitif di cluster:

• Database clustering — jalankan database yang high availability (replikasi, failover) karena ia titik tunggal yang sebenarnya.
• Connection pooling — atur ukuran pool sesuai jumlah node: terlalu kecil menyebabkan antrean, terlalu besar membebani database.
• Read replicas — bisa menurunkan beban baca, tetapi sesi dan data yang sedang ditulis tetap harus ke primary; jangan pernah melayani data sesi dari replica yang tertinggal.
• Database performance — karena semua node berbagi database, latensi dan tuning SQL berdampak langsung ke seluruh cluster.

Ingat dari episode 28 yang akan datang: semakin besar beban, semakin besar pula peran tuning database pool dan cache. Clustering menambah node, tetapi database tetap satu — ia yang paling sering menjadi bottleneck sebenarnya.

Database yang dipakai semua node juga perlu perhatian pada connection timeout dan koneksi idle: node yang sedang diam tetap memegang koneksi dari pool. Atur masa hidup koneksi dan batas idle agar node yang baru bergabung tidak kesulitan mendapat slot di tengah lonjakan.

#Testing HA

Cluster yang tidak diuji bukan high availability. Rutinitas wajib:

• Failover testing — matikan satu node secara sengaja, pastikan user yang sedang login tidak kehilangan sesi dan permintaan tetap dilayani.
• Load testing — naikkan beban bertahap, pastikan node baru masuk tanpa gangguan dan respons tetap stabil.
• Disaster recovery drills — simulasikan kegagalan total satu region; ukur berapa lama layanan pulih dan berapa banyak data yang hilang (RTO dan RPO dibahas detail di episode 29).

#Penutup

Episode 27 membawa Keycloak ke arsitektur enterprise: active-active clustering dengan Infinispan sebagai distributed cache, shared database, discovery antar node lewat KC_CACHE_STACK, load balancing dengan health checks, pertimbangan database, dan pengujian failover yang rutin.

Inti yang harus dibawa pulang:

• Database adalah titik tunggal yang sebenarnya — cluster Keycloak tidak menyelamatkan kalian jika database tidak HA.
• Session replication membebaskan load balancer — tanpa itu, sticky session menjadi wajib dan penuh risiko.
• Health checks adalah mata load balancer — pastikan /health/ready dipakai untuk keputusan routing.
• Cluster harus diuji gagal — failover, load, dan DR drills adalah bagian dari operasional.

Di episode 28 berikutnya, kalian mengoptimalkan kinerja cluster tersebut: performance tuning & monitoring — dari JVM, cache, hingga metrik Prometheus dan dashboard Grafana.