Microservices Engine:Configure canary release

Create a beta 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 instance.

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

5. Find the target configuration and click Edit in the Actions column. In the Edit Configuration panel, set Release Type to IP-based Canary Release.

   

6. Click the Application Node IP input box and select the IP addresses for the canary release from the list.

   You can also manually enter IP addresses. The autocomplete feature is supported.

   Note

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

7. After you modify the configuration, click Canary Release. In the Comparison of Configuration Content dialog box, confirm the Current Official Version and Content To Be Released, and then click Release.

View a beta 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 instance.

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

5. Find the configuration that is in a beta release and click Edit in the Actions column.

6. In the Edit Configuration panel, click the Beta(IP) tab to view the beta release information.

   

Other operations

• Stop canary release: On the Beta(IP) tab of the Edit Configuration panel, click Stop Canary Release to cancel the canary release.

• Full release: On the Beta(IP) tab of the Edit Configuration panel, click Full Release. In the Comparison of Configuration Content dialog box, confirm the configuration information and click Full Release. The content of the canary release is published as the official version, and the current canary release is stopped.

Set application tags on the client

You can set tags for applications in a key-value format. You can specify tags in one of three ways: properties, JVM parameters, or environment variables. If tags have the same key, the order of priority is properties > JVM parameters > environment variables. nacos.config.gray.label is the built-in default tag for canary releases in Nacos.

// 1. Pass as properties
Properties properties = new Properties();
properties.put(PropertyKeyConst.SERVER_ADDR, "your endpoint");
properties.put("project.name", "your app name");
properties.put("nacos.config.gray.label","yourgrayname");


// 2. Set as JVM parameters
Set the startup parameter -Dnacos.config.gray.label=yourgrayname

// 3. Specify as environment variables
Set the environment variable nacos_config_gray_label=yourgrayname

 String dataId = "gray_test_dataid";
 String group = "test-group";
        
 configService.addListener(dataId, group, new Listener() {
        @Override
        public Executor getExecutor() {
            return null;
        }
            
        @Override
        public void receiveConfigInfo(String configInfo) {
            System.out.println("receiveConfig:" + configInfo);
        }
 });

Release a tagged canary configuration on the server

• View listener tags

  After you inject application tags on the client, you can view the list of listeners for the configuration on the server. You can also see the tags that each listener has.

  

• Release a tagged canary configuration

  Click Edit Configuration, select Tag-based Canary Release, and then select an existing key-value tag pair for the application nodes. You can see the number of nodes that match the selected tag pair.

After you release the tagged canary version, you can view the configuration version that matches the current client on the Listener Query tab. You can view the details of the current canary version on the Configuration Details tab.

After you observe the results from the first canary release group, you can expand the value of the tag to gradually expand the release scope until all nodes are included. When you perform a full release, the corresponding canary version is stopped. If a business exception occurs during the canary release, you can click Stop Canary Release to automatically roll back the changes.

Advanced usage of application tags

In addition to setting a single tag such as nacos.config.gray.label, Nacos also supports setting multiple tags and using a custom tag Collector SPI. This allows for more flexible custom logic to obtain tags.

• Set a multi-value tag.

  Nacos supports injecting multiple key-value tag pairs into an application. You can specify the nacos.app.conn.labels parameter in properties and JVM parameters. The format is nacos.app.conn.labels="k1=v1,k2=v2,k3=v3". You can also specify the nacos_app_conn_labels parameter in environment variables.

  // 1. Pass as properties
  Properties properties = new Properties();
  properties.put(PropertyKeyConst.SERVER_ADDR, "your endpoint");
  properties.put("project.name", "your app name");
  properties.put("nacos.app.conn.labels","app=demo,site=hangzhou-c,otherkey=othervaue");
  
  // 2. Set as JVM parameters
  Set the startup parameter -Dnacos.app.conn.labels="app=demo,site=hangzhou-c,otherkey=othervaue"
  
  // 3. Specify as environment variables
  Set the environment variable nacos_app_conn_labels="app=demo,site=hangzhou-c,otherkey=othervaue"
  
  NacosConfigService configService = new NacosConfigService(properties);
  
  String dataId = "gray_test_dataid";
  String group = "test-group";
          
  configService.addListener(dataId, group, new Listener() {
          @Override
          public Executor getExecutor() {
              return null;
          }
              
          @Override
          public void receiveConfigInfo(String configInfo) {
              System.out.println("receiveConfig:" + configInfo);
          }
  });
  

• Custom application tag SPI

  Nacos Client defines an SPI for custom application tags. You can implement the com.alibaba.nacos.common.labels.LabelsCollector interface and publish the implementation class as a service to create a custom application tag SPI.

  package your.demo.test;
  
  import com.alibaba.nacos.common.labels.LabelsCollector;
  
  import java.util.HashMap;
  import java.util.Map;
  import java.util.Properties;
  
  /**
   * TestLabelsCollector.
   *
   * @author yourname
   */
  public class TestLabelsCollector implements LabelsCollector {
      
      @Override
      public String getName() {
          return "testlables";
      }
      
      @Override
      public Map<String, String> collectLabels(Properties properties) {
          Map<String, String> labels = new HashMap<>();
          labels.put("test", "implements your labels logic");
          return labels;
      }
  
    
      @Override
      public int getOrder() {
          return 1;
      }
  }

Parallel canary versions

A configuration can have multiple versions. These include an official version, an IP-based canary version, and multiple tag-based canary versions. When a configuration has multiple versions, the Nacos server matches configuration queries and pushes according to the following order of priority: IP-based canary version > Tag-based canary version > Official version.

When processing multiple tag-based canary versions, the versions are sorted by the value of the priority field. A larger priority value means a higher priority. If priority values are equal, the versions are sorted by name. We recommend that you set clear priorities for different canary versions.

When an application node has a tag, the system first checks for an IP-based canary version that corresponds to the node's IP address. If one exists, the IP-based canary configuration is returned. If an IP-based canary version does not exist, the system tries to match a tag-based canary version according to priority. If a match is found, the corresponding canary configuration is returned. If no tag-based canary version is matched, the official version of the configuration is returned. You can view the configuration version that matches each application node on the Listener Query page in the MSE console.

Application tag planning

When you plan tags for application nodes, we recommend that you plan them based on the scope of business impact. This lets you perform a gradual canary release and reduce change-related risks. The following are common best practices:

• Use application names as tags. First, perform a canary release on non-critical applications. After you observe and confirm that there are no exceptions, expand the release to core applications.

• On the business side, you can isolate traffic between upstream and downstream machines at the traffic ingress. For example, you can identify a group of canary machines for internal users. You can then set a separate canary tag for these machines to implement a canary release for internal users.

Format of application tags

The key and value of a tag can contain uppercase and lowercase letters, digits, underscores (_), hyphens (-), and periods (.). Tags in other formats are ignored. If you specify multiple key-value pairs with the nacos.app.conn.labels parameter, use the format "k1=v1,k2=v2,k3=v3" . For example, if you pass "k1=v1,k2", the k2 parameter is ignored and the final parsed value is k1=v1.