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 IntegrationNet TestNet 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.

Table of Contents

Upgrade Using nodectl

Process needed to upgrade using the Constellation Network nodectl utility.

Manual Upgrade

Information for advanced engineers who cannot use nodectl for various reasons.

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.2or newer of nodectl. Version v2.16.0 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.

Note: No new features will be added to the v2.15.x line.

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.

It is recommended to build a new node using Ubuntu 24.04 or Ubuntu 22.04 rather than attempting an inline upgrade from an older version.

This approach is advised because nodes are considered ephemeral, meaning they can be recreated or replaced without impacting long-term operations. Migrating to a fresh installation ensures a clean, stable environment and reduces the risk of issues during the upgrade process.

Upgrade using nodectl

1

Verify your version

Issue the version command to output the current version of nodectl.

sudo nodectl version

2

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_path

You may replace v2.16.0 with v2.15.2 if necessary (info here).

If there are multiple versions between your current version and v2.16.0, 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: Y

When you reach a version that can be directly upgraded to the latest v2.16.0 you may exclude the -v option.

sudo nodectl upgrade_nodectl

Auto Upgrade

If you plan to perform a manual upgrade using nodectl, you may skip this section and proceed directly to the appropriate instructions here.

---

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 status

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

sudo nodectl quick_status -p intnet-l0 -w 20

Alternatively, monitor the node closely during the process.

sudo nodectl logs -l app -p dag-l0

Perform a nodectl upgrade (semi-manual)

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 upgrade

Optional

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

sudo nodectl upgrade --ni

Manual ( 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.