Labfolder - Migrating from a Previous Installation

Modified on Thu, 1 Aug at 10:20 AM

Labforward supports migrating all the business data to the new installation.
Available on the Labforward Platform version 2.34.1.

TABLE OF CONTENTS

General Recommendations
Migration Process
Recommended Steps
Following Up on 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 removing old installation data and components is not supported by Labforward.

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 get in touch with Labforward to discuss a different migration plan.

Migration Process

The process consists of three unrelated migrations:

Connect the Kubernetes environment to the previous MySQL database. If possible, stop the previous Labfolder docker containers and back up the database before proceeding;
FOS - Move all binary data from the relational database to the File Object Storage. This step is mandatory for everyone with a previous installation;
Embedded Database - Moves all the database data from an external 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;
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.1. When the migration is completed, send a support request to Labforward asking to update your license. After the license update, you will receive version 3.9+ and all next weekly updates normally.

No further manual actions are required for any 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.

In the event that the IT admin detects errors or anomalies during or after the migration, do the following:

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;
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;
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.

Connect to the Previous MySQL Database

Stop all Labfolder docker containers, except for the MySQL database:
```
./labfolder.sh stop
```
1. Confirm that all containers stopped after this command.
Back up the Database;
Make sure the previous database is accessible from the Kubernetes cluster. In this example, it is giving 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

a. Give access to the Kubernetes host to the labfolder user:
```
UPDATE mysql.user SET host='%' WHERE user='labfolder';
GRANT ALL PRIVILEGES ON labfolder.* TO 'labfolder'@'%';
FLUSH PRIVILEGES;
```
b. Permit access from the Kubernetes host to the MySQL server:
Open the MySQL configuration file, usually located in /etc/mysql/my.cnf. Then, edit the bind-address to bind-address = 0.0.0.0.
The migration components do not support MySQL passwords with special characters. Ensure the password contains only letters and numbers.
Include the connection data for the External Database in Labfolder & Labregister Configurations → Labfolder Database (MySQL) → Show Database Configurations → External MySQL. This is the database that Labforward will extract the data from:

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

FOS Migration

Open the admin console Configs;
Adjust the FOS size (Ignore this step if you are using an external Object Storage):
1. Insert the same size as the previous database in File Object Storage Configurations → Embedded MinIO Configuration → Show MinIO Configurations → MinIO storage size;
Select the Show Object Storage Configurations checkbox in Labfolder & Labregister Configurations → Object Storage Configurations;
Select the properties: Migrate Binary Files to Object Storage and File Object Storage Enabled:
1. The “Clean up Database Binaries” is not necessary for the migration. This 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;
2. The “Stop Inserting Files in the Database” can be enabled after you are confident with the migration results. After enabling it, new files will be persisted only in FOS. Do not enable it before validating that the migration is completed.
Click on Save config at the bottom of the page;
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;
Wait for the FOS migration to complete and validate it. Check the Following Up on FOS Migration section.
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;.;
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;
Notice that after the FOS migration, the external database size should shrink between 60% and 90% of its previous size. If it does not shrink, you need to optimize the MySQL tables. Connect to the origin database and execute the following queries:
```
OPTIMIZE TABLE labfolder.storage_document;
OPTIMIZE TABLE labfolder.inventory_file_upload;
```
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)

Open the admin console webpage;
Go to Config;
Select the Show Database Configurations checkbox in Labfolder & Labregister Configurations → Labfolder Database (MySQL);
Select Embedded MySQL;
Select the MySQL Version referent to your current Database;
Adjust the LF/LR MySQL storage size according to your current database size. Remember to use the new size after the FOS migration
1. 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;
2. Increase the size from the previous step by 50%.
Adjust the Embedded Database resources. Labforward recommends starting with a similar amount of CPU and memory as your previous database:
1. Select the Show Advanced Resources Configurations checkbox in Labfolder & Labregister Configurations → Resources;
2. Define the MySQL resources as your requirements. It is recommended to use the same value as the previous database. Using the same value for the Minimum and Maximum memory is a good practice. The admin can change these values at any moment:
Select MySQL Migration Between Databases:
Include the host (only the hostname, no protocol and no port), username, 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:
Click on Save Config at the bottom of the page;
Go to the Dashboard or the Version History menu and click Deploy in the new version. This will deploy a new version of Labfolder responsible for migrating 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;
Check the Following Up on the Embedded Database Migration section to check when the database migration is completed;
When the migration is completed, return to the admin console webpage and disable the MySQL Migration Between Databases property;
Deploy it again. Now, Labfolder will start using the embedded database.

IAM Migration

At this point, all the data is in the new environment. Still, copying the user's credentials to the Identity and Access Manager (IAM) application is necessary.

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

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.

Following Up on the Embedded Database Migration

There are different places to follow up the migration:

The status in the admin console. It will turn Ready only when the migration is completed:
Check the migration observer. Every 45 minutes, It counts the number of rows in the source and target databases. Run the command:
```
sudo kubectl logs -f lf-db-migration-0 -c observer
```

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

It will log the current status every 15 minutes:

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

Connect to MinIO to see the migrated files:

1. Get the username and password:
Username:

sudo kubectl get secret file-object-storage-app-chart-minio  -o jsonpath="{.data.rootUser}" | base64 -d

Password:

sudo kubectl get secret file-object-storage-app-chart-minio  -o jsonpath="{.data.rootPassword}" | base64 -d

2. Port forward MinIO:

sudo kubectl port-forward service/file-object-storage-app-chart-minio-console 9001:9001

3. Open localhost:9001 in the browser and log in with the credentials above.

a. If you do not have access to the browser, run the command:

kubectl get service file-object-storage-app-chart-minio-console -o jsonpath='{.spec.clusterIP}'

b. Open a terminal in your local host machine, and type:

ssh {{user}}@{{kubernetes-host-ip}} -L 9001:{{service-ip}}:9001

i. {{user}} = the same user name as the host running the kubernetes cluster

ii. {{kubernetes-host-ip}} = the kubernetes host IP

iii. {{service-ip}} = the result of the 3.a. command.

c. Make sure the port-forward command is still running (item 2.). Now you will be able to access localhost:9001 from your local machine.

4. You should see the bucket with all the migrated data:

5. Notice that the number of Objects should match with the Files Migrated to Object Storage log message;

6. Optionally, you can navigate through the bucket and download objects.

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.

Optionally, connect to the database and check each table in the log messages. The clean-up process sets the binary column value to '' (empty string):