Suggested Migration Path for V2 Private Networks

The article documents the suggested migration path for V2 Private Networks.

Suggested migration path:

Step 1: Major changes in The Things Stack: Go through the major changes in The Things Stack from the guide here:

Step 2: Update your custom Applications/Integrations: Update your integrations to support the The Things Stack Data Format. If you are using Payload Formatters, make sure to set them correctly from the Application settings page.

Step 3: Test Migration: Follow migration guide in order to migrate a single device (and gateway, if needed) to The Things Stack. For migrating a gateway, please refer to Migrating Gateways guide. Upon successful test, continue to migrate a small batch of devices.
Note: Avoid migrating production workloads before you are certain that they will work as expected.

Step 4: Migrate Site by Site: The best approach is to migrate devices and gateways site by site. Once you are confident that your devices are working properly, migrate the rest of your devices and gateways to The Things Stack site by site.

Important Notes:

  1. Major version update: Please note that this is a major version update where downtime is expected. Zero downtime is difficult to achieve and it depends on how often the devices transmit/rejoin and the level of access to the gateways.

  2. Migrate devices with new session on V3: In order to guarantee proper functioning of migrated devices, they will need to rejoin after migrating to V3. It is not advised to migrate the device session data, because when the session is retained, we can't guarantee the maintainability of the active session and if downlinks will reach the devices. Devices imported from V2 are configured with an Rx1Delay of 1 second, by default. In The Things Stack we recommend using an Rx1Delay of 5 seconds to accommodate for high latency backhauls and/or peering with Packet Broker.

  3. Multi-cluster deployment: In V2, deployment is in the closest geographical region. The Things Stack Cloud is a multi-cluster deployment. This means that while your account information is stored in a central location, you can connect your gateways to a closer cluster, and route all your IoT traffic in that cluster. This can significantly reduce latency. Hence, we recommend you to consider migrating your devices and gateways to appropriate clusters. The Things Stack Cloud currently has clusters in Ireland, Sydney and North California. Ref:

  4. Peering between V2 and V3:
    Eventually, all the gateways are to be migrated to V3. But, if you need more time to migrate your gateways due to lack of remote access or manual access, we can enable peering between your V2 instance and your The Things Stack Cloud V3 tenant, so that the traffic from your devices reach V3 while the gateways are still pointing to V2. It gives you more time to migrate your gateways gradually. Please note that V2 deployment is based on geographical region and so the frequency plan is tied to that region. If your installed base use gateways operating in multiple frequency plans, then peering can be enabled for only one frequency plan. The gateways on other frequencies should be migrated to route traffic to V3.

    For support in the process, please file a ticket in our Support Portal or mail us at