Skip to content
Tutorials Center
My learning

Topics

Lesson 33 of 37 ยท Deployment and Operations

Backup, Export and Upgrades

Protect Keycloak data with database backups and realm exports, import configuration safely, and plan upgrades with tested rollbacks, migration order and checklists.

Identity data is the one dataset you cannot afford to lose: if the user table disappears, every product built on it stops. This lesson separates two ideas that are often confused, backup (restoring a broken system) and export (moving configuration between systems), then covers how to upgrade Keycloak without surprises.

Keycloak cannot run on this site. Commands are for a Quarkus-based Keycloak and may differ in details between versions. The TryIt blocks are JavaScript stand-ins that compare realm JSON files and check an upgrade path.

Backup is the database

A real backup is a backup of the database. Everything persistent is there: realms, users and credentials, roles, sessions that are persisted, events, and configuration. Use your database's tools: pg_dump or continuous archiving (point-in-time recovery) for PostgreSQL, snapshots on managed services, and always test the restore. A backup that has never been restored is a hope, not a backup.

Also back up what is not in the database:

  • conf/keycloak.conf, Dockerfiles, and deployment manifests (keep them in Git).
  • Custom themes and provider JARs (also in Git or an artifact repository).
  • TLS certificates and keys (secrets store).
  • Vault secrets referenced by realms.
Terminal
# PostgreSQL logical backup (read-only example)
pg_dump --format=custom --file=keycloak-$(date +%F).dump keycloak
# Restore into an empty database
pg_restore --dbname=keycloak_restore --clean keycloak-2026-11-13.dump

Define targets before an incident: RPO (how much data you can lose, for example 5 minutes) and RTO (how long you can be down). Continuous archiving meets small RPOs; nightly dumps do not.

Export and import

Keycloak can export realm data to JSON files and import them back. Useful for:

  • Moving a realm from staging to production.
  • Seeding a local developer environment.
  • Keeping configuration in Git and reviewing changes.
Terminal
# Export all realms to a directory (server stopped or a separate instance)
bin/kc.sh export --dir /tmp/export --users realm_file

# Export a single realm to one file
bin/kc.sh export --file demo-realm.json --realm demo

# Import at startup: place files in data/import and start with --import-realm
bin/kc.sh start --import-realm

The --users option chooses how users are exported: skip, realm_file, same_file, or different_files (the default splits users into files of 50). The import skips a realm that already exists, so it is safe for seeding but cannot update an existing realm.

You can also export from the admin console: Realm settings > Action > Partial export (with options to include groups, roles and clients). Partial export masks secrets (client secrets show as **********) and omits users, so it is a configuration template, not a backup.

Realm configuration as code

For repeatable environments, store realm JSON in Git and apply it with automation. Options include the --import-realm seed for new environments, the Admin REST API, the Keycloak Terraform provider, and community tools such as keycloak-config-cli. Review diffs of the JSON in pull requests: realm settings changes become auditable.

Here is a stand-in that compares two exported realm snippets and flags suspicious differences:

JS Stand-in: diff two realm exports

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Upgrades

Keycloak releases frequently, and security fixes land in patch releases. Treat upgrades as routine, not as projects.

Upgrade procedure

  1. Read the release notes and upgrading guide for every version between yours and the target: pay attention to removed features, renamed options, and database changes.
  2. Back up the database (and verify the restore works somewhere).
  3. Upgrade in staging first with a copy of production data.
  4. Rebuild your custom image: update provider JARs to the matching Keycloak version, re-test themes (templates in custom themes can break across major versions).
  5. Roll out: for one node, stop it, start the new version, and let it migrate the database. For a cluster, follow the supported strategy for your versions: older versions required stopping all nodes (a "recreate" rollout) when the migration was not compatible. Recent versions document rolling updates for patch releases.
  6. Smoke test: log in, run token requests from a test client, check admin console, check events and metrics.
  7. Keep the backup until you are comfortable. Database migrations are usually not reversible, so rollback means restoring the backup.

Skipping many major versions at once multiplies risk. Prefer small, regular steps.

JS Stand-in: plan an upgrade path

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Disaster recovery drill

Once a year (or per release), rehearse: stand up a clean environment, restore the database backup, deploy the same image with the same configuration, and verify a user can log in. Time it and compare with the RTO. Write the runbook down while you do it.

Common mistakes

  • Treating a partial realm export as a backup (it has no users and masks secrets).
  • Importing a realm and expecting it to update an existing realm.
  • Upgrading production first.
  • Forgetting custom providers and themes in the upgrade.
  • Backing up only the database but losing the encryption keys or TLS certificates stored elsewhere.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the real backup of a Keycloak deployment?

    All persistent data is in the database; exports are for moving configuration.
  2. 2. What happens when you import a realm that already exists with --import-realm?

    Existing realms are left untouched, so imports seed new environments rather than update them.
  3. 3. Why is rolling back a Keycloak upgrade usually a database restore?

    The new version migrates the schema forward; older versions cannot read it.
  4. 4. Which two numbers define how much loss and downtime you accept?

    Recovery point objective (data loss) and recovery time objective (downtime) drive backup design.

Summary

  • Back up the database and keep configuration, themes, and providers in version control.
  • Export and import move realm configuration; partial export is not a backup.
  • Upgrade staging first, update providers and themes, and test the restore.
  • Define RPO and RTO and rehearse recovery.

Next: Project: A Single-Page App with PKCE