
:guide-id: introduction
:guide-title: Multi-site deployments
:guide-summary: Connect multiple {project_name} deployments in different sites to increase the overall availability.
:guide-priority: 999
:guide-tile-visible: true
:version: 26.3.0

include::../attributes.adoc[]

[[introduction]]
= Multi-site deployments

ifeval::["" == "true"]
WARNING: This {section} is describing a feature which is currently in preview.
ifeval::["" == ""]
Please provide your feedback while we’re continuing to work on this.
endif::[]
ifeval::["" != ""]
Please provide your feedback by link:[joining this discussion] while we’re continuing to work on this.
endif::[]
endif::[]


{project_name} supports deployments that consist of multiple {project_name} instances that connect to each other using its Infinispan caches; load balancers can distribute the load evenly across those instances.
Those setups are intended for a transparent network on a single site.

The {project_name} high-availability guide goes one step further to describe setups across multiple sites.
While this setup adds additional complexity, that extra amount of high availability may be needed for some environments.

== When to use a multi-site setup

The multi-site deployment capabilities of {project_name} are targeted at use cases that:

* Are constrained to a single
ifeval::[{project_product} == true]
AWS Region.
endif::[]
ifeval::[{project_product} != true]
AWS Region or an equivalent low-latency setup.
endif::[]
* Permit planned outages for maintenance.
* Fit within a defined user and request count.
* Can accept the impact of periodic outages.

ifeval::[{project_product} != true]
== Tested Configuration

We regularly test {project_name} with the following configuration:
endif::[]
ifeval::[{project_product} == true]
== Supported Configuration
endif::[]

* Two Openshift single-AZ clusters, in the same AWS Region
** Provisioned with https://www.redhat.com/en/technologies/cloud-computing/openshift/aws[Red Hat OpenShift Service on AWS] (ROSA),
ifeval::[{project_product} == true]
either ROSA HCP or ROSA classic.
endif::[]
ifeval::[{project_product} != true]
using ROSA HCP.
endif::[]

** Each Openshift cluster has all its workers in a single Availability Zone.
** OpenShift version
ifeval::[{project_product} == true]
4.17 (or later).
endif::[]
ifeval::[{project_product} != true]
4.17.
endif::[]

* Amazon Aurora PostgreSQL database
** High availability with a primary DB instance in one Availability Zone, and a synchronously replicated reader in the second Availability Zone
** Version 16.8
* AWS Global Accelerator, sending traffic to both ROSA clusters
* AWS Lambda
ifeval::[{project_product} != true]
triggered by ROSA's Prometheus and Alert Manager
endif::[]
to automate failover

ifeval::[{project_product} == true]
Any deviation from the configuration above is not supported and any issue must be replicated in that environment for support.
endif::[]
ifeval::[{project_product} != true]
While equivalent setups should work, you will need to verify the performance and failure behavior of your environment.
We provide functional tests, failure tests and load tests in the https://github.com/keycloak/keycloak-benchmark[Keycloak Benchmark Project].
endif::[]

Read more on each item in the link:{links_high-availability_bblocks-multi-site_url}[{links_high-availability_bblocks-multi-site_name}] {section}.

ifeval::[{project_product} == true]
== Maximum load
endif::[]
ifeval::[{project_product} != true]
== Tested load

We regularly test {project_name} with the following load:
endif::[]

* 100,000 users
* 300 requests per second

ifeval::[{project_product} != true]
While we did not see a hard limit in our tests with these values, we ask you to test for higher volumes with horizontally and vertically scaled {project_name} name instances and databases.
endif::[]

See the link:{links_high-availability_concepts-memory-and-cpu-sizing_url}[{links_high-availability_concepts-memory-and-cpu-sizing_name}] {section} for more information.

== Limitations

ifeval::[{project_product} != true]
Even with the additional redundancy of the two sites, downtimes can still occur:
endif::[]

* During upgrades of {project_name} or {jdgserver_name} both sites needs to be taken offline for the duration of the upgrade.
* During certain failure scenarios, there may be downtime of up to 5 minutes.
* After certain failure scenarios, manual intervention may be required to restore redundancy by bringing the failed site back online.
* During certain switchover scenarios, there may be downtime of up to 5 minutes.

For more details on limitations see the link:{links_high-availability_concepts-multi-site_url}[{links_high-availability_concepts-multi-site_name}] {section}.

== Next steps

The different {sections} introduce the necessary concepts and building blocks.
For each building block, a blueprint shows how to set a fully functional example.
Additional performance tuning and security hardening are still recommended when preparing a production setup.

ifeval::[{project_product} != true]
== Concept and building block overview

* link:{links_high-availability_concepts-multi-site_url}[{links_high-availability_concepts-multi-site_name}]
* link:{links_high-availability_bblocks-multi-site_url}[{links_high-availability_bblocks-multi-site_name}]
* link:{links_high-availability_concepts-database-connections_url}[{links_high-availability_concepts-database-connections_name}]
* link:{links_high-availability_concepts-threads_url}[{links_high-availability_concepts-threads_name}]
* link:{links_high-availability_concepts-memory-and-cpu-sizing_url}[{links_high-availability_concepts-memory-and-cpu-sizing_name}]
* link:{links_high-availability_concepts-infinispan-cli-batch_url}[{links_high-availability_concepts-infinispan-cli-batch_name}]

== Blueprints for building blocks

* link:{links_high-availability_deploy-aurora-multi-az_url}[{links_high-availability_deploy-aurora-multi-az_name}]
* link:{links_high-availability_deploy-infinispan-kubernetes-crossdc_url}[{links_high-availability_deploy-infinispan-kubernetes-crossdc_name}]
* link:{links_high-availability_deploy-keycloak-kubernetes_url}[{links_high-availability_deploy-keycloak-kubernetes_name}]
* link:{links_high-availability_deploy-aws-accelerator-loadbalancer_url}[{links_high-availability_deploy-aws-accelerator-loadbalancer_name}]
* link:{links_high-availability_deploy-aws-accelerator-fencing-lambda_url}[{links_high-availability_deploy-aws-accelerator-fencing-lambda_name}]

== Operational procedures

* link:{links_high-availability_operate-synchronize_url}[{links_high-availability_operate-synchronize_name}]
* link:{links_high-availability_operate-site-offline_url}[{links_high-availability_operate-site-offline_name}]
* link:{links_high-availability_operate-site-online_url}[{links_high-availability_operate-site-online_name}]
* link:{links_high-availability_health-checks-multi-site_url}[{links_high-availability_health-checks-multi-site_name}]

endif::[]


