keycloak-scim/docs/guides/high-availability/deploy-aurora-multi-az.adoc

<#import "/templates/guide.adoc" as tmpl>
<#import "/templates/links.adoc" as links>

<@tmpl.guide
title="Deploy AWS Aurora in multiple availability zones"
summary="Building block for a database"
tileVisible="false" >

This topic describes how to deploy an Aurora regional deployment of a PostgreSQL instance across multiple availability zones to tolerate one or more availability zone failures in a given AWS region.

This deployment is intended to be used with the setup described in the <@links.ha id="concepts-multi-site"/> {section}.
Use this deployment with the other building blocks outlined in the <@links.ha id="bblocks-multi-site"/> {section}.

include::partials/blueprint-disclaimer.adoc[]

== Architecture

Aurora database clusters consist of multiple Aurora database instances, with one instance designated as the primary writer and all others as backup readers.
To ensure high availability in the event of availability zone failures, Aurora allows database instances to be deployed across multiple zones in a single AWS region.
In the event of a failure on the availability zone that is hosting the Primary database instance, Aurora automatically heals itself and promotes a reader instance from a non-failed availability zone to be the new writer instance.

.Aurora Multiple Availability Zone Deployment
image::high-availability/aurora-multi-az.dio.svg[]

See the https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/CHAP_AuroraOverview.html[AWS Aurora documentation] for more details on the semantics provided by Aurora databases.

This documentation follows AWS best practices and creates a private Aurora database that is not exposed to the Internet.
To access the database from a ROSA cluster, <<establish-peering-connections-with-rosa-clusters,establish a peering connection between the database and the ROSA cluster>>.

== Procedure

The following procedure contains two sections:

* Creation of an Aurora Multi-AZ database cluster with the name "keycloak-aurora" in eu-west-1.
* Creation of a peering connection between the ROSA cluster(s) and the Aurora VPC to allow applications deployed on the ROSA clusters to establish connections with the database.

=== Create Aurora database Cluster

include::partials/aurora/aurora-multiaz-create-procedure.adoc[]

[#establish-peering-connections-with-rosa-clusters]
=== Establish Peering Connections with ROSA clusters

Perform these steps once for each ROSA cluster that contains a {project_name} deployment.

include::partials/aurora/aurora-create-peering-connections.adoc[]

== Verifying the connection

include::partials/aurora/aurora-verify-peering-connections.adoc[]

== Deploying {project_name}

Now that an Aurora database has been established and linked with all of your ROSA clusters, the next step is to deploy {project_name} as described in the <@links.ha id="deploy-keycloak-kubernetes" /> {section} with the JDBC url configured to use the Aurora database writer endpoint.
To do this, create a `Keycloak` CR with the following adjustments:

. Update `spec.db.url` to be `jdbc:aws-wrapper:postgresql://$HOST:5432/keycloak` where `$HOST` is the
<<aurora-writer-url, Aurora writer endpoint URL>>.

. Ensure that the Secrets referenced by `spec.db.usernameSecret` and `spec.db.passwordSecret` contain usernames and passwords defined when creating Aurora.

</@tmpl.guide>