7. How to migrate ArmoniK.Core dependencies during upgrade ?

7.1. Migration policy

Most minor version upgrades are transparent and require no manual steps — simply update the Docker images to the new tag and restart the deployment.

Manual migration steps are required only when a release changes the database schema (MongoDB collections) or the authentication table structure. Such changes are documented in the sections below. If a version is not listed here, no migration is needed.

Before any migration:

1. Back up your MongoDB data before running any migration script.

2. Test the migration procedure in a staging environment before applying to production.

3. If the migration fails, restore from backup and re-deploy the previous version.

7.2. 0.29.x -> 0.30.x

7.2.1. Database

This version changes the structure of a Result in the database. It introduces a new field called OpaqueId which holds the identifier of its associated value in the Object Storage. Previously, the ResultId was used. The following MongoDB request converts the ResultId into the OpaqueId to support the new implementation.

db.Result.updateMany({},
    [{
        $addFields: {
            OpaqueId: {
                $function: {
                    body: function(data) {
                        const base64Chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
                        const bytes = [];
                        for (let i = 0; i < data.length; i++) {
                            bytes.push(data.charCodeAt(i));
                        }

                        let base64 = '';
                        let i = 0;
                        while (i < bytes.length) {
                            let byte1 = bytes[i++] || 0;
                            let byte2 = bytes[i++] || 0;
                            let byte3 = bytes[i++] || 0;

                            let enc1 = byte1 >> 2;
                            let enc2 = ((byte1 & 3) << 4) | (byte2 >> 4);
                            let enc3 = ((byte2 & 15) << 2) | (byte3 >> 6);
                            let enc4 = byte3 & 63;

                            if (isNaN(byte2)) {
                                enc3 = enc4 = 64;
                            } else if (isNaN(byte3)) {
                                enc4 = 64;
                            }

                            base64 += base64Chars[enc1] + base64Chars[enc2] + base64Chars[enc3] + base64Chars[enc4];
                        }

                        return BinData(0, base64);
                    },
                    args: ["$_id"],
                    lang: "js"
                }
            }
        }
    }])

7.3. 0.34.x -> 0.35.x

7.3.1. Database

This version changes the structure of the authentication related tables (AuthData, RoleData and UserData). Identifiers are now integers instead of strings. They are also used to build the relations between items in the database. The migration procedure is to delete the three tables, set up initialisation related environment variables for authentication that can be found here and let ArmoniK regenerate the database.

Before deleting tables: ensure you have a full MongoDB backup. Deleting these tables removes all existing users, roles, and user–certificate associations (the certificates themselves are not deleted) — users and roles must be re-provisioned via environment variables after the migration.