mirror/keycloak
1
0
Fork 0
mirror of https://github.com/keycloak/keycloak.git synced 2025-12-21 06:20:05 -06:00
Code Issues Packages Projects Releases Wiki Activity

Update documentation to prefer CacheCR in multi-site

Browse Source 
Closes #42980

Signed-off-by: Pedro Ruivo <1492066+pruivo@users.noreply.github.com>
Signed-off-by: Alexander Schwartz <alexander.schwartz@ibm.com>
Co-authored-by: Pedro Ruivo <1492066+pruivo@users.noreply.github.com>
Co-authored-by: Alexander Schwartz <alexander.schwartz@ibm.com>
This commit is contained in:
Pedro Ruivo
2025-09-26 12:06:28 +01:00
committed by GitHub
parent 7e28d13e76
commit 746a8211ff
1 changed files with 79 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

82
docs/guides/high-availability/multi-cluster/deploy-infinispan-kubernetes-crossdc.adoc
View File

@@ -172,7 +172,7 @@ include::../examples/generated/ispn-site-a.yaml[tag=infinispan-crossdc]
<8> The secret key (filename) of the Keystore as defined in the previous step.
<9> The secret name where the Truststore exists as defined in the previous step.
<10> The Truststore key (filename) of the Keystore as defined in the previous step.
<11> The remote site's name, in this case `{site-b}`. Use this value in {project_name} option `cache-remote-backup-sites`.
<11> The remote site's name, in this case `{site-b}`. You may use this value in {project_name} option `cache-remote-backup-sites` for the automatic cache creation.
<12> The namespace of the {jdgserver_name} cluster from the remote site.
<13> The {ocp} API URL for the remote site.
<14> The secret with the access token to authenticate into the remote site.
@@ -190,9 +190,79 @@ include::../examples/generated/ispn-site-b.yaml[tag=infinispan-crossdc]
. Creating the caches for {project_name}.
+
{project_name} automatically creates the necessary caches on the first startup if they do not exist.
To customize any default configuration, use the {infinispan-operator-docs}#creating-caches_creating-caches[`Cache` CR] to declare the full cache configuration.
+
[IMPORTANT]
====
It requires {project_name} to be deployed in both clusters because the {project_name} does not start until all caches are present in both clusters.
====
+
To {infinispan-operator-docs}#creating-caches_creating-caches[`Cache` CR] is the recommend way to proceed in {kubernetes}.
To take effect, the `Cache` CR must be deployed before any {project_name} Pod starts.
+
The following example shows the `Cache` CR for `{site-a}`.
+
--
. In `{site-a}` create a `Cache` CR for each of the caches mentioned above with the following content.
+
.Cache `actionTokens`
[source,yaml]
----
include::../examples/generated/ispn-site-a.yaml[tag=infinispan-cache-actionTokens]
----
+
.Cache `authenticationSessions`
[source,yaml]
----
include::../examples/generated/ispn-site-a.yaml[tag=infinispan-cache-authenticationSessions]
----
+
.Cache `loginFailures`
[source,yaml]
----
include::../examples/generated/ispn-site-a.yaml[tag=infinispan-cache-loginFailures]
----
+
.Cache `work`
[source,yaml]
----
include::../examples/generated/ispn-site-a.yaml[tag=infinispan-cache-work]
----
<1> The transaction mode.
<2> The locking mode used by the transaction.
<3> The remote site name.
<4> The cross-site communication strategy, in this case, `SYNC`.
<5> The cross-site replication timeout.
<6> The cross-site replication failure policy.
--
+
The example above is the recommended configuration to achieve the best data consistency.
+
====
*Background information*
Deadlocks may occur in an active-active setup as entries are modified concurrently in both sites.
The `transaction.mode: NON_DURABLE_XA` ensures that the transaction is rolled back keeping the data consistent if this occurs.
The setting `backup.failurePolicy: FAIL` is required in this case.
It will throw an error that allows the transaction to be safely rolled back.
When this occurs, {project_name} will attempt a retry.
The `transaction.locking: PESSIMISTIC` is the only supported locking mode; `OPTIMISTIC` is not recommended due to its network costs.
The same settings also prevent that one site is updated while the other site is unreachable.
The `backup.strategy: SYNC` ensures the data is visible and stored in the other site when the {project_name} request is completed.
NOTE: The `locking.acquireTimeout` can be reduced to fail fast in a deadlock scenario.
The `backup.timeout` must always be higher than the `locking.acquireTimeout`.
====
+
For `{site-b}`, the `Cache` CR is similar, except for the `backups.<name>` outlined in point 3 of the above diagram.
+
.Example for `actionTokens` cache in `{site-b}`
[source,yaml]
----
include::../examples/generated/ispn-site-b.yaml[tag=infinispan-cache-actionTokens]
----
== Verifying the deployment
Confirm that the {jdgserver_name} cluster is formed, and the cross-site connection is established between the {ocp} clusters.
@@ -238,7 +308,13 @@ include::../examples/generated/keycloak-ispn.yaml[tag=keycloak-ispn]
This is optional, and it defaults to `11222`.
<3> The Secret `name` and `key` with the {jdgserver_name} username credential.
<4> The Secret `name` and `key` with the {jdgserver_name} password credential.
<5> The name of the remote site.
<5> Optionally, the name of the remote site. The caches are only created if they do not already exist.
+
[IMPORTANT]
====
Using the option `cache-remote-backup-sites` only creates the caches in the local site.
You must deploy the `KeycloakCR` in the other cluster too, to create the caches there, otherwise {project_name} fails to start until they exist.
====
=== Architecture