🚧Upgrade Tessellation to v3
This page is a dedicated procedure specifically for upgrading your Constellation Network node from Tessellation v2 to Tessellation v3.
Introduction
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.
BEFORE YOU BEGIN
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.
The nodectl Utility
Prerequisites and Deprecations
🔧 Prerequisites
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.
⚠️ Deprecations
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.
Upgrade nodectl in Preparation for the Cluster Upgrade
Upgrade if necessary
Please follow the correct upgrade path to ensure your node remains manageable by nodectl and does not encounter compatibility issues.
sudo nodectl upgrade_pathYou may replace v2.17.3 with v2.15.2 if necessary (info here).
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.
sudo nodectl upgrade_nodectl -v <next_version_in_path>Example: sudo nodectl upgrade_nodectl -v v2.13.0
Node internal upgrade
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.
Press Y then [ENTER] to upgrade or N then [ENTER] to cancel: YWhen you reach a version that can be directly upgraded to the latest v2.17.3 you may exclude the -v option.
sudo nodectl upgrade_nodectlUPGRADE OPTIONS
Auto Upgrade (Recommended)
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:
⚠️ 1. Be Patient – Do Not Interrupt the Process
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.
⚠️ 2. Pay close attention - Monitor the upgrade
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.
sudo nodectl statusIf 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
sudo nodectl quick_status -p intnet-l0 -w 120Alternatively, monitor the node closely during the process.
sudo nodectl logs -l app -p dag-l0Perform nodectl upgrade
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.
sudo nodectl upgradeor
🏭Upgrade Tessellation GuideOptional
use the
--nioption ( non-interactive )This option will choose all the default options for any questions normally asked by nodectl during the installation process.
sudo nodectl upgrade --niManual ( not using nodectl )
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.
The Constellation Network team has provided a data migration script to assist with this process, located here.
⚠️ 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.
Last updated
Was this helpful?