From 746a8211ffd04fc4fb559ce2a05f800b38cd0eb6 Mon Sep 17 00:00:00 2001 From: Pedro Ruivo Date: Fri, 26 Sep 2025 12:06:28 +0100 Subject: [PATCH] Update documentation to prefer CacheCR in multi-site Closes #42980 Signed-off-by: Pedro Ruivo <1492066+pruivo@users.noreply.github.com> Signed-off-by: Alexander Schwartz Co-authored-by: Pedro Ruivo <1492066+pruivo@users.noreply.github.com> Co-authored-by: Alexander Schwartz --- .../deploy-infinispan-kubernetes-crossdc.adoc | 82 ++++++++++++++++++- 1 file changed, 79 insertions(+), 3 deletions(-) diff --git a/docs/guides/high-availability/multi-cluster/deploy-infinispan-kubernetes-crossdc.adoc b/docs/guides/high-availability/multi-cluster/deploy-infinispan-kubernetes-crossdc.adoc index 3ebea845b65..26f414b2739 100644 --- a/docs/guides/high-availability/multi-cluster/deploy-infinispan-kubernetes-crossdc.adoc +++ b/docs/guides/high-availability/multi-cluster/deploy-infinispan-kubernetes-crossdc.adoc @@ -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.` 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