Keycloak Migration
Prerequisite
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
cd /opt/keycloak
CODEExport the current running keycloak configuration
bin/kc.sh export --dir <dir> --users same_file
CODE→ This will export the current configuration in
<dir>
generating as many pairs of configuration files (`<realm>-realm.json
and<realm>-users-0.json
) as they are realms configuredCreate a
migration
directorymkdir migration
CODECopy 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/
CODEOR Keep Existing Realm config & New Users set
cp <dir>/lissi-cloud-realm.json migration/ cp imports/lissi-cloud-users-0.json migration/
CODEOR 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
đź’Š Troubleshooting
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