How to Use Nacos Custom Tag Gray Release for Precise Configuration Deployment

Introduction

The article introduces Nacos configuration center's custom tag gray release, which addresses the limitations of traditional IP‑based gray releases in medium‑to‑large applications by allowing developers to assign tags to nodes for more flexible and precise rollout.

Nacos Overview

Nacos is a microservice middleware platform designed for cloud‑native applications. Its core functions include dynamic service discovery, dynamic configuration management, and dynamic DNS services. It integrates Alibaba's internal Diamond, ConfigServer, and VipServer middleware, supporting Java, Go, Python, C++, C# SDKs and holding a dominant market share in China.

Configuration Center Usage

The configuration center enables runtime configuration changes without restarting services, reducing build and deployment costs and improving efficiency. It is widely used across microservice, high‑availability, front‑end, and database scenarios for traffic scheduling, routing rules, emergency plans, feature switches, and data source configurations.

Risks of Configuration Changes

Dynamic configuration changes improve iteration speed but introduce stability risks. Mis‑operations can cause runtime errors, so changes must be gray, monitorable, and rollbackable.

Gray: Control the rollout scope gradually.

Monitor: Visualize business metrics to reflect runtime status.

Rollback: Quickly revert to the previous state if anomalies appear.

Gray Release Process

A typical gray release selects a low‑risk subset of servers, deploys new configuration, monitors metrics, expands the scope if stable, or aborts and rolls back if issues arise.

Limitations of IP‑Based Gray Release

IP‑based gray release becomes cumbersome for large applications because IPs are not business‑aware, selection is manual, and containerized environments may change IPs after restarts.

Custom Tag Gray Release

To overcome IP limitations, MSE Nacos adds custom tag gray release, allowing tags such as application, data center, environment, or project branch to be assigned to nodes for more granular control.

Version Requirements

Nacos‑Client 2.3.2+ (Go SDK 2.2.6+).

MSE Nacos 2.2.3.3+.

Setting Application Tags

Tags are key‑value pairs set via properties, JVM arguments, or environment variables. The built‑in tag key is nacos.config.gray.label. Example settings:

// properties
Properties properties = new Properties();
properties.put(PropertyKeyConst.SERVER_ADDR, "{server addr}");
properties.put("nacos.config.gray.label", "yourgrayname");
ConfigFactory.createConfigService(properties);

// JVM argument
-Dnacos.config.gray.label={value}

// Environment variable
nacos_config_gray_label={value}

Priority of tag sources: properties > JVM argument > environment variable.

Publishing Tag Gray Release

After setting tags and restarting the application, the MSE console shows the tags. In the configuration edit page, select "Tag‑based gray release", specify the tag key and value, preview matched nodes, edit configuration content, and publish the gray version.

Published gray versions appear as "Beta" alongside the "Formal" version in the configuration detail page.

Multi‑Tag Gray Release

For complex scenarios, multiple tags can be set using nacos.app.conn.labels (e.g., k1=v1,k2=v2,k3=v3) via properties, JVM arguments, or environment variables. Tags support letters, digits, underscores, hyphens, and dots, with a maximum of 10 tags per node.

Parallel Gray Versions

MSE Nacos allows up to five simultaneous tag‑based gray versions for a single configuration. Each version can target different tag values, and priority is determined by a numeric priority field (higher value = higher priority). If multiple gray versions match a node, the server selects the version with the highest priority, falling back to IP‑based gray, then the formal version.

Conclusion

The article completes the introduction to MSE Nacos custom tag gray release, encouraging users to upgrade and try the feature, and provides links to Nacos documentation and repositories.