Spring Cloud Gateway 流量染色

插件简介

网关常用于南北、东西向流量的边界。在某些场景下，期望流量经过网关之后，加入某些全链路透传标签。例如：

1. 网关作为全链路追踪起始节点，需要生成第一跳 Tracer 上下文
2. 在测试环境路由场景下，通过网关流量染色并配合网关的路由能力，实现把流量转发到对应的测试环境，如下图所示

Spring Cloud Tencent Gateway Plugin 实现了基于规则非常灵活的流量染色能力。

规则流量染色

规则流量染色核心是基于染色规则实现动态流量染色。如下所示的规则实现：

1. 请求查询参数 uid=1000 时，增加 env=blue 标签
2. uid=1001 是，增加 env=green 标签

{
    "rules":[
        {
            "conditions":[ # 一条规则中的多个 conditions 为与的关系
                {
                    "key":"${http.query.uid}",
                    "values":["1000"], # 如果是 EQUALS 操作符只需要填第一个，IN，NOT_IN 操作符可以填多个
                    "operation":"EQUALS" # 支持 EQUALS、NOT_EQUALS、IN、NOT_IN、REGEX、BLANK、NOT_BLANK 操作符
                }
            ],
            "labels":[ # 当满足满足所有 conditions 之后，增加的标签信息
                {
                    "key":"env",
                    "value":"blue"
                }
            ]
        },
        {
            "conditions":[
                {
                    "key":"${http.query.uid}",
                    "values":["1001"],
                    "operation":"EQUALS"
                }
            ],
            "labels":[
                {
                    "key":"env",
                    "value":"green"
                }
            ]
        }
    ]
}

快速入门

本章节将介绍普通的 Spring Cloud Gateway 如何快速集成流量染色能力。

第一步：引入 Polaris 服务端

需要通过北极星的配置中心下发流量染色规则，所以需要引入北极星。

方式一：搭建本地北极星服务

搭建北极星服务请参考 Polaris Getting Started

方式二：使用北极星开源提供的体验环境

• Console Address : http://14.116.241.63:8080/
  • Username: polaris
  • Password: polaris
• Server Address: grpc://183.47.111.80:8091

方式三：使用腾讯云北极星服务

腾讯云提供了免运维的北极星云服务，基于云服务可以快速开通生产级高可用北极星集群 了解更多

第二步：引入 SCT 网关插件依赖

1.7.0 版本之后新增了 spring-cloud-tencent-gateway-plugin 插件，用于增强 Spring Cloud Gateway 的能力。

1. 参考 Spring Cloud Tencent 版本管理 文档获取最新的版本号，引入 Spring Cloud Tencent Bom，例如：

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.tencent.cloud</groupId>
            <artifactId>spring-cloud-tencent-dependencies</artifactId>
            <version>1.7.0-Hoxton.SR9</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

2. 引入 Spring Cloud Tencent Gateway Plugin

<dependency>
    <groupId>com.tencent.cloud</groupId>
    <artifactId>spring-cloud-tencent-gateway-plugin</artifactId>
</dependency>

<!-- 如何需要全链路透传标签，需要引入 spring-cloud-starter-tencent-metadata-transfer 依赖 -->
<dependency>
    <groupId>com.tencent.cloud</groupId>
    <artifactId>spring-cloud-starter-tencent-metadata-transfer</artifactId>
</dependency>

第三步：增加北极星相关配置

在 Spring Cloud Gateway 的 bootstrap.yml 配置文件中加入以下配置内容。由于依赖 Spring Cloud Tencent Polaris Config 下发染色规则，所以需要配置再 bootstrap.yml 文件里。

spring:
  application:
    name: ${application.name}
  cloud:
    polaris:
      address: grpc://${修改为第一步部署的 Polaris 服务地址}:8091
      namespace: default
    tencent:
      plugin:
        scg: 
          staining:
            enabled: true # 打开染色插件开关，默认为 false
            rule-staining:
              enabled: true # 打开规则染色插件开关，默认为 true
              namespace: default # 染色规则配置文件所属的 Namespace，默认值为：default
              group: ${spring.application.name} # 染色规则配置文件所属的 Group，默认为：${spring.application.name} 
              fileName: rule/staining.json # 染色规则配置文件名，默认为：rule/staining.json

第四步：启动网关

应用启动成功后，即完成流量染色插件接入能力。

第五步：下发染色规则

根据第三步配置的染色规则配置文件三元组[namespace, group, fileName]信息，到北极星控制台上配置染色规则。

规则说明

conditions 一条规则中的所有 conditions 之间为与的关系。

key 支持的表达式列表

• ${http.query.xxx}
  • 匹配查询参数
• ${http.header.xxx}
  • 匹配请求头中的参数
• ${http.cookie.xxx}
  • 匹配 cookie 中的参数
• ${http.method}
  • 匹配 HTTP Method，例如 GET、POST
• ${http.uri}
  • 匹配请求 Path

operation 支持的操作符

• EQUALS (等于，区分大小写)
• NOT_EQUALS (不等于，区分大小写)
• IN (是否在集合中)
• NOT_IN (不在集合中)
• BLANK (是否为空)
• NOT_BLANK (是否不为空)
• REGEX (正则匹配)

规则样例

以下规则实现：

1. 请求查询参数 uid=1000 时，增加 env=blue 标签
2. uid=1001 是，增加 env=green 标签

{
    "rules":[ # 多条规则之间互相独立
        {
            "conditions":[ # 一条规则中的多个 conditions 为与的关系
                {
                    "key":"${http.query.uid}",
                    "values":["1000"], # 如果是 EQUALS 操作符只需要填第一个，IN，NOT_IN 操作符可以填多个
                    "operation":"EQUALS" # 支持 EQUALS、NOT_EQUALS、IN、NOT_IN、REGEX、BLANK、NOT_BLANK 操作符
                }
            ],
            "labels":[ # 当满足满足所有 conditions 之后，增加的标签信息
                {
                    "key":"env",
                    "value":"blue"
                }
            ]
        },
        {
            "conditions":[
                {
                    "key":"${http.query.uid}",
                    "values":["1001"],
                    "operation":"EQUALS"
                }
            ],
            "labels":[
                {
                    "key":"env",
                    "value":"green"
                }
            ]
        }
    ]
}

第六步：验证

当满足染色规则成功染色之后，将会打印以下 debug 日志，既说明接入成功。

[SCT] rule stained labels. {"env":"green"}

完整参数说明

配置项Key	默认值	是否必填	配置项说明
spring.cloud.tencent.plugin.scg.enabled	true	否	SCG 插件总开关
spring.cloud.tencent.plugin.scg.staining.enabled	false	否	SCG 染色插件开关，默认为 false 需要显示打开
spring.cloud.tencent.plugin.scg.staining.rule-staining.enabled	true	否	SCG 规则染色插件开关
spring.cloud.tencent.plugin.scg.staining.rule-staining.namespace	default	否	染色规则配置文件的 Namespace，默认为 default
spring.cloud.tencent.plugin.scg.staining.rule-staining.group	${spring.application.name}	否	染色规则配置文件的 Group，默认为 SCG 的应用名
spring.cloud.tencent.plugin.scg.staining.rule-staining.fileName	rule/staining.json	否	染色规则配置文件名