Master Multi‑Test Environment Routing with Spring Cloud Tencent

Preface

Since its public release at the end of June, Spring Cloud Tencent has attracted strong interest, quickly surpassing 2,000 GitHub stars and gathering over 1,000 developers. The community’s main concern is the roadmap for Spring Cloud Tencent.

Initially, the project focused on basic service‑governance capabilities such as service discovery, dynamic configuration, rate limiting, and routing. However, enterprises often need custom solutions for specific business scenarios, which requires extending basic capabilities (e.g., custom Gateway filters, enhanced Feign, complex routing). Therefore, the next major plan is to provide out‑of‑the‑box business‑level solutions built on solid service‑governance primitives.

To achieve this, Spring Cloud Tencent introduced the spring-cloud-tencent-plugin-starts module, currently focusing on fine‑grained traffic‑governance scenarios, divided into three development phases:

Development‑testing stage with multiple test‑environment scenarios

Release stage with canary, blue‑green, and full‑link gray releases

Production stage with unitization and A/B testing

This article focuses on the first stage: practical implementation of multiple test‑environment scenarios.

1. Fundamentals

1.1 What Is a Test‑Environment Route?

In a microservice system, different teams develop and maintain separate services. During development, a team may need to validate the full call chain, which raises two problems:

If all teams share a single development environment, a failing test instance can block dependent services.

If each team maintains its own environment, the cost and operational overhead increase dramatically.

Test‑environment routing solves this by keeping a stable baseline environment and deploying only changed services to a feature environment. Two core concepts:

Baseline Environment: a complete, stable environment that serves as a fallback.

Feature Environment: a temporary environment that only deploys services with changes, reusing baseline services via routing.

After deploying multiple test environments, developers route requests to the appropriate environment using routing rules. If a request cannot be handled by a feature environment, it falls back to the baseline.

1.2 Service Routing

The service‑routing model determines which requests are forwarded to which instances. It involves three questions: how to identify a request, how to identify an instance, and how to forward.

Routing uses tags (metadata) on both requests and instances. Core terminology includes instance coloring, traffic coloring, and service routing.

2. Implementation Principles of Test‑Environment Routing

2.1 Overview

A typical scenario involves two feature environments and one baseline. Traffic flows through App → Gateway → User Center → Points Center → Activity Center.

To achieve test‑environment routing, three tasks are required:

Instance coloring (labeling instances with the target environment)

Traffic coloring (labeling requests with the target environment)

Service routing (gateway forwards based on request tags, and service calls prefer instances in the same environment, falling back to baseline if none exist)

2.2 Instance Coloring

Instances are labeled with <featureenv=environment_name>. Spring Cloud Tencent supports three ways:

Configuration file (application.yml)

Environment variables (prefix SCT_METADATA_CONTENT_)

Custom SPI implementation of

InstanceMetadataProvider

spring:
  cloud:
    tencent:
      metadata:
        content:
          idc: shanghai
          env: f1

Overrides can be applied via -Dspring.cloud.tencent.metadata.content.idc=guangzhou or by externalizing application.yml.

2.3 Traffic Coloring

Traffic coloring attaches the target environment tag to each request. Three approaches:

Static coloring – propagate instance tags to requests (configured via spring.cloud.tencent.metadata.content.transitive or equivalent env var or SPI).

Dynamic coloring – add HTTP headers like X-Polaris-Metadata-Transitive-featureenv=f1 at runtime.

Gateway coloring – define rules in Spring Cloud Gateway to add tags based on request parameters.

{
  "rules":[
    {
      "conditions":[{"key":"${http.query.uid}","values":["1000"],"operation":"EQUALS"}],
      "labels":[{"key":"featureenv","value":"f1"}]
    },
    {
      "conditions":[{"key":"${http.query.uid}","values":["1001"],"operation":"EQUALS"}],
      "labels":[{"key":"featureenv","value":"f2"}]
    }
  ]
}

The gateway plugin is enabled via spring.cloud.tencent.plugin.scg.staining.enabled=true.

2.4 Spring Cloud Tencent Routing Mechanics

Spring Cloud Tencent builds on Polaris. The Polaris routing chain fetches all instances from the registry and applies MetadataRouter to match request tags with instance tags, typically using the featureenv label.

Spring Cloud Tencent extends RestTemplate, Feign, and Spring Cloud LoadBalancer to inject request tags into the routing context and invoke Polaris routing APIs.

3. User Guide for Test‑Environment Routing

Add the spring-cloud-tencent-featureenv-plugin dependency.

Label service instances with the featureenv tag (via config file, env var, or SPI).

Apply traffic coloring to requests (client‑side header, gateway rule, or static gateway header).

After these steps, the test‑environment routing works automatically.

3.1 Adding the Plugin Dependency

Include spring-cloud-tencent-featureenv-plugin to enable all routing capabilities.

3.2 Labeling Service Instances

Default label key is featureenv. Example configuration in bootstrap.yml:

spring:
  cloud:
    tencent:
      metadata:
        content:
          featureenv: f1  # replace with your environment name

Alternatively, set SCT_METADATA_CONTENT_featureenv=f1 as an environment variable or implement a custom InstanceMetadataProvider.

3.3 Traffic Coloring

Recommended methods:

Client‑side coloring – add X-Polaris-Metadata-Transitive-featureenv=f1 header to HTTP requests.

Gateway dynamic coloring – configure rules so that, for example, uid=1 routes to f1 and uid=0 routes to f2.

Gateway static coloring can also be used by adding a fixed header in each environment’s gateway.

4. Summary

Test‑environment routing greatly reduces maintenance and resource costs during development while improving efficiency. Spring Cloud Tencent achieves this with simple instance labeling and request tagging, without the need for complex routing rule distribution.

When using Spring Cloud Gateway, the provided gateway staining plugin further simplifies traffic coloring, requiring only configuration changes.

GitHub: https://github.com/Tencent/spring-cloud-tencent