ACCESS: Permissions migration known issues

Motivation - New Permissions Model

Simplifies the UI user flows to configure all resource types.
Standardization of permissions’ Custom data structure.
Flexibility to cover more authentication structures and release new features faster.

Solution - New Permissions Model

JFrog Access service is the sole owner of permissions models and authorization logic.
Creates a single unified permission model for all services needs
No ‘free text’ (=Custom data) in the permission model. All data is standardized.
Full Backward compatibility
- Migrates all existing permissions to the new model
- Provides new APIs, while still supporting the legacy APIs with the legacy permissions model.
Simplifies permissions UI.

Migration Known Issues

A migration is added to support full backward compatibility:

Creates new permissions tables.
Locks legacy permissions table to prevent data loss.
Converts all existing permissions to the new model, and inserts them to the new tables.

Known issue # 1 - Cannot Modify Permission error

Description:

Migration locks the old tables so that no new data is inserted into them. If an old node tries to perform a change to the old permissions table (via UI/API) during migration, the user will get the following error:
'JFrog migration is running in the background, cannot modify permissions, please wait for the migration to finish'

Solution:

Wait until migration for all nodes is complete. The error will not be thrown after the migration is complete.

Known Issue # 2 - Long Migration time for large customers

Description:

A large customer is a customer that has more than 100K Permissions.

Migration might take a few minutes for large customers. During migration, the JFrog Access service will not communicate with the other internal JFrog services.
Currently, all internal JFrog services are waiting for 5 minutes for JFrog Access to start. In case JFrog Access service does not respond during this time, they shutdown.

Solution:

Configure the services to wait for 10 minutes to allow JFrog Access service the time it needs to migrate.

Case # 1:

If you are a large customer and haven’t started the migration
Action Item: Go to system.yaml and set the following values:

shared:
    security:
        bootstrapKeysReadTimeoutSecs: 600
frontend:
    startup:
        ping:
            retries: 600
    accessClient:
        join:
            retries: 600

observability:
  accessClient:
    joinTimeoutMins: 10
    pingTimeoutMins: 10

metadata:
  accessClient:
    joinTimeout: 10m

jfconnect:
  accessClient:
    joinTimeoutMins: 10
    pingTimeoutMins: 10

event:
  accessClient:
    joinTimeout: 10m
    pingTimeout: 10m

Case # 2:

If you are a large customer and your migration failed since it took a long time.
Action Item: Wait until the migration is complete and restart the entire system.

Known issue # 3 - Migration Lock Database Tables failure

Description:

For the migration to work properly, and to avoid data loss, the first step is locking the legacy permissions tables.
The lock is done by creating a trigger that throws an error when a customer tries to manipulate the old permissions tables.
Creating these triggers requires the DB user to have special grants. For example, in MySQL/MariaDB, the user has to have SUPER user grants.
If the user doesn't have the proper permissions to create these triggers, the migration will fail.
The migration name is: V7_82_0_1__PermissionsV2DataMigration

Solution:

Step #1
Remove the failing migration from the DB with the following command:
DELETE from access_schema_version where version='7.82.0.1'
This allows the migration to run again on the next restart (DO NOT RESTART AT THIS POINT).

Step #2
Choose one of the following solutions:
1. Elevate the DB user permissions so it can create TRIGGERs.
2. If you’re using MySQL or MariaDB, set the flag
SET GLOBAL log_bin_trust_function_creators = 1;
which allows the creation of TRIGGERs and FUNCTIONs.
You can remove the flag after the migration is complete.
3. Starting Artifactory 7.77.5, you can manually review and apply the TRIGGERs to your DB and skip their automatic creation during the migration.
The trigger scripts for the different DBs are attached in this zip file.

To skip the trigger creation, set either one of the following properties:
Java System property:
jf.access.skip_pv2_legacy_tables_lock=true
Environment Variable:
JF_ACCESS_SKIP_PV2_LEGACY_TABLES_LOCK=true

Important: Do not restart the migration and skip the TRIGGERs creation before manually setting the TRIGGERs!
It can cause a data loss of permissions in the system (if you add/remove/edit permissions while some nodes in your JPD were not upgraded, you will lose these changes).

Step #3
You are ready to run the migration again.
Upgrade your nodes to the new version, the migration will succeed.

Migration Logs

You can find the migration logs in access-service.log

Successful migration -

“Migration Summary: Conversion of 61 legacy permissions to 61 v2 permissions succeeded in 0 seconds”

Migration details for debugging - in the log file look for log class

“PermissionsV2DataMigration”

If some permissions were not migrated, you will see a log with the failed permissions:

“{#number_of_permissions} Permissions were not migrated. Permissions {#permission_details}”

If you get Permissions that were not migrated or experience unexpected behavior contact JFrog Support.

Note

If you experience unexpected behavior in the permission/authorization area, contact JFrog Support.