Alauda Application Services Identity Management E1

Configure Database

Keycloak requires a relational database for persistent storage of realms, users, clients, sessions, and events. This guide covers database configuration for production deployments.

TOC

Supported DatabasesConfigure the Database in the Keycloak CRConfiguration ReferenceCreate the Database SecretProduction Best PracticesConnection Pool SizingDatabase High AvailabilityBackup and RestoreDatabase Schema Migration

Supported Databases

Alauda Application Services Identity Management E1 is tested and supported with the following database:

DatabaseVendor ValueStatus
PostgreSQLpostgresRecommended and fully supported.

Upstream Keycloak 26.x also supports MySQL/MariaDB, Microsoft SQL Server, and Oracle at the engine level. However, Alauda Application Services Identity Management E1 is validated and supported with PostgreSQL only. Using other database vendors is at your own risk and may not receive support.

Database Support Boundary

The supported PostgreSQL version range for Alauda Application Services Identity Management E1 is defined in the release notes for each version. Do not assume that all PostgreSQL versions supported by upstream Keycloak are also validated for Alauda Build. Always check the release notes and compatibility matrix before deploying or upgrading your database.

Configure the Database in the Keycloak CR

The database connection is configured in the spec.db section of the Keycloak CR:

spec:
  db:
    vendor: postgres
    host: postgres-db.database.svc.cluster.local
    port: 5432
    database: keycloak
    schema: public
    usernameSecret:
      name: keycloak-db-secret
      key: username
    passwordSecret:
      name: keycloak-db-secret
      key: password

Configuration Reference

FieldDescriptionDefault
spec.db.vendorDatabase typepostgres
spec.db.hostDatabase hostname—
spec.db.portDatabase port5432 (PostgreSQL)
spec.db.databaseDatabase namekeycloak
spec.db.schemaDatabase schemapublic
spec.db.urlFull JDBC URL (overrides host/port/database)—
spec.db.usernameSecretSecret reference for database username—
spec.db.passwordSecretSecret reference for database password—
spec.db.poolInitialSizeInitial connection pool size0
spec.db.poolMinSizeMinimum connection pool size0
spec.db.poolMaxSizeMaximum connection pool size100

Create the Database Secret

kubectl create secret generic keycloak-db-secret \
  --from-literal=username=keycloak \
  --from-literal=password='<strong-password>' \
  -n <namespace>

Production Best Practices

Connection Pool Sizing

The default maximum pool size of 100 is suitable for most deployments. Adjust based on:

  • Number of Keycloak replicas (each replica maintains its own pool)
  • Expected concurrent user load
  • Database server connection limits

For a 3-replica HA deployment, the total maximum connections = poolMaxSize * replicas (for example, 100 * 3 = 300).

Database High Availability

For production deployments, the database should be highly available:

  • Use a managed database service with automatic failover, or
  • Deploy a PostgreSQL HA cluster (for example, using a PostgreSQL Operator such as CloudNativePG or Zalando Postgres Operator).
  • Configure connection strings to point to the primary/writer endpoint.

Backup and Restore

Backup Strategy Required

Keycloak stores all configuration, user data, and credentials in the database. A robust backup strategy is essential. The specific backup procedures depend on your database infrastructure and are outside the scope of this guide. Ensure that your database backup solution:

  • Performs regular automated backups (at least daily)
  • Supports point-in-time recovery
  • Is tested regularly with restore drills
  • Stores backups in a separate location from the database

Database Schema Migration

Keycloak automatically applies database schema migrations on startup when upgrading to a new version. No manual migration steps are required. However:

  • Always back up the database before upgrading Keycloak.
  • Schema migrations are forward-only and cannot be rolled back.
  • Test upgrades in a non-production environment first.