Keycloak can be deployed in a number of high-availability architectures, allowing system administrators to pick the deployment type most suitable for their needs. Ease of deployment, cost and fault-tolerance guarantees are important considerations when determining the correct architecture for your deployments.
Keycloak provides capabilities that can be used as building blocks for highly available deployments. This guide describes those capabilities, their configuration requirements, expected product behavior, and important trade-offs.
High availability depends on components outside Keycloak, including the database, networking, load balancing, compute/platform infrastructure, and operational failover procedures. Keycloak itself must be deployed on a platform, JVM and database covered by the Supported Configurations.
Deployers are responsible for designing, validating, and operating their end-to-end HA architecture and for verifying that it meets their required availability, RTO, and RPO objectives.
Deploy Keycloak in a single cluster, optionally across multiple availability-zones or data centers with the required network latency and database configuration, using Single-cluster deployments.
No external dependencies
Deployment in a single Kubernetes cluster or a set of virtual machines with transparent networking
Tolerate availability-zone failure or data center failure, if deployed to multiple availability zones or data centers
Kubernetes cluster is a single point of failure:
Control-plane failures could impact all Keycloak pods
Connect two or more Keycloak clusters without an external Infinispan cluster using Multi-cluster deployments (v2).
Tolerate availability-zone failure
Tolerate cluster failure
Simpler architecture: no external Infinispan cluster required
No requirement for a specific environment such as Kubernetes or AWS
Complexity:
External load-balancer required
Cost:
Additional load-balancer required
Two or more independent deployment environments must be operated. On Kubernetes, this normally means multiple Kubernetes clusters/control planes.
Higher database load as session data is stored in the database and less data is cached. You might see approximately twice the CPU usage and write IOPS on your database, though your results might vary based on your use case.
Multi-cluster v1 (the multi-site feature) is deprecated and will be removed in a future release. Use Multi-cluster deployments (v2) instead. See Migrating from multi-cluster v1 to v2 for migration instructions.
|
Connect two Keycloak clusters deployed for example in different Kubernetes clusters in two availability zones or data centers with the required network latency and database configuration using Multi-cluster deployments (v1).
Tolerate availability-zone failure
Tolerate Kubernetes cluster failure
Bridge two networks that do not offer transparent networking
Regulatory compliance when distinct deployments are required
Complexity:
External load-balancer required
Separate Infinispan cluster required on each site
Cost:
Additional load-balancer required
Additional compute is required for external Infinispan clusters
Two Kubernetes control-planes must be provisioned
Not supported with three or more availability zones
Use the following comparison to decide between a single-cluster and a multi-cluster (v2) setup.
| Multi-cluster (v1) is deprecated and will be removed in a future major release stream of Keycloak. |
| Single cluster | Multi-cluster (v2) / Stateless | |
|---|---|---|
Keycloak topology |
One Keycloak cluster |
2+ independent Keycloak clusters |
Typical use |
One platform/network, optionally stretched across availability zones or data centers. |
Independent sites/clusters requiring site-level isolation |
User session state |
Database |
Database |
Authentication sessions and tokens |
In-Memory |
Database |
Networking |
Transparent between Keycloak members |
No transparent network required between sites |
Database |
Synchronously replicated DB |
Synchronously replicated DB |
External LB |
Depends on deployment; usually included in an Kubernetes platform. |
Required |
|