🔁Migration from v2 to v3

To migrate an instance from v2 and v3, you will need the two instances running at the same time.

Migrating the instance settings

Assuming the v2 API is running at https://api-v2.example.com and the v3 API is running at https://toucan.example.com/laputa, you will need to do the following:

1. Login to the v2 instance and fetch the access_token from the cookies by using the inspector tools (open with F12):

   

   The access_token should be shaped like eyJ....

2. Export the settings:

curl -f https://api-v2.example.com/export-instance -H "Authorization: Bearer eyJ..." -o exported-instance.tar.gz

1. Login to the v3 instance and fetch the access_token from the IndexedDB by using the inspector tools.

   

   The access_token should be shaped like _0XBPWQQ_....

2. Import the settings to the v3 instance:

curl -f -X POST https://toucan.example.com/laputa/import-instance/v2 \
   -H "Authorization: Bearer _0XBPWQQ_..." \
   -H "Content-Type: multipart/form-data" \
   -F "[email protected]"

The migration will start asynchronously. You will need to monitor the logs to see when the migration is done.

# Assuming the release name is toucan-stack, and namespace is toucan.
kubectl logs toucan-stack-laputa-0 -n toucan | grep -ai "Import"

You should see:

{"date":"2025-05-27 16:54:14","level":"INFO","pid":88,"thread":140600555514752,"output":{"module":"laputa.app.imports.import_instance_v2","full_message":"ImportInstance :: import finished successfully !"},"small_app_id":null,"task_id":"8436ba33-e206-40d4-8ae1-37b721ccf684","user_id":"..."}

Migrating the apps

Apps are migrated one by one.

Checklist

• Make sure there aren't any refresh data running on the source app v2.

• Make sur the source app v2 is published.

Importing apps

Assuming the v2 API is running at https://api-v2.example.com and the v3 API is running at https://toucan.example.com/laputa, you will need to do the following:

1. Login to the v2 instance and fetch the access_token from the cookies by using the inspector tools (open with F12):

   

   The access_token should be shaped like eyJ....

2. Export the app. The app ID can be found in the URL.

APP_ID="..."
curl -f "https://api-v2.example.com/export-app/$APP_ID" -H "Authorization: Bearer eyJ..." -o "exported-$APP_ID.tar.gz"

1. Login to the v3 instance and fetch the access_token from the IndexedDB by using the inspector tools.

   

   The access_token should be shaped like _0XBPWQQ_....

2. Import the apps to the v3 instance:

curl -f -X POST https://toucan.example.com/laputa/import-app/v2 \
   -H "Authorization: Bearer _0XBPWQQ_..." \
   -H "Content-Type: multipart/form-data" \
   -F "[email protected]"

The migration will start asynchronously. You will need to monitor the logs to see when the migration is done.

# Assuming the release name is toucan-stack, and namespace is toucan.
kubectl logs toucan-stack-laputa-0 -n toucan | grep -ai "Import"

At this point, a snapshot of the app has been imported. You will need to restore the datasource files and connector secrets

Importing the datasources files

1. Go to your newly imported app.

2. Open DATAHUB, select the DATASOURCES tab, click on the three dots of the files and click on replace:

   

   And select your file.

nginx:
  ingress:
    annotations:
      nginx.ingress.kubernetes.io/proxy-body-size: 100m
    path: /
    tls: true

Importing the connector secrets

1. Go to your newly imported app.

2. Open DATAHUB, select the DATASOURCES tab, click on the three dots of data source and click on settings:

   
3. If you are using connectors with OAuth2, you can find the Credentials menu in the workspace settings. Go back to the home page and select the top right menu.

   

Validate the data sources

Go to datasets and run the refresh data button:

Validate the app

At this point, there are no automated fixes available.

Validate and fix every tiles and stories manually.

Migrating the SSO

SSO cannot be easily migrated. Please read the OIDC or SAML2 configuration guide for more information:

Migrating breaking instance settings

Some instance settings needs to be updated.

gotenberg_wait_settings

From:

gotenberg_wait_settings:
  "/new-demo/home-preview": 5
  "/embed.html": 2

To:

gotenberg_wait_settings:
  "/new-demo/home-preview": '5s'
  "/embed.html": '2s'