Realm Export & Import

Realm Export and Import let you move a single realm, with all of its users and their credentials, between clusters or in and out of Skycloak. Use it to back up a realm before a risky change, promote a realm from a staging cluster to production, or bring an existing Keycloak realm into Skycloak.

Unlike Database Export, which captures a whole cluster’s database, this works at the level of one realm and produces a standard Keycloak realm file.

Plan Requirements

Realm Export and Import are available on Launch, Business, and Enterprise plans. They are not available on Trial or Developer plans.

What is included

A realm export is a complete, faithful copy of one realm:

• Realm configuration (login, tokens, sessions, required actions)
• Clients, client scopes, and roles
• Identity providers and mappers
• Authentication flows
• Groups
• Every user, with all of their credentials (password hashes, OTP, and other stored factors)

Because the artifact contains credentials, it is always encrypted.

Exporting a realm

1. Open the cluster you want to export from on the Clusters page.
2. Open the realm you want to export, or find it in the realms list.
3. Choose Export (on the realm overview, or from the realm’s actions menu in the list).
4. Set a password to encrypt the export, then start it.

The export runs in the background, so you can close the dialog and keep working. You will receive an email when it is ready.

The export artifact

• Format: a standard Keycloak realm file (the same shape Keycloak’s own kc.sh export produces), wrapped in an AES-256-CBC encrypted envelope.
• Encryption: the file can only be opened with the password you set. Keep it safe. Skycloak cannot recover it for you.
• Retention: the download is available for 24 hours, after which the file is permanently deleted. Download it and store it wherever you keep your backups. You own it from that point on.

Importing a realm

You can import a realm into any cluster on a Launch plan or above.

1. Open the cluster you want to import into, and go to its realms list. If the cluster has no realms yet, you will see Import Realm next to Create Realm in the empty state.
2. Choose Import realm.
3. Upload your realm file and, if it is encrypted, enter its password.
4. Start the import. It runs in the background and emails you when it finishes.

The realm name comes from the file itself, so there is nothing else to fill in.

What you can import

• A Skycloak realm export (the encrypted file described above). Enter the password you set when exporting.
• A plain Keycloak realm export produced by any Keycloak server (for example, the output of kc.sh export). This is how you bring an existing realm into Skycloak. No password is needed for a plain, unencrypted file.

Before the import runs

Skycloak checks a few things up front and stops with a clear message if the import cannot succeed safely:

• Version compatibility. The target cluster’s Keycloak version must be the same as, or newer than, the version the realm was exported from. Importing into an older version is blocked.
• Name collision. If a realm with the same name already exists on the cluster, the import stops. Delete or rename the existing realm first, then import again.
• Credential compatibility. If the realm uses a password-hashing algorithm the target cluster does not support, the import is blocked so users are never locked out.

Notes and limitations

• Exports and imports cover a full realm. Partial or selective exports are not available.
• An import creates the realm on a running cluster, so its users can sign in immediately once it completes.
• If an import fails partway through, Skycloak does not automatically delete what was created and does not silently retry. The failure message tells you what to do (usually: delete the partial realm, then import again). This avoids ever destroying a realm that actually imported.