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
```
CODE
Export 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 configured
Create a migration directory
```
mkdir migration
```
CODE

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

💊 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