Microservices Engine:Configure a phased release

Create an IP-based canary configuration

1. Log on to the MSE console and select a region in the top navigation bar.

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

3. On the Instances page, click the name of the target instance.

4. In the left-side navigation pane, choose Configuration Management > Configurations.

5. Find the target configuration and click Edit in the Actions column.

6. In the Edit Configuration panel, set Release Type to IP-based Canary Release.

   

7. Click the Application Node IP input box and select the IP addresses for the canary release. You can also type IP addresses manually. The input supports autocomplete.

   Note

   IP addresses listed here are the IPs of nodes that subscribe to this configuration. Separate multiple IP addresses with commas (,).

8. Edit the configuration content, then click Canary Release.

9. In the Comparison of Configuration Content dialog box, verify the Current Official Version and Content To Be Released, then click Release.

View the canary configuration

1. Navigate to the Configurations page of the target instance (steps 1-4 above).

2. Find the configuration with an active canary release and click Edit in the Actions column.

3. In the Edit Configuration panel, click the Beta(IP) tab to view the canary release details.

   

Stop or promote the canary release

On the Beta(IP) tab of the Edit Configuration panel:

• Stop the canary release: Click Stop Canary Release. The canary configuration is discarded and all nodes continue using the official version.

• Promote to full release: Click Full Release. In the Comparison of Configuration Content dialog box, confirm the configuration and click Full Release. The canary configuration becomes the new official version and the canary release ends.

Step 1: Set application tags on the client

Assign tags to application nodes in key-value format. You can set tags through properties, JVM parameters, or environment variables. If the same key is defined in multiple places, the priority order is: properties > JVM parameters > environment variables.

nacos.config.gray.label is the built-in default tag key for canary releases.

// Option 1: Set through properties
Properties properties = new Properties();
properties.put(PropertyKeyConst.SERVER_ADDR, "<your-nacos-endpoint>");
properties.put("project.name", "<your-app-name>");
properties.put("nacos.config.gray.label", "<your-canary-tag>");

// Option 2: Set as a JVM parameter
// -Dnacos.config.gray.label=<your-canary-tag>

// Option 3: Set as an environment variable
// nacos_config_gray_label=<your-canary-tag>

// Create the config service and subscribe to a configuration
NacosConfigService configService = new NacosConfigService(properties);

String dataId = "<your-data-id>";
String group = "<your-group>";

configService.addListener(dataId, group, new Listener() {
    @Override
    public Executor getExecutor() {
        return null;
    }

    @Override
    public void receiveConfigInfo(String configInfo) {
        System.out.println("Received config: " + configInfo);
    }
});

Replace the following placeholders with actual values:

Step 2: Verify listener tags on the server

After the client connects with tags, verify that the server recognizes them. Open the listener list for the target configuration. Each listener displays its associated tags.

Step 3: Release a tag-based canary configuration

1. Click Edit Configuration and set Release Type to Tag-based Canary Release.

2. Select an existing key-value tag pair. The console displays the number of nodes that match the selected tag.

   

3. Edit the configuration content and click Canary Release.

Step 4: Verify and expand the release

After releasing the canary version:

1. Verify the canary group: On the Listener Query tab, check which configuration version each node received.

2. View canary details: On the Configuration Details tab, review the current canary version content.

3. Expand the release scope: After confirming the canary group is healthy, expand the tag value to include more nodes. Repeat until all target nodes are covered.

4. Promote to full release: Click Full Release to make the canary configuration the new official version. The canary version is stopped automatically.

5. Roll back if needed: If a problem occurs, click Stop Canary Release to discard the canary configuration. All nodes revert to the official version.

Version matching priority

When a node requests a configuration, MSE Nacos evaluates versions in this order:

1. IP-based canary version -- If the node IP matches the canary IP list, this version is returned.

2. Tag-based canary version -- If no IP match exists, the system checks tag-based canary versions sorted by the priority field (higher value = higher priority). If priority values are equal, versions are sorted by name.

3. Official version -- If no canary version matches, the official version is returned.

Check the matched configuration version for each node on the Listener Query page in the MSE console.

Set multiple tags

Nacos supports injecting multiple key-value tag pairs into an application through the nacos.app.conn.labels parameter. Use the format "k1=v1,k2=v2,k3=v3".

// Option 1: Set through properties
Properties properties = new Properties();
properties.put(PropertyKeyConst.SERVER_ADDR, "<your-nacos-endpoint>");
properties.put("project.name", "<your-app-name>");
properties.put("nacos.app.conn.labels", "app=order-service,site=hangzhou-c,env=staging");

// Option 2: Set as a JVM parameter
// -Dnacos.app.conn.labels="app=order-service,site=hangzhou-c,env=staging"

// Option 3: Set as an environment variable
// nacos_app_conn_labels="app=order-service,site=hangzhou-c,env=staging"

NacosConfigService configService = new NacosConfigService(properties);

String dataId = "<your-data-id>";
String group = "<your-group>";

configService.addListener(dataId, group, new Listener() {
    @Override
    public Executor getExecutor() {
        return null;
    }

    @Override
    public void receiveConfigInfo(String configInfo) {
        System.out.println("Received config: " + configInfo);
    }
});

Implement a custom tag collector (SPI)

For dynamic or complex tag logic, implement the com.alibaba.nacos.common.labels.LabelsCollector SPI interface and register it as a service.

package com.example.labels;

import com.alibaba.nacos.common.labels.LabelsCollector;

import java.util.HashMap;
import java.util.Map;
import java.util.Properties;

public class CustomLabelsCollector implements LabelsCollector {

    @Override
    public String getName() {
        return "custom-labels";
    }

    @Override
    public Map<String, String> collectLabels(Properties properties) {
        Map<String, String> labels = new HashMap<>();
        // Add custom logic to determine labels
        labels.put("env", System.getenv("DEPLOY_ENV"));
        labels.put("region", System.getenv("DEPLOY_REGION"));
        return labels;
    }

    @Override
    public int getOrder() {
        return 1;
    }
}

To use the implementation, publish it as a service.

Tag format requirements

Tag keys and values support: uppercase and lowercase letters, digits, underscores (_), hyphens (-), and periods (.). Tags in other formats are ignored.

When specifying multiple key-value pairs with nacos.app.conn.labels, use the format "k1=v1,k2=v2,k3=v3". Entries without a value are ignored. For example, "k1=v1,k2" results in only k1=v1 being parsed.