Keycloak single-cluster vs multi-cluster: which high availability design fits your estate
If your identity service must stay up across availability zones or sites, the first decision is whether all your Keycloak nodes can sit on one low-latency network. Keycloak's single-cluster design suits that case: one cluster spread across zones, with a round-trip latency of less than 10 ms between Keycloak instances. The tested reference is 6 pods across 3 availability zones in one AWS region, each limited to 40 vCPU and 8 GB of memory, with Amazon Aurora PostgreSQL 17.5 replicating synchronously across zones. If your sites cannot share that network, the multi-cluster v2 design is the one to evaluate. It links independent Keycloak deployments through the embedded Infinispan caches, without an external Infinispan cluster, and it requires a highly available database with synchronous replication and a commit latency below 10 ms (with below 5 ms suggested).
The trade-off is load and recovery time. Multi-cluster v2 needs an external load balancer that routes requests between clusters and probes their availability, and every node must keep an NTP-synchronized clock, because clock skew over 10 seconds between clusters can stop cache invalidation messages. The guide also warns that some failure scenarios cause several minutes of downtime, depending on the database, load balancer and Keycloak settings, and that Keycloak detects a failed node within one minute by default. Before you commit, ask your database team to measure commit latency between sites, and run a failover test that a stakeholder has agreed to in writing.
Multi-cluster v1, which needs a separate Infinispan cluster per site, is deprecated and will be removed in a future release, so do not build new sites on it. Plan a migration if you run it today. The Keycloak high availability overview recommends v2 for multiple sites and estimates that multi-cluster roughly doubles database CPU and write IOPS, so size the database before you choose. Remember that the project places responsibility for designing, validating and operating the end-to-end architecture on your team.
How the two Keycloak high availability designs compare
This table compares the single-cluster design, spread across availability zones in one region, with the multi-cluster v2 design that links independent sites. Read each row as a question to answer for your own network, database and failure model before choosing. The main takeaway is that latency and database commit time decide which design is even possible, and the failover and database load rows decide whether it is worth the complexity.
| Factor | Single cluster across availability zones | Multi-cluster v2 |
|---|---|---|
| Network and latency | Round-trip latency under 10 ms between Keycloak instances, with transparent networking such as one Kubernetes cluster in one region | Sites can be farther apart, but the design still needs a highly available database with synchronous replication and a low commit latency |
| Database requirement | Synchronously replicated database; the tested reference uses Amazon Aurora PostgreSQL 17.5 replicating synchronously across zones | Highly available database with synchronous replication; a commit latency below 5 ms is suggested and below 10 ms is required |
| External Infinispan | Not needed; instances form one cluster | Not needed; v2 links deployments through the embedded Infinispan caches. The older v1 design needed a separate Infinispan cluster per site and is deprecated |
| Load balancer role | Routes requests across instances in the cluster | An external load balancer must balance requests between clusters and probe their availability |
| Clock requirement | Keep node clocks synchronized with NTP as a standard operating practice; confirm the tolerance in your environment | NTP-synchronized clocks are required; skew over 10 seconds between clusters can stop cache invalidation messages |
| Tested sizing reference | Six pods across three availability zones in one AWS region, each limited to 40 vCPU and 8 GB memory, tested at 1,000,000 users and 300 requests per second | No equivalent reference figures are documented in the guide; ask Keycloak or your partner for a load test on your own topology |
| Failover behavior | Keycloak detects a failed node within one minute by default; confirm recovery time for your zone-loss scenario | Some failure scenarios can cause several minutes of downtime, depending on database, load balancer and Keycloak configuration |
| Database load | Adds the write load of one cluster; test under your own peak | Estimated by the Keycloak HA overview to roughly double database CPU and write IOPS; size the database before committing |
| Confirm in your environment | Measured latency between zones, database replication behavior and failover drills | Measured inter-site latency, commit latency, NTP drift, load balancer health checks and database capacity |
What each design is made of
Both Keycloak high availability designs share the same core: Keycloak nodes, a synchronously replicated database and a clock discipline that keeps nodes in agreement. They differ in how sites are joined, which adds an external load balancer and cache messaging across sites in v2, and a separate Infinispan cluster in the deprecated v1 design. Read each card as a responsibility you must assign, not a product you can leave to defaults.
Keycloak nodes and pods
These are the running Keycloak instances that serve logins, token requests and admin traffic. In the single-cluster design they sit in one network with transparent connectivity, and the tested reference spreads six pods across three availability zones. Your team decides node count, per-node CPU and memory limits, and how pods are scheduled across zones. Check that every node can reach every other node with round-trip latency under 10 ms, because the single-cluster guide sets that as a requirement.
Synchronously replicated database
Keycloak stores realms, users, clients and sessions in a relational database, and both supported high availability designs require synchronous replication. A replica that lags behind can return stale state after failover, so the database is the first place to validate a design. Confirm that your engine and version are on the supported list, that replication is synchronous across the zones or sites you choose, and that a commit latency target is measured in your environment, not assumed. Database licensing and hosting costs are usually the largest recurring line item.
Embedded Infinispan caches
Keycloak uses Infinispan caches for sessions and other shared state. In the single-cluster design, these caches run across the Keycloak nodes in one network. In v2 multi-cluster, the same embedded caches link independent deployments without a separate Infinispan cluster, which keeps the topology simpler but means cache invalidation messages now cross sites. Plan for cache behavior during a node or site loss, and test session survival rather than assuming it. Ask your vendor or your own test results to confirm how sessions behave in each failure you rehearse.
External load balancer in v2
Multi-cluster v2 requires an external load balancer that spreads requests across clusters and probes each cluster's availability. This component is not provided by Keycloak, so its health check settings, failover rules and TLS termination are design decisions your team owns. The v2 guide warns that some failure scenarios can cause several minutes of downtime depending on the database, load balancer and Keycloak configuration. Rehearse a site loss with the load balancer in the loop, and record how long it takes users to recover.
NTP-synchronized clocks
Every node in a v2 multi-cluster deployment needs a clock synchronized through NTP. The v2 guide states that clock skew above 10 seconds between clusters can stop cache invalidation messages from being processed, which quietly leaves stale data in place. Clock drift is often invisible until an incident, so add time-sync monitoring to the same dashboard as node health. Confirm the time source your platform uses and who owns it in your change process.
Separate Infinispan cluster in v1
The deprecated multi-cluster v1 design requires a separate Infinispan cluster per site, which adds a second stateful system to build, patch and monitor. Keycloak's high availability overview recommends v2 and estimates that multi-cluster roughly doubles database CPU and write IOPS, so the database budget also changes. If you already run v1, plan a migration path before the design is removed in a future release. Ask your implementation partner to scope that migration as its own deliverable with written acceptance tests.
How latency and database replication shape the single-cluster build
The single-cluster design only works when the network behaves like one site. Keycloak's single-cluster guide assumes transparent networking, such as a single Kubernetes cluster inside one AWS Region or an equivalent low-latency setup, and it requires a round-trip latency of less than 10 ms between Keycloak instances. If your pods, database and load balancer span sites with a slower or less predictable link, you are no longer building this topology. Measure round-trip time between every zone you plan to use before you commit, and check it again after any network change, since the requirement applies to the path your cache traffic actually takes.
Keycloak's tested reference is 6 pods across 3 availability zones in one AWS region, each limited to 40 vCPU and 8 GB of memory, regularly tested at 1,000,000 users and 300 requests per second. The database was Amazon Aurora PostgreSQL 17.5 replicating synchronously across zones, which is the part to copy most carefully. Synchronous replication means every write waits for confirmation across zones, so database commit latency becomes part of every login and session update. Treat this as a reference point, not a sizing promise for your workload. Your user count, session profile, token lifetimes, federation volume and peak request rate will differ, so run a load test against your own data and measure p95 login latency, database write latency and failover time before you choose pod counts.
Ask your database team to confirm three things in your environment: that the replica in each zone is synchronous rather than asynchronous, that commit latency stays within the bounds the guide describes, and how the database behaves when one zone is lost. Then rehearse a zone failure with real traffic and record how long sessions take to recover. Your results, not the reference figures, should set the pod limits and the database tier.
How to choose and validate the design before go-live
This sequence turns the single-cluster or multi-cluster choice into a measured decision, then proves with load and failure tests that the chosen design meets your users, latency budget and downtime tolerance before production traffic arrives.
Measure inter-site and database latency
Your platform or network team measures round-trip latency between every pair of Keycloak nodes and between the nodes and the primary database, using the actual links and zones you plan to use rather than vendor diagrams. Measure database commit latency under realistic write load, not idle. The single-cluster guide requires round-trip latency under 10 ms between Keycloak instances, and the multi-cluster v2 guide suggests commit latency below 5 ms with 10 ms as the requirement. Done means you hold a measured table of latencies with dates, times and load conditions, and you can state which architecture the numbers allow.
Confirm synchronous database replication
Your database team confirms that the database engine and deployment you intend to use provide synchronous replication across the zones or sites involved, because both supported high availability designs depend on it. Check the supported database list in the Keycloak database guide, including the PostgreSQL 14 to 18 range and Amazon Aurora PostgreSQL, and confirm the exact version against your own support matrix. Ask the database vendor or your DBA to document the replication mode, failover behavior and promotion process in writing. Done means a signed-off database design that names the replication mode and the version you will run.
Decide partition tolerance requirements
Your business owners and architects decide whether each site must keep serving logins if the network between sites fails. A single cluster spread across availability zones assumes the zones stay within one low-latency network, while multi-cluster v2 links independent sites and depends on cache messages and clock agreement between them. Record which applications must continue during a split, how long a degraded state is acceptable, and who makes the call during an incident. Done means a written requirement that either favors one design or identifies the trade-offs you must accept.
Pick the architecture and load balancer model
Your architects select one design and document the components around it. For multi-cluster v2, this includes the external load balancer that routes requests between clusters and probes their availability, plus NTP-synchronized clocks on all nodes, since clock skew over 10 seconds between clusters can stop cache invalidation. Confirm who owns the load balancer, how its health checks are configured and how its failover is tested. Done means an architecture decision record that lists every component, its owner and the monitoring that will show each one working.
Load test against your own profile
Your performance engineers build a load test from your own user counts, login rates, token refresh patterns and realm layout, then run it against a staging copy that matches production sizing and database configuration. Vendor test figures, such as the single-cluster guide's tested setup of 1,000,000 users and 300 requests per second, describe one configuration and do not replace your own results. Record CPU, memory, database write IOPS and latency at peak. For multi-cluster v2, include the write load, because the v1 design is documented to roughly double database CPU and write IOPS. Done means a report with a sizing decision and the headroom you measured.
Rehearse node and site failures
Your operations team, with DeployOpen if you have scoped that work in writing, injects node failures, zone or site outages, database failovers and load balancer faults during the staging test window. Keycloak detects a failed node within one minute by default, but the multi-cluster v2 guide warns that some failure scenarios can cause several minutes of downtime depending on the database, load balancer and Keycloak configuration. Run each scenario while monitoring active sessions, login errors and recovery time. Done means a failure test log that shows the observed downtime for each scenario, which you compare against the tolerance agreed in the partition decision.
Record results and approve go-live
Your change board or architecture review reads the load test report, the failure rehearsal log and the latency measurements together, then signs off or sends the design back for changes. Confirm the runbook covers the failover steps you actually rehearsed, the alerts that fire during each scenario and the owner of each recovery action. Ask any implementation partner to deliver these artifacts in the written scope, and confirm what ongoing testing or upgrade support is included after launch. Done means an approved go-live record that links each requirement to its evidence.
What failover looks like in each design
In the single-cluster design, Keycloak instances run inside one cluster on transparent networking, typically within one AWS Region, with the requirement of a round-trip latency below 10 ms between instances. When a pod fails, the remaining pods continue to serve requests and Keycloak's shared state stays in the database rather than on the failed instance. When an availability zone fails, the outcome depends on whether the surviving zones still have enough capacity for the traffic and whether the database fails over without losing committed writes. The tested reference setup uses 6 pods across 3 availability zones, each limited to 40 vCPU and 8 GB of memory, with Amazon Aurora PostgreSQL 17.5 replicating synchronously across zones. Your load balancer must stop routing to unhealthy pods quickly and must spread traffic across zones, or a zone failure can leave clients timing out against dead targets.
- Pod failure: Surviving pods absorb the load, so capacity headroom matters more than the failover mechanism itself.
- Zone failure: Replica placement across zones and the remaining capacity determine whether users notice the event.
- Database dependency: Synchronous replication is required, so the database failover behavior sets the ceiling on how well the cluster can recover.
- Load balancer behavior: Health check intervals and connection draining decide how long clients keep reaching failed targets.
- Sizing headroom: A design sized to run at full load in every zone will behave differently from one that needs all zones to stay up.
Before you rely on this design, confirm your database failover time, your load balancer health check settings and your surviving-zone capacity in a test that fails a zone under realistic load.
In the multi-cluster v2 design, several Keycloak deployments connect through the embedded Infinispan caches without a separate Infinispan cluster, and an external load balancer distributes requests between the clusters and probes their availability. When one cluster or site fails, the load balancer should stop sending traffic to it, and the remaining clusters continue to serve sessions that they can read from the shared database and replicated caches. The Keycloak multi-cluster v2 guide warns that some failure scenarios can cause several minutes of downtime, depending on the database, the load balancer and the Keycloak configuration. By default, Keycloak detects a failed node within one minute, but that detection window does not cover the time the load balancer and database take to react, so you cannot read the default as a failover time for your system.
- Node detection: By default Keycloak detects a failed node within one minute, which is a starting point for testing rather than a guaranteed recovery time.
- Multi-minute scenarios: The guide names failure cases that can cause several minutes of downtime, so you must identify which ones apply to your topology.
- Load balancer probes: Probe interval, failure threshold and how the balancer handles sessions determine how fast traffic leaves a failed site.
- Clock skew: Clocks must be NTP-synchronized, because skew over 10 seconds between clusters can stop cache invalidation messages.
- Database role: A highly available database with synchronous replication and low commit latency is still a single point of design risk for the whole design.
Test each failure case named in the guide, including partial network loss between sites, and record the observed downtime for your own database, load balancer and configuration before you commit to a service target.
What multi-cluster v2 adds: the load balancer, clocks and database load
Multi-cluster v2 moves complexity out of the Keycloak nodes and into the infrastructure around them. Each site runs its own Keycloak cluster, and an external load balancer must spread requests between those clusters and probe their availability. Keycloak does not supply this component for you. Confirm which product will perform the health checks, how often it probes each cluster, and how quickly it stops sending traffic to a site that fails. The Keycloak multi-cluster v2 guide warns that some failure scenarios can cause several minutes of downtime depending on the database, load balancer and Keycloak configuration, and by default Keycloak detects a failed node within one minute. Your failover time depends on the sum of those settings, so test it rather than assuming it.
Clock discipline is the second requirement and the easiest one to overlook. Every node needs an NTP-synchronized clock, because the guide notes that clock skew over 10 seconds between clusters can stop cache invalidation messages from being processed. The result is stale data served from one site after a change made at another, which is a quiet failure that health checks alone may not reveal. Ask the platform team who owns time synchronization on each site, how drift is monitored, and whether alerts fire well before the 10-second threshold. This is a skill gap for many teams that run Keycloak on virtual machines or Kubernetes nodes they have not previously managed for time sources.
The database budget needs the most attention in planning. The high availability overview estimates that multi-cluster roughly doubles database CPU and write IOPS compared with the alternative design. Because both supported designs require a synchronously replicated database, the database is also the place where latency, cost and failover behavior meet. Size it before the first site goes live, not after the first load test, and include the replication overhead in the figures you give your database provider or cloud account team. Operating skills that the team must have in place include load balancer configuration and health check tuning, NTP setup and monitoring, and database performance management with synchronous replication.
What running each design means for upgrades, backups and monitoring
This table compares the day-two work each Keycloak high availability design creates: upgrades, schema migration, backups, monitoring and staffing. Read each row as a question to answer for your own environment before choosing a design. The main takeaway is that multi-cluster adds operating surface on top of the single-cluster work, so confirm upgrade windows and restore tests with the team that will own it.
| Area | Single cluster across availability zones | Multi-cluster v2 across independent sites |
|---|---|---|
| Release cadence | Minor releases are planned four times a year since Keycloak 26.0, so plan a recurring upgrade window for one cluster. | Same release cadence applies, but every linked deployment must be upgraded and tested as a set. Confirm the sequence with your team. |
| Breaking changes | Breaking changes in a minor release are opt-in, so review release notes before enabling any new behavior. | Opt-in changes still apply per site. Confirm that all linked sites run compatible configuration before and after each upgrade. |
| Database schema migration | Migration runs automatically at startup by default. For large deployments, the upgrading guide suggests applying the SQL manually. | Each site's database must be migrated in a controlled order. Manual SQL is worth planning for when several sites share a schedule. |
| Backups | Back up the synchronously replicated database and test restores. Confirm backup scope covers realm configuration and secrets outside the database. | Back up every site's database and confirm the layout that replicates between them. Restore tests should cover losing one site and rejoining it. |
| Monitoring | Enable the documented metrics endpoint and watch node health, cache activity and database latency across the zones. | Monitor each site's metrics endpoint, the external load balancer health probes and clock skew between clusters, since skew over 10 seconds can stop cache invalidation. |
| Database load | The database is sized for one set of writes plus cross-zone replication latency, which must stay under 10 ms. | The guide estimates multi-cluster roughly doubles database CPU and write IOPS, so budget database capacity and monitoring for that increase. |
| Skills the team needs | Kubernetes or VM operations, database administration for synchronous replication, and Keycloak upgrade practice. | All single-cluster skills, plus load balancer configuration, NTP discipline across sites and cross-site failover testing. |
| Deprecated design risk | Not applicable. This design is the one the documentation describes without deprecation. | Avoid v1, which needs a separate Infinispan cluster per site and is deprecated for removal. Confirm the v2 path before any migration. |
Why the v1 multi-cluster design should be migrated away from
If your Keycloak estate runs multi-cluster v1, plan a move to v2 now rather than waiting for a removal notice. Keycloak's v1 design links sites through a separate Infinispan cluster per site, which adds a second stateful system to operate in each location. The project has deprecated v1 and says it will be removed in a future release, and the Keycloak high availability overview recommends v2 for multi-site designs. The removal date is not yet published, so the timing depends on your own release schedule: check which Keycloak version you run, read the release notes for each upgrade you expect to take, and confirm the removal milestone directly with the Keycloak project before setting a date for your change window.
A migration plan for v1 to v2 should cover four workstreams. First, the external load balancer, which v2 requires to balance requests between clusters and probe their availability, so the probe settings and failover behavior must be designed and tested before cutover. Second, database replication: v2 needs a highly available database with synchronous replication and a commit latency target below 5 ms (with 10 ms as the requirement), so confirm that the database layout you use today meets that bar. Third, clock sync, because nodes need NTP-synchronized clocks and skew over 10 seconds between clusters can stop cache invalidation messages. Fourth, cache testing, where you prove that sessions and cache invalidation behave correctly across sites under node loss before production traffic moves.
Keep a rollback path in the plan. Define the exact state in which you can return traffic to the v1 deployment, how long you keep it running in parallel, and which configuration and database changes can and cannot be reversed. The high availability overview makes the deployer responsible for validating the end-to-end design, so ask your DeployOpen or in-house team to document test results for failover, node loss and load balancer probes, not only for the happy path. Keycloak also documents that database schema changes are applied at startup by default, which affects how you sequence upgrades. Use the Keycloak multi-cluster v2 guide as the baseline for your test plan.
Questions buyers ask before choosing a Keycloak high availability design
What drives the cost of a single-cluster or multi-cluster Keycloak design?
The biggest drivers are the database, the extra capacity and the people who run it. Both designs need a synchronously replicated database, so the database license or cloud service tier and its replicas are a recurring cost. Multi-cluster adds a second set of Keycloak nodes and an external load balancer that probes each site, and the Keycloak high availability overview estimates that multi-cluster roughly doubles database CPU and write IOPS. Ask any provider to price each of these items separately in a fixed-scope quote, including who pays for the cloud or data center capacity and who pays for ongoing operations.
Can our team run Keycloak high availability without outside help?
A capable platform team can run either design, but the work sits across Keycloak, the database, the network and the load balancer, so the question is whether one team owns all four. Keycloak's high availability overview states that deployers are responsible for designing, validating and operating their end-to-end high availability architecture. If your team already runs synchronously replicated databases and tests failover regularly, the gap is smaller. If not, a fixed-scope engagement can cover design, validation and a documented runbook, and retainers can cover upgrades and continuous testing afterward.
How long does a Keycloak high availability project take?
The timeline depends on how many of the prerequisites already exist. The main factors are whether a qualifying database with synchronous replication is in place, whether the network meets the latency limits for your chosen design, whether NTP is already enforced on every node, and how much load testing your team must perform before go-live. Single-cluster work mostly involves infrastructure placement and testing across availability zones, while multi-cluster adds site links, load balancer health checks and clock validation. Ask for the schedule in the written scope, with each milestone and the testing that must pass before cutover.
What skills does a Keycloak high availability design require?
Both designs require database administration skills, network skills and a working knowledge of how Keycloak caches and sessions behave. The database needs synchronous replication and commit latency measured against the guide's targets, so someone must own that tuning. Single-cluster designs usually run on a Kubernetes cluster, which means Kubernetes skills and, if you use the Keycloak Operator, familiarity with Operator Lifecycle Manager. Multi-cluster designs also need careful control of inter-site latency and clock synchronization. Confirm which of these skills sit in-house before you choose the design.
Do we have to replace the deprecated Keycloak multi-cluster v1 design now?
Keycloak multi-cluster v1 is deprecated and will be removed in a future release, so any new design should not start on it. If you already run v1, plan a migration to v2 or to a single-cluster design on a schedule you control rather than waiting for a forced change. The v1 design needs a separate Infinispan cluster per site, which v2 removes. Ask your provider to inventory the current v1 dependencies, including the Infinispan clusters, load balancer configuration and database settings, and to include the migration and its validation in the written scope.
What should we expect for failover downtime in each design?
Keycloak detects a failed node within one minute by default, but the multi-cluster v2 guide warns that some failure scenarios can cause several minutes of downtime depending on the database, load balancer and Keycloak configuration. Downtime therefore depends on the combination of settings in your environment, not on the design name alone. Ask any provider to test the specific failure scenarios that matter to you, record the measured recovery time, and state which failures were excluded from the test plan.
What should we ask a provider for in a fixed-scope quote?
Ask for a written scope that names the chosen design, the database and its replication setup, the load balancer and health checks, the clock synchronization method, and the sizing basis for users and requests per second. The quote should list each deliverable, including the architecture document, the failover tests with their measured results, the runbook, and any migration from v1. It should also state what is one-time, such as design and testing, and what recurs, such as upgrades and continuous testing under a retainer. Confirm which items sit outside the scope and who owns the cloud or data center accounts where the platform runs.
How DeployOpen scopes and delivers a Keycloak high availability build
DeployOpen plans, implements, hardens, documents and supports self-hosted open-source platforms inside the client's own infrastructure, so a Keycloak high availability design is built in your cloud account, data center or air-gapped network. The work starts with a written scope that settles which architecture fits your latency, database and failure-tolerance requirements before any infrastructure is changed.
How we scope
- Confirm whether all sites sit within one low-latency network, since the single-cluster guide requires under 10 ms round-trip latency between instances.
- Review the database platform and its synchronous replication options, because both supported high availability designs depend on them.
- Agree in writing which failure scenarios, user volumes and request rates the design must survive, and how downtime will be measured.
How we build
- Deploy Keycloak with the Keycloak Operator or the server distribution, based on the platform your team already runs and operates.
- Place and configure the external load balancer that distributes requests across clusters and probes their availability.
- Set NTP time synchronization on all nodes and test failover paths, including node loss, zone loss and database failover, against the agreed scope.
How we hand over
- Document the architecture, the database and load balancer settings, and the runbooks for failover, upgrades and schema migration.
- Record the test results, including observed detection and recovery times, so your team can compare them with the expected behavior.
- Walk your operators through the upgrade approach, including manual approval for operator updates and how schema migration runs in your environment.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers after handover, scoped in a separate written agreement.
- Retainers can cover re-testing after Keycloak minor releases, which arrive several times a year under the project's release plan.
- Ask for a quote built from the written scope, since DeployOpen does not publish a price list and quotes follow the agreed deliverables.
