All Products
Search

This Product

    IoT Platform:Prerequisites

    Document Center

    IoT Platform:Prerequisites

    Last Updated:Jun 16, 2026

    Legacy public instances no longer support resource scale-out. If your resources are insufficient, IoT Platform provides an instance migration feature that lets you migrate products, devices, and message forwarding data from a legacy public instance to a Standard Enterprise instance under the same account and in the same region, reducing service impact and system refactoring costs.

    Limits

    Important

    The instance migration feature supports only data migration from a legacy public instance to a Standard Enterprise instance. For more information about instances, see Instance overview.

    Limitations

    Description

    Limit

    Migration concurrency

    The maximum number of device distribution and instance migration tasks that can run concurrently.

    Note

    IoT Platform also supports migrating devices with device distribution capabilities to an Enterprise instance. For more information, see Device distribution.

    5

    Concurrent online devices

    The minimum number of concurrent online devices that the destination Enterprise instance must support.

    Must be greater than the number of devices to be migrated.

    Destination Enterprise instance

    • A product and its devices can be migrated to only one Enterprise instance.

    • You can migrate only to an Enterprise instance in the same region.

    1

    Devices

    The maximum number of devices that can be migrated under a single product.

    Note

    If this limit does not meet your business requirements, submit a ticket to describe your needs.

    500,000

    Before you begin

    Before you migrate, review the following information to assess the business impact.

    • Data to be migrated:

      When you migrate a public instance, IoT Platform automatically synchronizes and migrates the products, devices, and message forwarding data. The following table describes the migrated data.

      Data item

      Migrated data

      Notes

      Product

      • Product information: ProductKey, name, node type, category, and more.

      • Feature definitions: Properties, services, events, and extended Thing Specification Language (TSL) models, including draft TSL model data.

      • Scripts: Data parsing scripts, including draft script data.

      • The migration supports products and devices that use per-device or per-product certificates for pre-registration authentication.

      • For gateway sub-devices, the topology relationship remains unchanged during migration. After migration, they can connect to IoT Platform as usual. Therefore, if you migrate a gateway device or its sub-devices, you must migrate them together to the same Enterprise instance.

      • Authorized products and devices cannot be migrated. The authorization feature for products and devices is not supported in Enterprise instances.

      • Products and devices that use DataService Studio cannot be migrated.

      • Products and devices with the video service enabled cannot be migrated.

      • Products and devices connected to IoT Edge or Link WAN cannot be migrated.

      • After migration, the TSL model validation type for the product remains unchanged.

      • After migration, the original data is retained in the legacy public instance. To prevent accidental operations, manually delete this data after the instance migration is complete and you confirm that your services are running normally.

      Device

      • Device information: Device certificate information. The device certificate is guaranteed to be globally unique.

      • Device data: TSL model property, event, and service data.
      Important

      Devices distributed under the instance cannot be migrated.

      • Devices to be migrated must have a reconnection feature. You must complete the device-side SDK development and connect the device to IoT Platform for normal communication.

        Note

        • If you use the Link SDK provided by IoT Platform to develop the device, the device side automatically connects to the Enterprise instance. You do not need to modify the device connection domain name. For more information about the Link SDK, see Device connection.

        • If you do not use the device-side SDK provided by IoT Platform, you must modify the device connection domain name and develop your own reconnection logic for the device.

      • During migration, if a device is online, it will be forced to go offline.

      • After migration, the migrated devices are automatically deleted from the legacy public instance. You do not need to modify the device-side SDK. The devices can successfully connect to the destination Enterprise instance and communicate normally.

      • Only users on the whitelist can migrate devices that use ID²-based authentication. You can submit a ticket to request whitelist permission. For more information about ID²-based authentication, see ID²-authenticated devices.

      • Instructions for TSL model data migration:

        • By default, data synchronization is disabled. After creating the migration task, you can manually enable data synchronization to ensure that your services are not affected during the instance migration.

        • After you enable data synchronization, the data reported by devices under the product to be migrated in the public instance is synchronized to the destination Enterprise instance. The synchronization starts with a maximum delay of 1 minute. From the day you enable data synchronization, data can be synchronized for up to 30 days.

        • You can manually disable and re-enable the device data synchronization feature. If you do not manually disable it, the system automatically disables data synchronization after 30 days. Before data synchronization is disabled, make sure to complete the instance migration to avoid affecting related services.

        • Data synchronization is one-way. It only supports synchronizing data reported by devices under the product to be migrated from the public instance to the Enterprise instance.

          When data synchronization is enabled, if a device is rolled back from the Enterprise instance to the public instance, the migrated device data is not rolled back. When the device is migrated to the Enterprise instance again, the data in the Enterprise instance is complete, but the data in the public instance will be incomplete.

      Message forwarding

      • Server-side subscription: AMQP and MNS server-side subscription configurations and subscription relationships.

      • Data forwarding: Forwarding rules, including SQL settings, data sources, data destinations such as RocketMQ, TSDB, RDS, and FC, and parsing scripts.

      • Consumer groups: Consumer group information. After migration, a new consumer group ID is created.

      • After migration, the original data is retained in the legacy public instance. To prevent accidental operations, manually delete this data after the instance migration is complete and you confirm that your services are running normally.

      • If you have configured AMQP server-side subscription or message forwarding to AMQP, you must start two AMQP clients. This ensures that both the public instance and the Enterprise instance have an AMQP client to receive data, which prevents data loss.

      • Enterprise instances do not support server-side subscription over HTTP/2. Change the server-side subscription method from HTTP/2 in the original public instance to AMQP.

    • Feature usage:

      After devices are migrated to the destination Enterprise instance, you can continue to use the migrated configurations. To use additional features, you can reconfigure them in the Enterprise instance. For more information about feature usage, see Feature usage after migration.

    • Billing:

      For devices migrated to an Enterprise instance, you are no longer billed for message communication, connection duration, or over-the-air (OTA) updates.

    Preparations before migration

    Assess the business impact and modify your business systems before you migrate the instance to ensure that devices communicate normally after the migration.

    Business item

    Assessment and action

    References

    Products and devices

    Check whether the products and devices to be migrated meet the migration requirements. For migration instructions, see Notes in Pre-migration notes.

    None

    AMQP server-side subscription

    Check whether AMQP server-side subscription or message forwarding to AMQP is configured.

    If configured, copy the new Enterprise instance ID and connection domain name to configure a new AMQP client. After the grayscale migration, copy and update the consumer group ID and start the new AMQP client.

    AMQP client connection

    Data forwarding

    In the public instance, configure data forwarding:

    • Set up a rule to forward all instance migration events to subscribe to messages about instance migration task status changes.

    • Forward device data and store it in a database. During the instance migration, data forwarding rules are migrated. After the devices are successfully migrated, update the instance information for the devices in the database to the instance ID of the destination Enterprise instance.

    Set data forwarding rules

    Device OTA update

    Check whether there are any device OTA update tasks for the product to be migrated.

    If there are, stop the OTA update tasks. Otherwise, the OTA updates may fail during the instance migration, and running OTA update tasks will continue to incur charges.

    Cancel an OTA update

    Cloud API calls

    Check whether you have developed services that call cloud APIs for the migrated devices.

    If you have such services, you must modify the request parameters when calling cloud APIs to pass the ID of the destination Enterprise instance.

    You must develop your own application or server. When calling a cloud API, first query the instance ID, which is the Enterprise instance ID, from the database table. Then, set the IotInstanceId request parameter to this Enterprise instance ID and make the API call.

    For a server-side modification example, see Server-side modification example for instance migration.

    Update the cloud SDK

    Overall migration flow

    流程图

    The instance migration flow consists of the following four parts.

    Workflow

    Description

    Business assessment

    Before the instance migration, you must assess the business impact. For more information, see Before you begin.

    System refactoring

    Based on the business assessment, refactor your business systems to ensure normal operation of device-related services in both the public and Enterprise instances:

    • Cloud APIs: When you call cloud APIs, the request parameters must include the ID of the Enterprise instance.

    • Server-side subscription and message forwarding: Configure new data forwarding rules and server-side subscriptions to receive data from migrated devices.

    Warning

    • For cloud API calls, first configure data subscription and forwarding for instance migration status. This lets you receive device migration success messages and update the instance ID information in the device data.

    • For configured AMQP subscriptions or forwarding rules, configure a new consumer group and restart the AMQP client after you verify the grayscale migration.

    For more information, see Preparations before migration.

    Instance migration

    In the IoT Platform console, create an instance migration task to migrate data related to the specified product. For more information, see Migration procedure.

    API traffic switching

    After the full migration is successful, check the service running status and results. Confirm that cloud API calls have been switched to the destination Enterprise instance.

    During system refactoring, subscribe to the forwarded data for device migration. After a device is successfully migrated, the instance information for the device in the database table is updated to the Enterprise instance ID. When you call a cloud API, the system first queries the instance ID, which is the Enterprise instance ID, from the database table, sets the IotInstanceId request parameter to this Enterprise instance ID, and then makes the API call.

    Migration procedure

    1. Step 1: Create a migration task. Add a migration task for a specified product.

      Important

      To ensure that your services are not affected during the instance migration, you can manually enable data synchronization after you create the migration task. This action migrates the data reported by devices under the product to be migrated from the public instance to the destination Enterprise instance. For more information, see Enable data synchronization.

    2. Step 2: Perform a grayscale migration. Sequentially copy product and message forwarding data, and then migrate data for the specified grayscale devices.

      Warning

      If you have configured AMQP server-side subscription or message forwarding to AMQP, you must copy and update the consumer group ID and start the new AMQP client SDK to receive data after the grayscale migration is complete.

      Observe the task and ensure that the migration does not affect your services before you perform a full migration.

    3. Step 3: Perform a full migration. Query all data under the specified product and migrate all device data.

      Warning

      Make sure that the system refactoring is complete and published. For example, cloud API calls must include the Enterprise instance ID, and the consumer group ID in the AMQP client SDK must be updated. For more information, see Preparations before migration.

      After the full migration is successful, check the service running status and results to ensure that cloud API calls have been switched to the destination Enterprise instance.

    4. Optional: Roll back the migration task. If the migration fails or an issue occurs, you can roll back all migrated device data, such as device certificate information and Thing Specification Language (TSL) model data, to the public instance to restore normal operation. This operation does not delete the migrated server-side subscription or message forwarding data from the destination Enterprise instance.

    References

    FAQ

    Before migration

    During migration

    After migration