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.

1. Run a bash in the keycloak container and navigate to the Keycloak base directory

   CODE

   cd /opt/keycloak

2. Export the current running keycloak configuration

   CODE

   bin/kc.sh export --dir <dir> --users same_file

   → 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

3. Create a migration directory

   CODE

   mkdir migration

4. Copy the desired pair of users & realm file into the migration folder

   1. Keep Existing Users set & New Realm config

      CODE

      cp <dir>/lissi-cloud-users-0.json migration/
      cp imports/lissi-cloud-realm.json migration/

   2. OR Keep Existing Realm config & New Users set

      CODE

      cp <dir>/lissi-cloud-realm.json migration/
      cp imports/lissi-cloud-users-0.json migration/

   3. OR New Realm config & New Users set

      CODE

      cp imports/lissi-cloud-users-0.json migration/
      cp imports/lissi-cloud-realm.json migration/

5. Start the migration

   CODE

   bin/kc.sh start \
     -Dkeycloak.migration.action=import \
     -Dkeycloak.migration.provider=dir \
     -Dkeycloak.migration.dir=/opt/keycloak/migration \

💊 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