Labfolder - Migrating from a Previous Installation

Labforward supports migrating all the business data to the new installation.

Available on the Labforward Platform version 2.33.3.

TABLE OF CONTENTS

• General Recommendations
• Migration Process
• Rollback
• Recommended Steps
• Connect to the Previous MySQL Database
• FOS Migration
• Embedded Database Migration (Required only if you want to move to the embedded database)
• IAM Migration
• Following Up the Embedded Database Migration
• Following Up on the FOS Migration
• Following Up on the DB Clean-Up

General Recommendations

Installing the Kubernetes cluster in a different VM than the previous installation is recommended. Creating a new VM will ensure no leftovers from the previous installation. 

Installing it in the same VM is possible, but Labforward does not support removing old installation data and components.

It is possible to connect to any database external to the new Kubernetes cluster, including the previous installation database. In this case, only part of the migration process is required, as explained below. 

For more details about Embedded and External databases, check the Persistent Data section at Data Peristency.

It is essential to clarify that the data can not be lost in any of these processes, regardless of any combination of properties. The data will be available anytime in the new or old environment.

This process is very versatile. If the recommended approach does not meet your requirements, please contact Labforward to discuss a different migration plan.

Migration Process

The process consists of the three unrelated migrations:

1. Connect the Kubernetes environment to the previous MySQL database. If possible, stop the previous Labfolder docker containers and back up the database before proceeding;

2. FOS - Move all binary data from the relational database to the File Object Storage. This step is mandatory for everyone with a previous installation;

3. Embedded Database - Moves all the database data from the external source to the embedded database. Labforward can connect and keep using any external database. Hence, this step is only for those who want to move to the embedded database managed by Labforward;

4. IAM - Move the authentication-related data to Labforward’s Identity and Authentication Manager. This step is unnecessary if you use an external Identity Provider, such as LDAP. After configuring LDAP, all users can log in with their current accounts;

The releases will be locked at version 2.34.3. When the migration is completed, send a support request to Labforward asking to update your license. After the license update, version 3+ will be available to download and deploy via the admin console. From this point forward, you will receive new versions on a weekly basis. 

No further manual actions are required to update after the migration.

Rollback

While every precaution has been taken to ensure a smooth transition, we recognize the importance of being prepared for unforeseen situations.

If the IT admin detects errors or anomalies during or after the migration, do the following:

1. Capture Evidence: Take screenshots of screens, error messages, or any relevant information that can help diagnose the problem. If possible, keep the VM/server with the problematic environment;

2. Rollback to the Previous Infrastructure: Restart the Docker-based infrastructure using the following script:

./labfolder.sh start

In case you already made changes to the DNS, make sure it is pointing out to the expected environment;

3. Contact Labforward: Open a support request describing the situation.

Recommended Steps

It is highly recommended to back up the database and stop the previous Labfolder application before starting the following process. Only the previous MySQL should be up and running.

If you need to identify the downtime window before the real migration, it is recommended to spin up a snapshot of the database and test the full process using this isolated database before shutting down the previous application.

It is not possible to estimate the migration duration without testing it out. However, completing all steps in less than one day is usually possible.

Connect to the Previous MySQL Database

1. Stop all Labfolder docker containers, except for the MySQL database:

./labfolder.sh stop

 a. Confirm that all containers stopped after this command.

2. Back up the Database;

3. Make sure the previous database is accessible from the Kubernetes cluster. In this example, it gives access to any IP in your network to the MySQL server. Optionally, you can replace ‘%' and '0.0.0.0’ with only the Kubernetes host IP

Permit access from the Kubernetes host to the MySQL server:

a. Open the MySQL configuration file, usually located in /etc/mysql/mysql.conf.d/mysqld.cnf. Then, edit the bind-address to bind-address = 0.0.0.0.

b. Connect to the MySQL database using the root user (the root password can be found on the server.yaml file in the same folder as the Labfolder script):

mysql -u root -p

c. Give access to the Kubernetes host to the root user:

UPDATE mysql.user SET host='%' WHERE user='root';

GRANT ALL PRIVILEGES ON labfolder.* TO 'root'@'%';

d. Check if the root user can be accessed from anywhere (%). The result of the query should contain the user root and the host % (or the IP you provided from the Kubernetes cluster):

select host, user from mysql.user;

e. Ensure the MySQL root password (or the user updated above) does not contain any special characters. There is a limitation in the migration process, which blocks the connection if the password contains special characters.

f. Restart the MySQL server. From the terminal, run:

sudo systemctl restart mysqld

4. Open the admin console Configs in the new environment;

5. Include the connection data for the External Database in Labfolder & Labregister Configurations → Labfolder Database (MySQL) → Show Database Configurations → External MySQL. This is the database from which Labforward will extract the data. The full JDBC address is required, as the example:

6.You don’t need to deploy now. In the same configuration screen, proceed to the FOS Migration configurations.

FOS Migration

1. Open the admin console Configs;

2. Adjust the FOS size (This step is required only if you provided your own cluster and your storage provider requires the PV storage size. If you installed using the Labforward cluster, you can skip this step):

a. Insert the same size as the previous database in File Object Storage Configurations → Embedded MinIO Configuration →  Show MinIO Configurations →  MinIO storage size;

3. Select the Show Object Storage Configurations checkbox in Labfolder & Labregister Configurations → Object Storage Configurations;

4. Select the properties: Migrate Binary Files to Object Storage and File Object Storage Enabled:

5. Click on Save Config at the bottom of the page;

6. Go to the Dashboard or the Version History menu and click Deploy in the new version. When this version is deployed, the migration will start;

7. Wait for the FOS migration to complete and validate it. Check the Following Up on FOS Migration section.

8. In the admin console, enable the Clean up Database Binaries and Stop Inserting Files in the Database properties.  Check the Following Up on DB Clean Up section;

a. The “Clean up Database Binaries” is the only property that will physically delete the files from the database. Even if this flag is enabled, the application verifies if each file is present in the Object Storage before deleting it. Unmigrated files are not going to be deleted;

b. The “Stop Inserting Files in the Database” will store new files only in the FOS Object Storage.

9. Click on Save Config, go to the Dashboard or the Version History menu, and click Deploy in the new version. When this deployment is completed, the application will start removing the migrated files from the database;

10. When the FOS migration is completed and validated, return to the admin console and keep only the File Object Storage Enabled and Stop Inserting Files in the Database flags enabled. Lastly, deploy the version with only these two flags enabled:

Embedded Database Migration (Required only if you want to move to the embedded database)

1. Open the admin console webpage;

2. Go to Config;

3. Select the Show Database Configurations checkbox in Labfolder & Labregister Configurations → Labfolder Database (MySQL);

4. Select Embedded MySQL;

5. Select the MySQL Version referent to your current Database;

6. Adjust the LF/LR MySQL storage size according to your current database size (This step is required only if you provided your own cluster and your storage provider requires the PV storage size. If you installed using the Labforward cluster, you can skip this step):

a. Measure the size directly on disk or equivalent (For example, with the command du -h). If you measure it using SQL from inside the database, it will give you a size bigger than required due to unnecessary caches and indexes;

b. Increase the size from the previous step by 50%.

7. Select MySQL Migration Between Databases (Use the same version as your original MySQL database, usually version 5.7 at this point):

8. Include the host (only the hostname. No protocol, and no port in the Datasource host), username (usually root), and password to connect to the previous database (the same one used in the FOS migration). This is the source database for the migration process. You can use the same username and password as the previous Labfolder application:

9. Click on Deploy at the bottom of the page;

10. Go to the Dashboard or the Version History menu and click Deploy in the new version. This will deploy a new version of Labfolder to migrate to the embedded database. The Labfolder application in the new platform will be disabled during the migration. Make sure to shut down all the previous Labfolder docker images, except for the MySQL database, before starting this process;

11. Check the Following Up on the Embedded Database Migration section to check when the database migration is completed;

12. When the migration is completed, return to the admin console webpage and disable the MySQL Migration Between Databases property;

13. Deploy it again. Now, Labfolder will start using the embedded database.

IAM Migration

No migration is required if you use any Identity Provider, such as LDAP. Proceed to the configuration of your specific IDP at IAM/LDAP Setup.

IAM manages the user’s data and credentials in the Kubernetes environment.

Check the detailed IAM migration process at Users migration to IAM.

Following Up the Embedded Database Migration

There are different places to follow up the migration:

1, The status in the admin console. It will turn Ready only when the migration is completed:

2. Check the migration process output:

sudo kubectl logs -f lf-db-migration-0 -c migration

Following Up on the FOS Migration

Go to the terminal and type:

sudo kubectl logs -f -l  app.kubernetes.io/component=labfolder-labregister-chart-task-executor

When the Pending files reach zero, the migration is completed.

Following Up on the DB Clean-Up

Go to the terminal and type:

sudo kubectl logs -f -l  app.kubernetes.io/component=labfolder-labregister-chart-task-executor

It will constantly log the number of files being deleted and their table:

The clean-up process is completed when you see the message:

All binary files have been removed from the DB.