容器与云原生 / 系统课时

设计 Ingress 到 Gateway 迁移

设计 Ingress 到 Gateway 迁移

从 Ingress 迁移到 Gateway API 的关键不是“换一种 YAML 写法”,而是先完成能力映射,再让旧入口和新入口并行验证,按门禁逐步切流,并始终保留可执行的回退路径。本课用一组最小对象和一套可运行命令串起迁移链路。

学习目标

  • 将 Ingress 的主机、路径和后端规则映射到 Gateway API 对象
  • 在不修改生产 DNS 的前提下并行验证旧 Ingress 与新 Gateway
  • 用配置、行为和流量门禁控制切换,并准备明确回退动作

先做能力映射再改配置

Ingress 常把入口、路由和实现特定能力集中在一个资源中。Gateway API 将职责拆开:GatewayClass 表示实现类别,Gateway 定义监听入口,HTTPRoute 定义 HTTP 匹配、过滤和后端转发。迁移前先确认目标实现支持哪些标准能力和扩展能力,再改写资源。

Ingress 到 Gateway API 的对象映射与迁移路径

迁移清单至少记录 host、path、pathType、Service、端口、TLS、重写、重定向、超时、流量拆分和认证。Prefix 通常映射为 PathPrefix,Exact 映射为 Exact;ImplementationSpecific 以及控制器 annotation 没有通用的一对一迁移规则,必须按目标 Gateway 实现逐项核对。

建立可并行运行的 Gateway 配置

假设旧 Ingress 继续接收 app.example.com 的 /api 请求,新 Gateway 使用另一套入口地址并转发到同一命名空间的 Service api:80。下面是主配置示例:集群需已安装 Gateway API CRD,并已有名为 example 的 GatewayClass。使用 List 将两个 Gateway API 对象放在一个可直接应用的 YAML 文档中,旧 Ingress 不做改动。

yaml
apiVersion: v1
kind: List
items:
  - apiVersion: gateway.networking.k8s.io/v1
    kind: Gateway
    metadata:
      name: web
      namespace: app
    spec:
      gatewayClassName: example
      listeners:
        - name: http
          protocol: HTTP
          port: 80
          hostname: app.example.com
  - apiVersion: gateway.networking.k8s.io/v1
    kind: HTTPRoute
    metadata:
      name: api
      namespace: app
    spec:
      parentRefs:
        - name: web
      hostnames:
        - app.example.com
      rules:
        - matches:
            - path:
                type: PathPrefix
                value: /api
          backendRefs:
            - name: api
              port: 80

这里 matches 和 backendRefs 同属于 rules 的同一个列表项:matches 先描述 /api 的匹配条件,backendRefs 再描述命中后的后端转发目标。保存为 <PATH> 后应用资源,并检查 Gateway 与 Route 的状态条件。

bash
set -euo pipefail

kubectl apply -f <PATH>

kubectl -n app get gateway web \
  -o jsonpath='{.status.conditions[?(@.type=="Programmed")].status}'; echo
kubectl -n app get httproute api \
  -o jsonpath='{.status.parents[0].conditions[?(@.type=="Accepted")].status}'; echo
kubectl -n app get httproute api \
  -o jsonpath='{.status.parents[0].conditions[?(@.type=="ResolvedRefs")].status}'; echo

OLD_IP="<IP>"
NEW_IP="<IP>"
TEST_PATH="/api/health"
EXPECTED_CODE="<VALUE>"

probe() {
  label="$1"
  ip="$2"
  code="$(curl --silent --show-error --output /dev/null --write-out '%{http_code}' \
    --resolve "app.example.com:80:${ip}" \
    "http://app.example.com${TEST_PATH}")"
  printf '%s http_code=%s\n' "$label" "$code"
  [[ "$code" == "$EXPECTED_CODE" ]]
}

probe old "$OLD_IP"
probe new "$NEW_IP"

old_requests=0
new_requests=0

for i in $(seq 1 100); do
  if (( i % 10 == 0 )); then
    label="new"
    target_ip="$NEW_IP"
  else
    label="old"
    target_ip="$OLD_IP"
  fi

  probe "$label" "$target_ip" >/dev/null

  if [[ "$label" == "new" ]]; then
    ((new_requests+=1))
  else
    ((old_requests+=1))
  fi
done

printf 'old_requests=%d new_requests=%d\n' "$old_requests" "$new_requests"

预期输出

text
gateway.gateway.networking.k8s.io/web created
httproute.gateway.networking.k8s.io/api created
True
True
True
old http_code=<VALUE>
new http_code=<VALUE>
old_requests=90 new_requests=10

重复执行 kubectl apply 时前两行可能显示 configured 或 unchanged。将 OLD_IP、NEW_IP 和 EXPECTED_CODE 替换为环境实际值;只有 Programmed=True、Accepted=True、ResolvedRefs=True,并且 102 次探测都得到期望状态码时脚本才会完成。若入口暴露的是负载均衡器主机名而非 IP,应使用平台提供的测试地址或等价的定向访问方式。

用并行入口验证迁移行为

curl --resolve 会把相同的 Host 和路径定向到指定入口地址,因此旧 Ingress 与新 Gateway 可以在生产 DNS 不变时接受完全相同的请求。先比较单次请求的状态码和响应契约,再运行脚本中的 90/10 合成流量:每 10 个测试请求有 1 个进入新 Gateway,其余仍进入旧 Ingress。

这组 90/10 请求是迁移前的合成灰度,不是生产权重配置。它的价值是把“并行存在”变成可重复执行的验证步骤,并确认新入口能处理与旧入口一致的 Host、Path 和后端请求。生产灰度仍应由实际 DNS、全局负载均衡器或入口层的权重能力完成,并在变更单中记录每一步的比例、观察窗口和回退动作。

按门禁切换并保留回退

进入生产灰度前先冻结旧 Ingress 的非必要变更,并记录错误率、P95/P99 延迟、后端成功率和 TLS 状态基线。切流时按三个门禁推进:配置门禁要求 Gateway 与 Route 状态正常;行为门禁要求路径、重定向、TLS 和关键扩展行为与旧入口一致;流量门禁要求关键指标在观察窗口内没有不可接受退化。

回退条件必须在第一次生产灰度前就写清并演练:旧 Ingress 资源仍存在、入口仍可访问,恢复旧入口流量的控制面动作可以立即执行。若新入口出现 5xx 上升、TLS 异常、路由行为不一致或关键能力缺失,应停止扩大流量并恢复旧入口权重,而不是在故障流量持续进入时现场修改复杂规则。

只有新 Gateway 承担全部目标流量、关键指标持续稳定、Route 与证书状态正常,并经过约定观察期后,才进入旧 Ingress 清理阶段。这样迁移才是可验证、可灰度、可回退的生产变更,而不是一次不可逆的资源替换。

按自己的节奏,确认真正理解。

目录与阅读设置

记录一个想法

设计 Ingress 到 Gateway 迁移

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通