实现蓝绿发布

蓝绿发布是一种发布策略，它维护两个完全相同的生产环境（Blue 和 Green）。任意时刻只有一个环境承载线上流量。当新版本准备就绪时，流量会切换到另一个环境；如果出现问题，也可以立即回滚。

API7 网关通过 traffic-split 插件实现蓝绿发布，该插件可以按权重在多个上游之间分配流量。

提示

蓝绿发布会一次性切换 100% 流量。若要逐步转移流量（例如将 10% 流量转到新版本），请参阅实施灰度发布。

前置条件

• API7 企业版实例正在运行。
• 已创建网关组，并且网关实例正在运行。
• 从控制台获取 Token。

工作流概览

第 1 步：准备上游

创建一个已发布服务，其默认上游代表 Blue 环境。切换流量时，Green 环境会以内联形式定义在 traffic-split 插件中。

Admin API

创建 Blue 服务和路由：

curl -k "https://localhost:7443/apisix/admin/services/blue-green-service?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "blue-green-service",
    "upstream": {
      "type": "roundrobin",
      "scheme": "https",
      "pass_host": "node",
      "nodes": [
        {
          "host": "mock.api7.ai",
          "port": 443,
          "weight": 100
        }
      ]
    }
  }'

curl -k "https://localhost:7443/apisix/admin/routes/blue-green-route?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "blue-green-route",
    "methods": ["GET"],
    "paths": ["/headers"],
    "service_id": "blue-green-service"
  }'

现在，默认服务上游代表 Blue 环境。

ADC

在 ADC 配置中定义 Blue 服务和路由：

adc.yaml

services:
  - name: blue-green-service
    upstream:
      scheme: https
      pass_host: node
      nodes:
        - host: mock.api7.ai
          port: 443
          weight: 100
    routes:
      - name: blue-green-route
        uris:
          - /headers
        methods:
          - GET
    labels:
      docs-example: blue-green-service

预览本示例管理的资源变更，确认没有非预期的更新或删除：

adc diff -f adc.yaml \
  --include-resource-type service \
  --label-selector docs-example=blue-green-service

审查变更后同步配置：

adc sync -f adc.yaml \
  --include-resource-type service \
  --label-selector docs-example=blue-green-service

第 2 步：将流量切换到 Green

应用 traffic-split 插件，将 100% 流量路由到 Green 上游。

Admin API

curl -k "https://localhost:7443/apisix/admin/routes/blue-green-route?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "blue-green-route",
    "methods": ["GET"],
    "paths": ["/headers"],
    "service_id": "blue-green-service",
    "plugins": {
      "traffic-split": {
        "rules": [
          {
            "weighted_upstreams": [
              {
                "weight": 100,
                "upstream": {
                  "type": "roundrobin",
                  "nodes": [
                    {
                      "host": "httpbin.org",
                      "port": 443,
                      "weight": 1
                    }
                  ]
                }
              },
              {
                "weight": 0
              }
            ]
          }
        ]
      }
    }
  }'

字段	描述
内联 upstream	接收流量的 Green 上游
weight: 100（Green）	所有流量都进入 Green
weight: 0（无 upstream_id）	不向默认（Blue）上游发送流量

ADC

adc.yaml

services:
  - name: blue-green-service
    upstream:
      scheme: https
      pass_host: node
      nodes:
        - host: mock.api7.ai
          port: 443
          weight: 100
    routes:
      - name: blue-green-route
        uris:
          - /headers
        methods:
          - GET
        plugins:
          traffic-split:
            rules:
              - weighted_upstreams:
                  - upstream:
                      type: roundrobin
                      scheme: https
                      pass_host: node
                      nodes:
                        - host: httpbin.org
                          port: 443
                          weight: 1
                    weight: 100
                  - weight: 0
    labels:
      docs-example: blue-green-service

预览本示例管理的资源变更，确认没有非预期的更新或删除：

adc diff -f adc.yaml \
  --include-resource-type service \
  --label-selector docs-example=blue-green-service

审查变更后同步配置：

adc sync -f adc.yaml \
  --include-resource-type service \
  --label-selector docs-example=blue-green-service

第 3 步：验证

发送测试请求，确认所有流量都到达 Green 环境：

# 验证响应来自 Green（v2）后端
for i in $(seq 1 10); do
  curl -s "http://127.0.0.1:9080/headers" | grep 'X-Amzn-Trace-Id'
done

所有响应都应来自 Green 上游。在此示例中，httpbin.org 响应包含 X-Amzn-Trace-Id，而 Blue 上游不包含该字段。

回滚

若要回滚到 Blue，请反转权重：

Admin API

curl -k "https://localhost:7443/apisix/admin/routes/blue-green-route?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "blue-green-route",
    "methods": ["GET"],
    "paths": ["/headers"],
    "service_id": "blue-green-service",
    "plugins": {
      "traffic-split": {
        "rules": [
          {
            "weighted_upstreams": [
              {
                "weight": 0,
                "upstream": {
                  "type": "roundrobin",
                  "nodes": [
                    {
                      "host": "httpbin.org",
                      "port": 443,
                      "weight": 1
                    }
                  ]
                }
              },
              {
                "weight": 100
              }
            ]
          }
        ]
      }
    }
  }'

ADC

更新 traffic-split 权重，使默认上游权重为 100，Green 上游权重为 0；或者直接移除该插件配置。

清理

Green 环境验证完成且稳定后，你可以：

1. 更新服务的默认上游，使其指向 Green 节点。
2. 确认配置已同步，且请求仍由 Green 节点处理。
3. 从路由中移除 traffic-split 插件，再次确认请求由 Green 节点处理。
4. 下线旧的 Blue 环境。

条件式蓝绿切换

你也可以按条件切换流量，例如基于请求头。这适合在切换全部流量之前，先让特定用户测试 Green 环境。

{
  "rules": [
    {
      "match": [
        {
          "vars": [["http_x_env", "==", "green"]]
        }
      ],
      "weighted_upstreams": [
        {
          "weight": 100,
          "upstream": {
            "type": "roundrobin",
            "scheme": "https",
            "pass_host": "node",
            "nodes": [
              {
                "host": "httpbin.org",
                "port": 443,
                "weight": 1
              }
            ]
          }
        }
      ]
    }
  ]
}

使用该配置时：

• 带有 X-Env: green 请求头的请求会被路由到 Green 上游。
• 所有其他请求会继续进入默认（Blue）上游。

后续步骤

• 实施灰度发布：在版本之间逐步转移流量。
• 配置上游健康检查：在部署期间监控上游健康状态。
• 配置故障注入：在部署切换期间测试韧性。