Upgrade Tessellation to v3
This page is a dedicated procedure specifically for upgrading your Constellation Network node from Tessellation v2 to Tessellation v3.
Last updated
Was this helpful?
This page is a dedicated procedure specifically for upgrading your Constellation Network node from Tessellation v2 to Tessellation v3.
Last updated
Was this helpful?
With the exciting announcement that the Constellation Network's MainNet will be upgraded to a stable release of v3, this documentation provides a straightforward guide to help you through the process.
It outlines what to expect and the steps required to upgrade from v2 to v3, ensuring a smooth and successful transition.
The latest version of Tessellation is a major upgrade that introduces breaking changes.
From a Node Operator’s perspective, the Constellation Network Team has worked diligently to ensure that all necessary components are in place for a simple and seamless migration from version 2 to version 3.
If you plan to upgrade manually using Constellation Network's nodectl utility, you should disable auto-restart and auto-upgrade features before the cluster upgrade (restart) begins.
Failing to do so may break your manual upgrade sequence, as the auto upgrade could interfere with the manual intervention process.
In order to utilize the nodectl utility to run Tessellation v3 you will need to be running version v2.15.2 or newer of nodectl. Version v2.17.3 is recommended.
These steps will be covered in this guide.
Please follow the nodectl upgrade path properly to ensure you do not run into any inconsistencies or issue later.
The nodectl utility v2.15 will be the final version to support the following Debian-based distributions:
Ubuntu 20.04 and earlier
Debian 11 and earlier
You may safely upgrade nodectl to 2.15.2 and continue using the listed Debian-based distributions.
If mission-critical updates (hotfixes) are required, they will be supported for this version until June 2025.
Do not upgrade to nodectl v2.16.0 (or higher) if you are running any version of Debian or Ubuntu listed above.
Starting with v2.16.0 and beyond, support for these operating systems is officially removed.
To continue receiving updates, improvements, and full support, please upgrade your operating system to a supported version.
Please follow the correct upgrade path to ensure your node remains manageable by nodectl and does not encounter compatibility issues.
If there are multiple versions between your current version and v2.17.3, you must follow the correct upgrade path.
Take note of each intermediate version and run the upgrade_nodectl command sequentially for each version step using the -v <version> option.
Upgrade one version at a time. Do not skip versions until you reach v2.16.0. This ensures compatibility and prevents potential issues with configuration or functionality.
Example: sudo nodectl upgrade_nodectl -v v2.13.0
If you are requested to upgrade the node, issue a Y and allow nodectl to upgrade the node so that all the features, changes, and updates can be properly applied.
This is important to ensure that all features of nodectl are enabled.
When you reach a version that can be directly upgraded to the latest v2.17.3 you may exclude the -v option.
If you have auto-upgrade enabled on your node, nodectl will automatically detect the upgrade and attempt to perform all necessary migration steps as outlined in the next section.
However, it's important to keep two key points in mind when relying on auto-upgrade:
The migration may take time. Interrupting it can cause the node to fail the migration, leading to recovery behavior where the node attempts to download all snapshots from genesis. This introduces two major issues:
⏳ It may take days to download all snapshots.
💾 You may retain residual v2 snapshots, which could consume excessive disk space and potentially cause your node to run out of storage.
If you're returning to check the results of an upgrade hours after it occurred, simply run the following command to verify that your node is in Ready state.
If you plan to be actively available during the upgrade, follow these steps to ensure your node re-joins the cluster properly and to avoid any unexpected issues:
Allow the upgrade process to complete without interruption
Alternatively, monitor the node closely during the process.
If you have auto restart with auto upgrade enabled, and the cluster has already restarted, do not attempt to upgrade. This may cause unexpected behavior.
You will perform the upgrade as normally done, no additional steps required. The nodectl utility will disable auto restart if it is engaged, and reengage upon completion.
or
use the --ni option ( non-interactive )
This option will choose all the default options for any questions normally asked by nodectl during the installation process.
Before downloading the latest Tessellation binaries and attempting to rejoin the network cluster, it is strongly recommended to migrate your snapshot data directories from the old v2 structure to the new v3 structure.
⚠️ Failure to migrate will result in your node attempting to redownload and install all snapshots from genesis, which can lead to delays and increased resource usage.
You may replace v2.17.3 with v2.15.2 if necessary ().
The Constellation Network team has provided a data migration script to assist with this process, located .