Migrate Mini-USF from version 1 to version 2

Before migration

1. Recreate the service accounts that you had created directly in Keycloak as clients instead of using Unity Dashboard, because all service accounts must follow the common Unity model:
   1. In Unity Dashboard, create the new service accounts that you will use instead of the old ones.
   2. Create a key for each new account, create it also in Unity Dashboard, and save the secrets. The key names use the universally unique identifier (UUID) format names, instead of the free-form names that were used previously.
   3. Assign the required roles to these accounts.
   4. Substitute the keys of the old accounts with the keys of the new accounts wherever services accounts are used, for example, in scripts or in pipelines.
2. Prepare the migration tool to run against the installation of Self-Hosted Deployment and run it in dry run mode. Make sure it runs successfully, and fix any reported errors. To deploy the migration tool in dry run mode, run this command and verify the results:

   kubectl run migrator-tool \ --image=uccmpprivatecloud.azurecr.io/docker/migrator:2026.13.19 \ --restart=Never \ --attach \ --rm -it \ --overrides='{  "spec": {    "securityContext": {      "runAsNonRoot": true,      "runAsUser": 1000,      "runAsGroup": 1000,      "fsGroup": 1000    },    "imagePullSecrets": [{"name": "asset-solutions-docker-credentials"}],    "containers": [{      "name": "migrator-tool",      "image": "uccmpprivatecloud.azurecr.io/docker/migrator:2026.13.19",      "resources": {        "limits": {"cpu": "1", "memory": "1Gi"},        "requests": {"cpu": "200m", "memory": "512Mi"}      },      "envFrom": [        {"secretRef": {"name": "mini-usf"}}      ],      "env": [        {"name": "MINIUSF_DryRun", "value": "true"},        {"name": "MINIUSF_MigrateEntities", "value": "true"},        {"name": "MINIUSF_MigrateRoleAssignments", "value": "true"},        {"name": "ASPNETCORE_ENVIRONMENT", "value": "Production"},        {"name": "MINIUSF_Keycloak_Realm", "value": "unity"},        {"name": "MINIUSF_Keycloak_EventType", "value": "LOGIN"},        {"name": "MINIUSF_Keycloak_EventsMaxNumber", "value": "10000"},        {"name": "MINIUSF_Keycloak__RealmPathPrefix", "value": "auth/realms"},        {"name": "MINIUSF_Keycloak__RealmAdminPathPrefix", "value": "auth/admin/realms"},        {"name": "MINIUSF_Jwt__Issuer", "value": "http://keycloak"},        {"name": "MINIUSF_Jwt__HttpsRequired", "value": "false"},        {"name": "MINIUSF_Jwt__RealmPathPrefix", "value": "auth/realms"},        {"name": "MINIUSF_Keycloak__BaseUri", "value": "http://keycloak"}      ]    }]  }}'

Cannot load library libgssapi_krb5.so.2Error: libgssapi_krb5.so.2: cannot open shared object file: No such file or directory

Migration

Prepare to start the migration

1. Block the network access to the solution for users. To do so, you can temporarily take down the DNS route, because administrators who perform migration still need access.
2. To disable the UNS Sync cron jobs, run this command:

   helm uninstall upc-cronjobs

3. To uninstall Mini-USF, run this command:

   helm uninstall mini-usf

4. Back up the postgres instance that Keycloak and Mini-USF use.

Perform the migration

First part of the migration

1. Run the migration tool in dry run mode. Make sure it runs successfully, and fix any reported errors.
2. Run the migration tool in full mode. The tool copies information from Keycloak to the Mini-USF database, while Keycloak data remains intact. To run the migration tool in full mode, run this command:

   kubectl run migrator-tool \ --image=uccmpprivatecloud.azurecr.io/docker/migrator:2026.13.19 \ --restart=Never \ --attach \ --rm -it \ --overrides='{  "spec": {    "securityContext": {      "runAsNonRoot": true,      "runAsUser": 1000,      "runAsGroup": 1000,      "fsGroup": 1000    },    "imagePullSecrets": [{"name": "asset-solutions-docker-credentials"}],    "containers": [{      "name": "migrator-tool",      "image": "uccmpprivatecloud.azurecr.io/docker/migrator:2026.13.19",      "resources": {        "limits": {"cpu": "1", "memory": "1Gi"},        "requests": {"cpu": "200m", "memory": "512Mi"}      },      "envFrom": [        {"secretRef": {"name": "mini-usf"}}      ],      "env": [        {"name": "MINIUSF_DryRun", "value": "false"},        {"name": "MINIUSF_MigrateEntities", "value": "true"},        {"name": "MINIUSF_MigrateRoleAssignments", "value": "true"},        {"name": "ASPNETCORE_ENVIRONMENT", "value": "Production"},        {"name": "MINIUSF_Keycloak_Realm", "value": "unity"},        {"name": "MINIUSF_Keycloak_EventType", "value": "LOGIN"},        {"name": "MINIUSF_Keycloak_EventsMaxNumber", "value": "10000"},        {"name": "MINIUSF_Keycloak__RealmPathPrefix", "value": "auth/realms"},        {"name": "MINIUSF_Keycloak__RealmAdminPathPrefix", "value": "auth/admin/realms"},        {"name": "MINIUSF_Jwt__Issuer", "value": "http://keycloak"},        {"name": "MINIUSF_Jwt__HttpsRequired", "value": "false"},        {"name": "MINIUSF_Jwt__RealmPathPrefix", "value": "auth/realms"},        {"name": "MINIUSF_Keycloak__BaseUri", "value": "http://keycloak"}      ]    }]  }}'

Second part of the migration

1. To upgrade Mini-USF to version 2, run this command:

   helm upgrade --install --debug -f values.yaml mini-usf mini-usf

2. To assign the global administrator role to the users who need it, complete these steps:

   kubectl run upc-cli -n asset-solutions \--image=uccmpprivatecloud.azurecr.io/docker/upc-cli:1.1.3 \--restart=Never \--attach \--rm \--overrides='{"spec":{"imagePullSecrets":[{"name":"asset-solutions-docker-credentials"}]}}' \-- --fqdn http://mini-usf:8080 --path-prefix="" --no-auth  roles assign --user-id "<id of the user you want to make global admin>" --role-id 812804b0-b643-4579-be8c-ef180e8c2c5a

3. Configure the default access for new users.
   • For the default access to an organization, run this command:

     kubectl run upc-cli -n asset-solutions \--image=uccmpprivatecloud.azurecr.io/docker/upc-cli:1.1.3 \--restart=Never \--attach \--rm \--overrides='{"spec":{"imagePullSecrets":[{"name":"asset-solutions-docker-credentials"}]}}' \-- --fqdn http://mini-usf:8080 --path-prefix="" --no-auth  default-access set-org --organization-id "<id of your default org>" --user-type-id 39943160-54da-49ac-b1c7-bf26adc65855 --role-ids=""

   • For the default access to a project, run this command:

     kubectl run upc-cli -n asset-solutions \--image=uccmpprivatecloud.azurecr.io/docker/upc-cli:1.1.3 \--restart=Never \--attach \--rm \--overrides='{"spec":{"imagePullSecrets":[{"name":"asset-solutions-docker-credentials"}]}}' \-- --fqdn http://mini-usf:8080 --path-prefix="" --no-auth  default-access set-project --project-id "<id of your default project>" --role-ids 4101ecc8-2223-4066-aa4b-6b6f4d0d01e6

After migration

1. Ensure that existing functionality works as expected.
2. Enable the UNS Sync cron jobs.
3. Restore the network access to the solution.