All Products
Search

This Product

    Microservices Engine:Migrate persistent data to an MSE ZooKeeper instance

    Document Center

    Microservices Engine:Migrate persistent data to an MSE ZooKeeper instance

    Last Updated:Mar 11, 2026

    When you move from a self-managed ZooKeeper cluster to Alibaba Cloud Microservices Engine (MSE), you need to migrate persistent znode data without data loss. MSE Sync handles this by creating a bidirectional sync task between your source cluster and the MSE ZooKeeper instance, so both sides stay in sync until you complete the cutover.

    This guide covers cluster registration, sync task creation, data verification, and cutover.

    Limitations

    Review these constraints before you start. This migration method has strict boundaries on what data it can handle and how MSE Sync operates.

    • Persistent znodes only. Do not use this method to migrate service data, distributed locks, or ephemeral node data.

    • Network connectivity required. The self-managed ZooKeeper cluster, MSE Sync, and the MSE ZooKeeper instance must communicate over the network.

    • MSE Sync availability. If MSE Sync goes down, synchronization stops. Deploy MSE Sync on at least two nodes to prevent a single point of failure, and complete the migration promptly after it starts.

    Prerequisites

    Before you begin, make sure that you have:

    Step 1: Register the source and destination clusters

    Register both your self-managed ZooKeeper cluster and the MSE ZooKeeper instance in MSE Sync before you create a sync task.

    Add the source cluster

    1. In the left-side navigation pane of MSE Sync, click Cluster Configuration.

    2. Click Add Cluster.

    3. In the Add Cluster dialog box, configure the following parameters:

      Note

      If your source cluster uses a Server Load Balancer (SLB) instance, enter the SLB IP address and port instead.

      ParameterDescription
      Cluster NameA custom name for your self-managed ZooKeeper cluster
      Cluster TypeSelect ZK
      Cluster IP Address ListEnter IP address and port combinations for your ZooKeeper nodes, one per line. The default port is 2181. Example:
      127.0.0.1:2181
      127.0.0.2:2181
      127.0.0.3:2181


    4. Click OK.

    Add the destination cluster

    1. Click Add Cluster again.

    2. Configure the following parameters:

      ParameterDescription
      Cluster NameA custom name for the MSE ZooKeeper instance
      Cluster TypeSelect ZK
      Cluster IP Address ListEnter the endpoint and service port of your MSE ZooKeeper instance. Example: mse-8b7de****-p.zk.mse.aliyuncs.com:2181

    3. Click OK.

    Step 2: Create a sync task

    1. In the left-side navigation pane of MSE Sync, click Service Synchronization.

    2. Click New Sync.

    3. In the New Sync dialog box, configure the following parameters:

      Important

      Bidirectional sync writes destination changes back to the source cluster. This may overwrite data or delete ephemeral nodes on the source. Evaluate the risk before you select this mode.

      ParameterDescription
      Sync ModeSelect Bidirection. Changes on either the source or destination trigger synchronization in both directions.
      Sync TypeSelect Config. MSE Sync displays the configurations of all services registered with the self-managed ZooKeeper cluster. Select the configurations to migrate based on your requirements.
      PathThe znode path on the self-managed ZooKeeper cluster where the persistent data to migrate is stored.

    4. Click OK.

    The sync task appears on the Service Synchronization page.

    Step 3: Verify the migration

    After the sync task starts, confirm that the persistent data has been replicated to the MSE ZooKeeper instance.

    1. Log on to the MSE console.

    2. In the top navigation bar, select the region of your MSE ZooKeeper instance.

    3. In the left-side navigation pane, choose Microservices Registry > Instances.

    4. Click the name of your MSE ZooKeeper instance.

    5. In the left-side navigation pane, choose Data Management > Znodes.

    6. Compare the znode tree with your source cluster to confirm that all expected persistent znodes and their data have been synchronized.

    Note

    Spot-check a few znodes with known values to validate data integrity beyond a structural comparison.

    Step 4: Complete the cutover

    After you verify that all persistent data has been synchronized:

    1. Shut down the self-managed ZooKeeper cluster.

    2. Disable MSE Sync.

    What's next

    • Monitor the MSE ZooKeeper instance for application connectivity and data integrity after the cutover.

    • For ongoing ZooKeeper management, see the MSE ZooKeeper documentation.