Using Amazon Regional Aurora PostgreSQL storage

An Amazon Regional Aurora PostgreSQL instance can be used as the underlying database for Keycloak in either single, or multi-site configurations. Currently, this is only supported with Keycloak deployments on ROSA.

Deploying an Aurora Cluster

Aurora clusters can be deployed to your AWS region of choice by executing ./provision/aws/rds/aurora_create.sh with the following env:

AURORA_CLUSTER= # The name of the Aurora cluster
AURORA_REGION= # The AWS region hosting the Aurora cluster
AURORA_INSTANCES= # The number of Aurora db instances to create in the AURORA_REGION, defaults to 1

This creates the necessary VPCs, subnets and routes required by an Aurora cluster as well as $AURORA_INSTANCES Aurora instances for said cluster. To create a multi-AZ database, create two instances The script currently doesn’t support more than two AZs for the instances created, all additional instances are distributed across the two AZs supported by the script. The script waits until the cluster and all instances are available. If the cluster already exists, a message indicating this is displayed and the script will fail with exit code 1.

The specified AURORA_CLUSTER must be unique per the AWS region and follow the conventions outlined for the "DB cluster identifier".

Connecting ROSA cluster to Aurora Cluster

In order to follow security best practices, the Aurora cluster is not exposed publicly over the internet. Instead, it is necessary for us to establish a Peering Connection between a ROSA cluster VPC and the Aurora Cluster VPC.

To configure such a connection run ./provision/aws/rds/aurora_create_peering_connection.sh with the following environment:

AURORA_CLUSTER= # The name of the Aurora cluster
AURORA_REGION= # The AWS region hosting the Aurora cluster
CLUSTER_NAME= # The name of the ROSA cluster to establish the peering connectin with
AWS_REGION= # The AWS region hosting the ROSA cluster

The scripts in this project ensure that all Aurora and ROSA clusters have non-overlapping machine-CIDR configured.

Enabling Aurora PostgreSQL storage

Use the following settings to configure the Aurora store:

KC_DATABASE=aurora-postgres
KC_DATABASE_URL=aws.example.route.com

The KC_DATABASE_URL should be the exposed endpoint of the Aurora writer instances. This can be obtained by executing the ./provision/aws/rds/aurora_endpoint.sh script with the following env:

AURORA_CLUSTER= # The name of the Aurora cluster instance
AURORA_REGION= # The AWS region hosting the Aurora cluster

See Customizing the deployment for a list of all configuration options.

Debugging Aurora PostgreSQL

The Aurora DB cluster is only accessible to ROSA clusters with an established Peering Connection, therefore all debugging connections must also originate from said clusters. A simple way to connect psql to the cluster is to execute the following:

kubectl run -i --tty --rm debug --image=postgres:15 --restart=Never -n <namespace> -- psql -h <....rds.amazonaws.com> -d keycloak -U keycloak

This will create a pod in the Keycloak deployment namespace and establish a connection with the Aurora cluster. A password prompt will appear on initial connection and you should utilise the password defined in the Secret keycloak-db-secret. Upon exiting the pod shell, the pod will be deleted.

To drop the contents of the database, run the following command. Then restart all Keycloak nodes in all datacenters.

DROP SCHEMA public CASCADE; CREATE SCHEMA public;

Disconnecting ROSA cluster from an individual Aurora Cluster

To remove a Peering Connections between a ROSA cluster and a specific Aurora cluster, execute ./provision/aws/rds/aurora_delete_peering_connection.sh with the following env:

AURORA_CLUSTER= # The name of the Aurora cluster instance
AURORA_REGION= # The AWS region hosting the Aurora cluster
CLUSTER_NAME= # The name of the ROSA cluster to remove the peering connection from
AWS_REGION= # The AWS region hosting the ROSA cluster

Disconnecting ROSA cluster from all Aurora Clusters

To remove all Peering Connections between the ROSA and Aurora VPCS in a given region, execute ./provision/aws/rds/aurora_delete_peering_connection.sh with the following env:

AURORA_REGION= # The AWS region hosting the Aurora clusters
CLUSTER_NAME= # The name of the ROSA cluster to remove the peering connection from
AWS_REGION= # The AWS region hosting the ROSA cluster

Deleting an Aurora Cluster

Before deleting an Aurora cluster, it is first necessary for all Peering Connections established with ROSA cluster(s) to be removed.

To remove an Aurora cluster, execute ./provision/aws/rds/aurora_delete.sh with the following env:

AURORA_CLUSTER= # The name of the Aurora cluster instance
AURORA_REGION= # The AWS region hosting the Aurora cluster