keycloak-migration-doctor

Keycloak migration doctor

Export and import failures look opaque because the dashboard notice is generic: "Job has reached the specified backoff limit" is a retry counter, not a cause. The cause is usually in the job record already, in the error_message field that skycloak_get_export, skycloak_get_realm_export and skycloak_get_realm_import all return. Reading it is the single highest-value step here. If a job has already failed, go straight to Diagnose; if the move has not run yet, start with Preflight.

Preflight: before an export, import or migration

1. Pin down the unit with the user: a whole-cluster database dump (skycloak_create_export), one realm's archive (skycloak_create_realm_export), or a realm import into Skycloak (skycloak_create_realm_import). Find the cluster with skycloak_list_clusters, then skycloak_get_cluster: it must be available, and note its Keycloak version, because an archive from a newer major does not import into an older target.
2. For an import, call skycloak_list_realms on the target: the import refuses a realm-name collision with a 409 rather than overwriting, so a taken name is better discovered now than on migration day.
3. Check the known blockers, all taken from support history:
   • Script-based authorization policies. Current Keycloak only loads JavaScript policies packaged in a deployed scripts JAR, so realms whose clients still carry admin-console script policies fail; the classic offender is a policy named "Default Policy" that old versions auto-created on authorization-enabled clients. No tool lists client policies, so use skycloak_list_applications to enumerate the clients and have the user clear script policies under each client's Authorization > Policies in the admin console. The dry run below catches any they miss.
   • The legacy /auth path. Keycloak dropped the /auth URL prefix in 17 and Skycloak clusters serve the modern paths, so anything with the old prefix hard-coded breaks after the move even though the import itself succeeds. Ask now.
   • partial-export never includes users. Keycloak's built-in partial export excludes users by design. A plan of "partial export, import, log in" fails at the login, not the import; users need a full realm export.
   • Feature flags. If the source relies on a Keycloak feature flag, check skycloak_list_cluster_features. A flag absent from that list is reserved for the platform operator; escalate rather than promise it.
4. Dry run now. The cheapest preflight is running the export today and polling it: a failure with error_message in hand this week beats the same failure on migration day. Realm archives are always encrypted: ask the user for a password, never invent one, and say the same password is needed again at import.