Backup & Recovery
Postgres holds your configuration data. Every account's Keycloak realm holds the rest — and it isn't in Postgres.
Postgres is the system of record
Every account and connection record, every credential the server holds (encrypted OIDC client secrets, and the SHA-256 hashes of SCIM tokens and API keys — see Encryption at Rest), and the full audit and observability history (see Monitoring & Observability) live in one Postgres database. There is no secondary datastore for this configuration data — losing it without a backup means losing your entire customer/connection configuration and history, not just recent activity.
The Helm chart's backup block
The chart exposes three values under backup.*:
| Key | Default | Meaning |
|---|---|---|
| backup.enabled | true | Whether backup automation is turned on |
| backup.schedule | 0 2 * * * | Cron schedule — daily at 02:00 |
| backup.retention | 30 | How many days of backups to keep |
This is configuration surface, not yet a running job
No CronJob template in the chart reads backup.schedule or backup.retention and actually runs a backup. Setting backup.enabled: true today does not, by itself, produce a scheduled job in your cluster. Until that template exists, treat these three values as the intended shape of backup automation and pair them with your own mechanism — a CronJob running pg_dump against postgresql.externalUrl on the same schedule, or your managed Postgres provider's native backup/point-in-time-recovery feature.
The second piece of state: Keycloak realms
Under the realm-per-account model (ADR 0001), every account's keycloakRealm points at a live Keycloak realm holding that customer's clients, identity providers, and signing keys. None of that lives in Postgres. Postgres knows the realm's name; Keycloak holds the realm itself.
This means a Postgres backup alone cannot recover a deleted or corrupted Keycloak realm — restoring the database would give you an Account row pointing at a realm name that no longer exists, and that account's SSO would stay broken until the realm is recreated or restored from a separate Keycloak-side backup. A complete disaster-recovery plan needs both halves: Postgres for configuration and history, and a backup or export strategy for each customer's Keycloak realm (Keycloak supports realm export/import for exactly this).
Recovery considerations
- Restore Postgres and every affected Keycloak realm together, and test that together — restoring only one half leaves accounts with mismatched or missing SSO configuration.
backup.retention(30 days by default) should be sized against how far back you might need to recover an accidentally deleted account — remember that deleting anAccountin RealmSSO also deletes its Keycloak realm (see the realm-per-account ADR), so there is no soft-delete window on the Keycloak side either.- Encryption keys (
encryptionKey, used to encrypt secrets at rest — see Encryption at Rest) must be backed up and restorable alongside the database itself; a Postgres restore with a lost or rotated encryption key leaves encrypted columns unreadable.