Learn Keycloak - Backup, Disaster Recovery & Upgrades

#Introduction

In episode 28 you made the cluster fast and measurable. Episode 29 answers the question people like least but matters most: what if everything gets destroyed? Backups protect data; disaster recovery restores service; upgrades keep security and features current. These three capabilities are the insurance a production deployment must not be without.

#Backup Strategy

Keycloak stores almost everything important in the database. But it's not only the database that must be backed up:

Database backup is done with the database's native utility:

pg_dump -h db.example.com -U keycloak -Fc keycloak > keycloak-$(date +%F).dump

pg_dump -Fc produces a binary archive that's easy to restore and compress. Store backups in a separate location — ideally object storage in a different region — and automate with cron or a systemd timer. A backup that only humans remember eventually never happens.

The principle is simple: if data is lost and can't be rebuilt, it must be backed up. Themes and extensions can indeed be rebuilt from source, but the database and realm configuration cannot. A good backup is also one that has been restored — schedule periodic restore tests into an empty database, then run a login health check so you know the backup files aren't corrupt.

Realm configuration export completes the database backup:

kc.sh export --dir /backup/keycloak-config --realm bank

kc.sh export describes the realm as files — very useful for moving configuration between environments (client policies from episode 26, authorization policies from episode 25) without carrying user data.

#Disaster Recovery

A backup has no value without a tested recovery procedure. Design a disaster recovery plan with two key numbers:

RPO determines backup frequency: an RPO of 15 minutes means backup or replication must run every 15 minutes. RTO determines recovery automation: the tighter the RTO, the more processes must be automatic. For multi-region, consider database replication between regions and DNS failover; without that, the realistic strategy is backup and restore to a standby region.

Multi-region adds cost and replication complexity. For most teams, a backup-and-restore strategy to a standby region is sufficient — make sure its RTO meets the SLA promise before chasing a full multi-region topology. RTO and RPO also aren't just numbers on a document: both must be tested, starting from realistic figures and tightening as automation improves.

• Recovery procedures — write the recovery steps one by one, from database restore to login verification.
• Failover strategies — make sure the chosen alternative can actually be executed when the primary zone dies.
• DR testing — test the procedures periodically in a separate environment; a procedure that was never tested is empty hope.

#Upgrade Procedures

Upgrading Keycloak is part of the lifecycle, not a rare event. The safe steps:

1. Version compatibility — read the migration guide released with each version; note configuration changes, endpoints, and removed features.
2. Pre-upgrade preparation — back up the database and full configuration, then record the old version and the settings you changed.
3. Database migration — Keycloak migrates the database schema automatically when first run with a new version; make sure the backup exists before this step.
4. Rolling upgrade — upgrade nodes one by one behind the load balancer, so the service never stops entirely.
5. Rollback procedures — keep the old version's image and backups, so you can return if the upgrade runs into problems.

An example rolling upgrade flow:

# 1. Take the first node out of the load balancer rotation
# 2. Run the new version's image on that node
# 3. Wait for /health/ready to indicate it's healthy
# 4. Put it back, then repeat for the next node

The rolling upgrade preserves the SLA: as long as one node is healthy, users don't feel a thing. Especially for database migration, run one node first and watch the logs before other nodes follow suit with the new version.

Pick an upgrade window during quiet hours and test in the staging tenant first. Small and regular upgrades are safer than rare big jumps — the closer your version is to the latest supported one, the smaller the migration leaps you'll have to face.

#Migration

Carrying configuration between realms or environments is daily work:

• Realm export/import — kc.sh export and kc.sh import move the entire realm definition: clients, users, groups, roles, policies, and permissions. Import into a new environment:

kc.sh import --dir /backup/keycloak-config

• User migration — user data moves via the database or import; make sure password hashing is compatible between versions.
• Client migration — clients and redirect URIs come along in export/import; verify metadata and client authentication methods (episode 26).
• Testing migration — always import into the staging environment first, run a complete login flow, then release to production.

Don't forget to back up the deployment configuration itself: environment values, compose files, and customization files. Without them, restoring a database to a new machine remains hard because the outer layer surrounding Keycloak is incomplete.

#Closing

Episode 29 protected your deployment: database backups with pg_dump, configuration backups with kc.sh export, disaster recovery with clear RTO and RPO targets, safe version upgrades with backups and rolling upgrades, and tested realm migrations between environments.

Key takeaways:

• A backup that isn't automated won't happen — schedule it, store it off-site, and verify it.
• RTO and RPO determine the DR design — both must be measured, not guessed.
• An upgrade starts with a backup — migration guide, backup, and rolling upgrade is the mandatory sequence.
• Test recovery periodically — a DR that was never tested is a DR that doesn't exist.

In episode 30 — the final episode — you'll tie everything together: troubleshooting & best practices for facing real problems and a complete checklist before launching Keycloak into production.