Migrate self-managed Nacos to MSE Nacos - Microservices Engine

Compared to a self-managed Nacos configuration center, Microservices Engine (MSE) Nacos offers advanced features like configuration encryption, decryption, and push tracking. It delivers high performance, availability, and ease of use, significantly reducing your O&M costs. This topic describes how to migrate from a self-managed, open-source Nacos configuration center to MSE Nacos.

Prerequisites

You have created a Nacos engine.
You have created the required namespaces. For more information, see Create a namespace.

Note
If your self-managed Nacos instance has multiple namespaces, create corresponding namespaces in MSE Nacos with identical names and IDs to ensure a smooth migration.

Step 1: Migrate configurations to MSE Nacos

Method 1: Use import and export

Note

Export and import configurations for each namespace separately.

Export the configurations from your self-managed Nacos console.
1. Log on to your self-managed Nacos console.
2. On the Configurations page, select the configurations that you want to migrate, and click Export at the bottom of the list. In the Export Configuration dialog box, click Export.
3. Save the exported configuration file.
Import the configurations into the MSE console.
1. Log on to the MSE console.
2. In the left-side navigation pane, choose Microservices Registry > Instances. Click the name of the instance.
3. In the left-side navigation pane, choose Configuration Management > Configurations.
4. On the Configurations page, select the destination namespace, and click Import Configuration.
5. In the Import Configuration dialog box, configure the import policy. For existing configurations with the same name, you can select Stop Import, Skip, or Overwrite. Upload the configuration file that you exported from your self-managed Nacos instance, and then click OK.
Perform bilateral updates.

Note
To ensure a smooth migration, keep configurations synchronized between your self-managed Nacos instance and MSE Nacos until you switch over your applications. If you update configurations by using an SDK, implement a double-write mechanism. If you update configurations in the console, apply the changes manually in both consoles.

Method 2: Use MSE Sync for hot migration

Note

To learn how to deploy MSE Sync, see Migration with MSE Sync.

After MSE Sync is deployed, log on to the MSE console. In the navigation pane on the left, choose Microservices Registry > Migration to Cloud. On the Migration to Cloud page, click Migration configuration.
On the Migration configuration page, click Next. In the Create Configuration step, set Source Instance Type to Nacos and Synchronization Type to Configuration Synchronization. Enter the IP address and port of the source instance in the Source Instance Node Address field, and select your Destination Instance. Click Next. On the Implement migration page, click Download and save the configuration that you want to migrate., then import the file into MSE Sync to enable hot synchronization from the source cluster.

Enter a Source Name (3 to 15 characters). In the Namespace List, enter the namespaces from the source Nacos instance that you want to migrate. You can also add a Description (up to 64 characters). We recommend that the destination instance's specifications meet or exceed the recommendation from the evaluation. For advanced settings, such as JVM parameters or Nacos authentication, see the related documentation.

Important

Configuration synchronization does not support canary configurations. If MSE Sync is within the canary scope of either cluster, canary configurations are synchronized to the other cluster as regular configurations.
Do not concurrently modify configurations in the source and destination clusters.

Step 2: Update application parameters

Update the parameters for your application based on its type:

Migrate a Spring Cloud Alibaba application

Check whether your application is a Spring Cloud Alibaba application.
Your application is a Spring Cloud Alibaba application if its pom.xml file contains the following dependency:
```
<dependency>
    <groupId>com.alibaba.cloud</groupId>
    <artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId>
</dependency>
```
If your application is a Spring Cloud Alibaba application, modify its bootstrap.properties file.
Replace ${MSE_ENDPOINT} with the public or internal endpoint of your destination MSE Nacos instance. You can find the endpoint on the Basic Information page of the instance.
```
spring.cloud.nacos.config.server-addr=${MSE_ENDPOINT}
```
In the following configuration, replace the namespace with your MSE namespace ID. You can find the ID on the Namespaces page of the Nacos instance. If the ID is unchanged from your previous setup, no modification is needed. If you are using the default namespace, leave this parameter empty.

Note

If you deploy your application using a public endpoint, add the client IP addresses to the whitelist to ensure connectivity. For more information, see Configure a whitelist.
If the whitelist is empty, all IP addresses are allowed to access the application.

Migrate a Java application

Check whether your application uses the Nacos Java SDK.
If the following dependency exists in the pom.xml file, your application uses the Nacos Java SDK.
```
<dependency>
  <groupId>com.alibaba.nacos</groupId>
  <artifactId>nacos-client</artifactId>
</dependency>
```
If your application uses the Nacos Java SDK, replace ${MSE_ENDPOINT} in the following code with the endpoint of the MSE instance. Replace ${NAMESPACE_ID} with the namespace ID of the MSE instance. If you use the default namespace, you can leave this parameter empty. If the namespace ID is unchanged, no modification is needed. Then, redeploy the application.
```
properties.put("serverAddr", "${MSE_ENDPOINT}");
properties.put("namespace", "${NAMESPACE_ID}");
```

Migrate a Nacos Spring Boot application

If your application is a Nacos Spring Boot application, modify its application.properties file.

Replace ${MSE_ENDPOINT} with the endpoint of the MSE instance.

nacos.config.server-addr=${MSE_ENDPOINT}

In the following configuration, replace the namespace with your MSE namespace ID:

nacos.config.namespace=${NAMESPACE_ID}

Migrate a Go application

Note

Before calling any API operations, set your access credentials using environment variables. The environment variable names for the AccessKey ID and AccessKey secret of Microservices Engine are MSE_AK and MSE_SK, respectively.

If you use the Nacos Go SDK, you need to replace ${SERVER_IP} with the IP address of the MSE instance.

sc := []constant.ServerConfig{
    {
    IpAddr: "${SERVER_IP}",
    Port:   8848,
    },
}

Note

For an official Go application demo, see nacos-sdk-go.

Migrate a Python application

If you use the Nacos Python SDK, you need to replace ${SERVER_ADDRESSES} and ${NAMESPACE_ID} with the endpoint and namespace ID of the MSE instance.

SERVER_ADDRESSES = "${SERVER_ADDRESSES}"
NAMESPACE = "${NAMESPACE_ID}"
client = nacos.NacosClient(SERVER_ADDRESSES, namespace=NAMESPACE)

Migrate a Node.js application

If you use the Nacos Node.js SDK, you need to replace ${SERVER_ADDRESS} and ${NAMESPACE_ID} with the endpoint and namespace ID of the MSE instance.

const configClient = new NacosConfigClient({
  serverAddr: '${SERVER_ADDRESS}',
  namespace: '${NAMESPACE_ID}',
  accessKey: 'MSE_AK',
  secretKey: 'MSE_SK',
  requestTimeout: 6000,
});

Migrate a C# application

Replace ${SERVER_ADDRESS} and ${NAMESPACE_ID} with the endpoint and namespace ID of the MSE instance.

{
  "NacosConfig": {
    "Listeners": [
      {
        "Optional": false,
        "DataId": "common",
        "Group": "DEFAULT_GROUP"
      },
      {
        "Optional": false,
        "DataId": "demo",
        "Group": "DEFAULT_GROUP"
      }
    ],
    "Namespace": "${NAMESPACE_ID}", 
    "ServerAddresses": [ "http://${SERVER_ADDRESS}:8848/" ],
    "UserName": "test2",
    "Password": "123456",
    "AccessKey": "MSE_AK",
    "SecretKey": "MSE_SK",
    "EndPoint": "acm.aliyun.com",
    "ConfigFilterAssemblies": ["YouPrefix.AssemblyName"],
    "ConfigFilterExtInfo": "some ext information"
  }
}

Migrate a C++ application

If you use the Nacos C++ SDK, you need to replace ${SERVER_ADDRESS} and ${NAMESPACE_ID} with the endpoint and namespace ID of the MSE instance.

Properties props;
props[PropertyKeyConst::SERVER_ADDR] = "${SERVER_ADDRESS}:8848";
props[PropertyKeyConst::NAMESPACE] = "${NAMESPACE_ID}";

Step 3: Verify and decommission the self-managed instance

When all applications are running stably on MSE Nacos, you can stop synchronizing configurations between the two instances. Monitor the self-managed instance to ensure no traffic or client connections remain. After confirming the self-managed instance has no remaining traffic, client connections, or configuration push queries, you can decommission it.