Chapter 10. Switch over to the secondary site
This procedure switches from the primary site to the secondary site when using a setup as outlined in Concepts for active-passive deployments together with the blueprints outlined in Building blocks active-passive deployments.
10.1. When to use this procedure
Use this procedure to gracefully take the primary offline.
Once the primary site is back online, use the chapters Recover from an out-of-sync passive site and Switch back to the primary site to return to the original state with the primary site being active.
See the Multi-site deployments chapter for different operational procedures.
10.2. Procedures
10.2.1. Data Grid Cluster
For the context of this chapter, Site-A is the primary site and Site-B is the secondary site.
When you are ready to take a site offline, a good practice is to disable the replication towards it. This action prevents errors or delays when the channels are disconnected between the primary and the secondary site.
10.2.1.1. Procedures to transfer state from secondary to primary site
- Log in into your secondary site
Connect into Data Grid Cluster using the Data Grid CLI tool:
Command:
oc -n keycloak exec -it pods/infinispan-0 -- ./bin/cli.sh --trustall --connect https://127.0.0.1:11222
It asks for the username and password for the Data Grid cluster. Those credentials are the one set in the Deploy Data Grid for HA with the Data Grid Operator chapter in the configuring credentials section.
Output:
Username: developer Password: [infinispan-0-29897@ISPN//containers/default]>
NoteThe pod name depends on the cluster name defined in the Data Grid CR. The connection can be done with any pod in the Data Grid cluster.
Disable the replication to the primary site by running the following command:
Command:
site take-offline --all-caches --site=site-a
Output:
{ "offlineClientSessions" : "ok", "authenticationSessions" : "ok", "sessions" : "ok", "clientSessions" : "ok", "work" : "ok", "offlineSessions" : "ok", "loginFailures" : "ok", "actionTokens" : "ok" }Check the replication status is
offline.Command:
site status --all-caches --site=site-a
Output:
{ "status" : "offline" }If the status is not
offline, repeat the previous step.
The Data Grid cluster in the secondary site is ready to handle requests without trying to replicate to the primary site.
10.2.2. AWS Aurora Database
Assuming a Regional multi-AZ Aurora deployment, the current writer instance should be in the same region as the active Red Hat build of Keycloak cluster to avoid latencies and communication across availability zones.
Switching the writer instance of Aurora will lead to a short downtime. The writer instance in the other site with a slightly longer latency might be acceptable for some deployments. Therefore, this situation might be deferred to a maintenance window or skipped depending on the circumstances of the deployment.
To change the writer instance, run a failover. This change will make the database unavailable for a short time. Red Hat build of Keycloak will need to re-establish database connections.
To fail over the writer instance to the other AZ, issue the following command:
aws rds failover-db-cluster --db-cluster-identifier ...
10.2.3. Red Hat build of Keycloak Cluster
No action required.
10.2.4. Route53
To force Route53 to mark the primary site as not available, edit the health check in AWS to point to a non-existent route (health/down). After some minutes, the clients will notice the change and traffic will gradually move over to the secondary site.
10.3. Further reading
See Concepts to automate Data Grid CLI commands on how to automate Infinispan CLI commands.
