The following migration guide assumes that new configuration files have been imported in
/opt/keycloak/imports. As the default keycloak migration strategy is set to
IGNORE_EXISTING protecting against undesired users deletion on container restart.
🛠 Migration steps
The following steps provide a template guide toward a clean migration.
Run a bash in the keycloak container and navigate to the Keycloak base directory
Export the current running keycloak configuration
bin/kc.sh export --dir <dir> --users same_fileCODE
→ This will export the current configuration in
<dir>generating as many pairs of configuration files (
<realm>-users-0.json) as they are realms configured
Copy the desired pair of users & realm file into the migration folder
Keep Existing Users set & New Realm config
cp <dir>/lissi-cloud-users-0.json migration/ cp imports/lissi-cloud-realm.json migration/CODE
OR Keep Existing Realm config & New Users set
cp <dir>/lissi-cloud-realm.json migration/ cp imports/lissi-cloud-users-0.json migration/CODE
OR New Realm config & New Users set
cp imports/lissi-cloud-users-0.json migration/ cp imports/lissi-cloud-realm.json migration/CODE
Start the migration
bin/kc.sh start \ -Dkeycloak.migration.action=import \ -Dkeycloak.migration.provider=dir \ -Dkeycloak.migration.dir=/opt/keycloak/migration \CODE
It might happen that the migration fails, reasons such as references to non-existing resources in the new version are most likely the cause.
In that particular case some manual changes must be brought to the old kept configuration (realm or users).
As the keycloak container do not offer any text editor, one must first pull the configuration file to be modified, sync the file locally, thus removing all non-existing references then push the modified version back to the keycloak container. Finally run again the migration command