Architecting Highly Available Keycloak Access Gateways Across Multi-Region Kubernetes Fleets

Key points

1. Use a shared database. Keycloak instances in multiple regions must connect to a replicated PostgreSQL cluster.
2. Enable Infinispan clustering. Keycloak uses Infinispan for sessions and caches; configure cross-site replication.
3. Deploy behind a global load balancer. Route users to the nearest region with health checks and failover.
4. Handle session affinity. Sticky sessions reduce cross-region traffic but complicate failover; use replicated sessions instead.
5. Tune cache invalidation. Cross-region cache invalidation adds latency; set appropriate TTLs.
6. Monitor replication lag. Database and cache replication lag affects login consistency.
7. Plan for split-brain. Network partitions between regions can cause conflicting writes; use quorum-based databases.
8. Test failover. Simulate a region failure and verify logins continue with acceptable latency.

Architecture

Each region runs a Keycloak pod connected to a replicated PostgreSQL database. Infinispan replicates sessions across regions. A global load balancer routes to the nearest healthy instance. Database replication uses streaming replication with a primary and standbys.

Production configuration

apiVersion: apps/v1
kind: Deployment
metadata:
  name: keycloak
spec:
  replicas: 3
  template:
    spec:
      containers:
      - name: keycloak
        image: quay.io/keycloak/keycloak:25.0
        env:
        - name: KC_DB
          value: postgres
        - name: KC_DB_URL
          value: jdbc:postgresql://pg-primary:5432/keycloak
        - name: KC_CACHE
          value: ispn
        - name: KC_CACHE_STACK
          value: kubernetes
        args: ["start", "--optimized"]
        resources:
          requests:
            memory: 1Gi
            cpu: 500m

cache:
  stack: kubernetes
  remoteCache:
    host: keycloak-remote.example.com
    port: 11222
  sessions:
    owners: 2
    backups: 1
  loginFailures:
    owners: 1
    backups: 0

kubectl get pods -l app=keycloak
kubectl logs -l app=keycloak | grep -i 'cluster\|infinispan'
# test failover
curl -s https://auth.example.com/health/ready
# simulate region failure
kubectl scale deployment keycloak --replicas=0 -n region-1

Edge cases from production

• Cross-region database replication adds write latency; consider read replicas for read-heavy workloads.
• Infinispan split-brain can cause session loss; configure merge policies carefully.
• Global load balancer health checks must account for Keycloak startup time, which is slow.
• Token refresh storms after a failover can overwhelm the surviving region.

Frequently asked questions