将由 ALB 提供服务的 Ingress 和 ALB 规则迁移到 Gateway API

概述

ALB 已弃用。推荐使用 Envoy Gateway(Gateway API)和 Ingress NGINX 作为 ingress controller。无法创建新的 ALB 实例,Web Console 中也不再提供 ALB。集群从早期版本升级后,其中现有的 ALB 实例仍会继续运行,以便迁移其流量。本指南介绍如何将 L7 HTTP/HTTPS 流量从 ALB 迁移到由 Envoy Gateway 管理的 Gateway API。

请根据目标 ACP 版本规划迁移,而不是根据源版本规划,因为不同版本中的 Gateway API CRD 和 Envoy Gateway 功能存在差异。请参阅 Gateway API CRD 版本。

ALB 以两种形式接收 L7 流量。开始之前,请确定工作负载使用的是哪种形式:

源形式创建方式迁移内容
由 ALB 提供服务的 Ingress每个 ALB 都会创建一个名称相同的 IngressClass,并将匹配的 Ingress 资源转换为生成的 Frontend 和 Rule 资源。生成的规则包含 spec.source.type: ingress 以及类似 alb2.cpaas.io/source-type: ingress 的标签。将原始 Ingress 迁移到 HTTPRoute。不要逐一转换生成的 Rule 资源。
直接创建的 ALB Rule通过 API 或 ALB 控制台创建的 Rule,且不包含 spec.source.type: ingress。它可以是 L7 规则,也可以是 L4 TCP/UDP 规则。将 L7 Rule 转换为 HTTPRoute。将 L4 Rule 分别转换为 TCPRoute 或 UDPRoute。

Gateway API 是一种新的配置模型。它不提供 ALB 规则、Ingress 注解或 ALB dslx 表达式的运行时兼容性。迁移意味着创建等效的 Gateway、HTTPRoute 和策略资源,对其进行验证,然后迁移流量。

WARNING

ALB 已弃用。仅当应用需要 Gateway API 无法表示的 Ingress 特定行为时,才使用 Ingress NGINX Operator。对于新的 L7 流量,请使用 Envoy Gateway 和 Gateway API。

本指南涵盖 L7 HTTP/HTTPS 流量。对于 ALB TCP/UDP 前端和规则,请参阅 迁移 L4 流量,并评估已安装的 Envoy Gateway 版本对 TCPRoute/UDPRoute 的支持情况。

迁移模型

ALB 对象或字段Gateway API 资源迁移说明
ALB2 实例GatewayClass 和 Gateway一个 ALB 通常对应一个 Gateway。
Frontend(端口和协议)Gateway.spec.listeners[] 或 ListenerSet.spec.listeners[]每个对外暴露的端口使用一个 listener。HTTPS listener 携带证书。
Frontend 或 Rule 证书Listener tls.certificateRefs将 .spec.certificate_name(namespace/secret)转换为 Secret 引用。
从 Ingress 生成的 Rule从原始 Ingress 转换而来的 HTTPRoute生成的 Rule 是 Ingress 的投影。不要直接迁移它。
直接创建的 RuleHTTPRoute 规则;对于 L4,则为 TCPRoute/UDPRoute转换 dslx、后端和操作。
dslx HOSTHTTPRoute.spec.hostnames[]EQ 映射到精确主机名。通配符和后缀匹配需要谨慎处理。
dslx URLHTTPRoute.spec.rules[].matches[].pathSTARTS_WITH 映射到 PathPrefix,EQ 映射到 Exact,REGEX 映射到 RegularExpression。ALB 正则表达式采用搜索/前缀匹配;Envoy RegularExpression 必须匹配整个路径,因此除非模式以 $ 结尾,否则应追加 .*。
vhost带有 hostname 的 URLRewrite 过滤器覆盖发送到后端的 Host 标头。
serviceGroup.servicesbackendRefs[]保留 Service 名称、命名空间、端口和权重。
priority无直接对应字段HTTPRoute 优先级取决于匹配的具体程度,而不是 ALB 优先级编号。请重新检查冲突路由。
.spec.config.timeoutHTTPRoute.spec.rules[].timeouts 或 BackendTrafficPolicy连接超时和响应超时各有不同的对应配置。
.spec.config.redirectRequestRedirect 过滤器不要保留占位后端。
enableCORS、corsAllowOrigin、corsAllowHeadersSecurityPolicy.spec.cors 或 CORS 路由过滤器检查通配符和多来源行为。
rewrite_base 和 rewrite_targetURLRewrite 过滤器,或带有 ReplaceRegexMatch 的 HTTPRouteFilter正则表达式捕获组替换需要 Envoy Gateway 扩展。
alb.ingress.cpaas.io/rewrite-request 或 alb.rule.cpaas.io/rewrite-request静态值使用 RequestHeaderModifier;对于 headers_var,使用带 Lua 的 EnvoyExtensionPolicyheaders_var 值是 nginx 变量;动态值请使用 Lua policy。
alb.ingress.cpaas.io/rewrite-response 或 alb.rule.cpaas.io/rewrite-responseResponseHeaderModifier 或 ClientTrafficPolicy使用 set 匹配 ALB ngx.header 语义。
backendProtocol: httpsBackendTLSPolicy指向实际的 Service 端口,并验证后端证书。
backendProtocol: grpcGRPCRoute,或带有 appProtocol: kubernetes.io/h2c 的 Service当后端使用 gRPC 时,请使用 GRPCRoute。
session_affinity_policyHTTPRoute.spec.rules[].sessionPersistence 或 BackendTrafficPolicyCookie 亲和性映射到 sessionPersistence;标头和 sip-hash 亲和性映射到 BackendTrafficPolicy 一致性哈希。
ALB VIPGateway 数据平面 Service 或 MetalLB 地址并行运行时使用单独的 VIP,然后切换 DNS。
ALB 项目分配或端口-项目隔离Gateway.spec.listeners[].allowedRoutes.namespaces使用 Same、Selector 或 All 控制哪些项目可以关联路由。

步骤 1:盘点现有配置

导出 ALB 对象和 Ingress 资源:

kubectl get alaudaloadbalancer2 -A -o yaml > alb2-backup.yaml
kubectl get frontends.crd.alauda.io -A -o yaml > alb-frontends-backup.yaml
kubectl get rules.crd.alauda.io -A -o yaml > alb-rules-backup.yaml
kubectl get ingress -A -o yaml > ingress-backup.yaml

如需对导出的 ALB2、Frontend、Rule、相关 Namespace 和源 Ingress YAML 进行初步转换,请参阅 ALB2/Frontend/Rule 到 Gateway API 迁移助手。该助手会生成 Gateway API YAML 和转换报告。请将其输出视为初步草稿:它不会应用资源,并且在切换前,必须根据本指南检查报告中的每条警告和缺口。

查找生成的规则及其源 Ingress:

kubectl get rules.crd.alauda.io -A -o jsonpath='{range .items[*]}{.metadata.namespace}/{.metadata.name}{"\t"}{.spec.source.type}{"\t"}{.spec.source.namespace}/{.spec.source.name}{"\n"}{end}'

对于每个源对象,记录:

  • 前端端口和协议,以及证书 Secret;
  • 主机名、路径匹配和 ALB 规则优先级;
  • 后端 Service、端口、权重、协议(HTTP、HTTPS 或 gRPC)以及上游 Host 覆盖(vhost);
  • 重写、请求和响应标头更改、重定向、CORS 和超时;
  • 会话亲和性和负载均衡方法;
  • Ingress 注解和 Rule 注解。

Rule spec 是字段映射的实用起点:dslx 描述匹配条件,serviceGroup 描述后端,config、rewrite_base、rewrite_target、certificate_name 和 backendProtocol 描述操作。生成的 dslx 还会显示 ALB 如何解释每个 Ingress 路径(STARTS_WITH 或 REGEX),这决定了 HTTPRoute 需要 PathPrefix 还是 RegularExpression。

步骤 2:创建或选择 Gateway

创建一个 Gateway,并为每个 ALB 前端端口配置一个 listener。ACP 建议每个 Gateway 使用一个专用的 EnvoyProxy;Web Console 默认创建的配置也是如此。请参阅 EnvoyProxy(Deployment Configuration),并从 Gateway.spec.infrastructure.parametersRef 引用其中的 EnvoyProxy。以下示例会终止 TLS,并暴露 HTTP 和 HTTPS:

apiVersion: gateway.envoyproxy.io/v1alpha1
kind: EnvoyProxy
metadata:
  name: public-gateway
  namespace: gateway-system
spec:
  provider:
    type: Kubernetes
    kubernetes:
      envoyService:
        type: LoadBalancer
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: public-gateway
  namespace: gateway-system
spec:
  gatewayClassName: envoy-gateway-operator-cpaas-default
  infrastructure:
    parametersRef:
      group: gateway.envoyproxy.io
      kind: EnvoyProxy
      name: public-gateway
  listeners:
    - name: http
      protocol: HTTP
      port: 80
      allowedRoutes:
        namespaces:
          from: All
    - name: https
      protocol: HTTPS
      port: 443
      tls:
        mode: Terminate
        certificateRefs:
          - kind: Secret
            name: app-example-tls
      allowedRoutes:
        namespaces:
          from: All

将 envoy-gateway-operator-cpaas-default 替换为你的 EnvoyGatewayCtl 创建的 GatewayClass。

不带 hostname 的 listener 会接受该端口上的所有主机名。除非需要为每个主机名使用不同的证书,否则请将主机名放入 HTTPRoute.spec.hostnames。如果一个 HTTPS 端口提供多个证书,请在 tls.certificateRefs 中列出所有证书 Secret,并让 Envoy Gateway 根据 SNI 选择证书。

请有意使用 allowedRoutes。from: Same 将路由限制在 Gateway 所在的命名空间;from: All 允许来自所有命名空间的路由;from: Selector 仅允许匹配该选择器的命名空间。如果证书 Secret 位于其他命名空间,请在该命名空间中创建 ReferenceGrant。

allowedRoutes 也是保留 ALB 项目分配和端口-项目隔离的推荐方式。每个项目端口使用一个 listener,并将 listener 的 allowedRoutes 设置为项目命名空间(当 Gateway 位于该命名空间时使用 from: Same)、项目标签选择器(from: Selector),或仅在有意共享 listener 时使用 from: All。

在创建路由前,确认 Gateway 已完成编程:

kubectl get gateway public-gateway -n gateway-system -o yaml

Gateway 应报告 Programmed=True,并且其状态应包含客户端可以访问的地址。

大多数 ALB 实例暴露的端口少于 63 个。如果源 ALB 暴露的端口超过 63 个,请参阅本指南末尾的Listener 限制和大型 ALB 迁移。

步骤 3:将由 ALB 提供服务的 Ingress 转换为 HTTPRoute

当源对象是由 ALB 提供服务的 Ingress 时,请迁移该 Ingress。生成的 Rule 资源由 ALB controller 重新创建,不能作为稳定的迁移输入。

包含主机、前缀路径和 Service 后端的 Ingress 可以表示如下:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: web
  namespace: default
spec:
  parentRefs:
    - name: public-gateway
      namespace: gateway-system
      sectionName: https
  hostnames:
    - app.example.com
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        - name: web
          port: 8080

转换规则如下:

  • 将 spec.rules[].host 映射到 hostnames;
  • 将 pathType: Prefix 映射到 PathPrefix,并将 pathType: Exact 映射到 Exact;
  • 对于 pathType: ImplementationSpecific,检查生成的 Rule dslx。当路径不包含正则表达式元字符时,ALB 使用 STARTS_WITH,否则使用 REGEX。将普通路径映射到 PathPrefix,将正则表达式路径映射到 RegularExpression;
  • ALB 正则表达式使用搜索匹配或前缀匹配,而 Envoy Gateway RegularExpression 必须匹配整个路径。除非原始模式以 $ 结尾,否则追加 .* 或 (/.*)?;
  • PathPrefix 匹配路径元素:/v1 匹配 /v1 和 /v1/...,但不匹配 /v1beta;而 ALB STARTS_WITH /v1 还会匹配 /v1beta;
  • 将 Ingress 后端 Service 和端口映射到 backendRefs;
  • 将 ingressClassName 替换为适当的 parentRefs 和 listener sectionName;
  • 尽可能将一个源 Ingress 保持为一个 HTTPRoute,每个路径对应一条规则;
  • 仅当某项策略或兼容性行为需要更小的附加范围时,才拆分路由。

迁移后,将 Ingress 注解保留在相同的作用域。Ingress 上的注解适用于整个 Ingress;HTTPRoute 过滤器可以应用于单条规则、整个路由或 Gateway。不要将每个 Ingress 注解复制到每条 HTTPRoute 规则。

请阅读配置 Gateway API 路由,了解路由附加和匹配行为。

步骤 4:转换 ALB 规则

对于直接创建的 Rule,将 Rule spec 的每个部分映射到一个 HTTPRoute。

匹配条件

不同类型的 dslx 条目之间使用 AND 组合。同一条目中的多个值使用 OR 组合。

ALB dslxHTTPRoute 等效项说明
HOST with EQspec.hostnames[]使用精确的主机名。
HOST with ENDS_WITHspec.hostnames[] with a wildcard*.example.com 不匹配 apex example.com。
URL with STARTS_WITHmatches[].path.type: PathPrefix路径逐个元素进行匹配。
URL with EQmatches[].path.type: Exact对于必须优先于更宽泛前缀的路由,请使用此项。
URL with REGEXmatches[].path.type: RegularExpression正则表达式引擎是 RE2,而不是 PCRE。ALB 正则表达式是搜索/前缀匹配;Envoy RegularExpression 必须匹配整个路径,因此除非模式以 $ 结尾,否则请追加 .*。
METHOD with EQmatches[].method—
HEADERmatches[].headers[]同一匹配中的多个标头使用 AND 组合。
PARAMmatches[].queryParams[]—
COOKIE无标准 HTTPRouteMatch 字段使用 matches[].headers[] 和能匹配整个标头值的 RegularExpression 匹配 Cookie 标头,例如 .*session=abc.*。
将 SRC_IP 用作允许列表带有 defaultAction: Deny 的 SecurityPolicy.spec.authorization,以及使用 principal.clientCIDRs 的允许规则当 ALB 使用 X-Real-IP 或 X-Forwarded-For 时,添加 ClientTrafficPolicy.clientIPDetection。
使用 SRC_IP 选择后端无直接的 HTTPRoute 等效项SecurityPolicy 用于访问控制,而不是路由。保留规则拆分,或更改应用程序。

ALB 首先读取 X-Real-IP,然后读取最左侧的 X-Forwarded-For 条目,最后读取对端地址。Envoy Gateway 支持 customHeader(用于 X-Real-IP)中的一种,或支持带有从右侧计数的 numTrustedHops 的 xForwardedFor。ClientTrafficPolicy 适用于整个 Gateway 或 listener,而不是单个路由。对于允许列表,请勿信任客户端提供的最左侧 X-Forwarded-For 值。

例如,将匹配 api.example.com/v1 并转发到 api:8080 的规则转换为:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: api
  namespace: application
spec:
  parentRefs:
    - name: public-gateway
      namespace: gateway-system
      sectionName: https
  hostnames:
    - api.example.com
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /v1
      backendRefs:
        - name: api
          port: 8080

当一条 ALB 规则包含多个 URL 值时,请为每个值创建一个 matches[] 条目。当一条规则组合多个类型时,请将一个组合中的所有条件放在同一匹配项中。

ALB 规则 priority 没有直接对应的 Gateway API 字段。请勿依赖 YAML 文件中规则的顺序。应使重叠路由明确无歧义:对必须优先匹配的路由使用 Exact,并避免更宽泛的前缀或正则表达式路由捕获同一请求。作为最后手段,EnvoyProxy.spec.preserveRouteOrder 可以保留整个 Gateway 的规则顺序,但它会改变该 Gateway 上每条路由的优先级;仅当无法通过匹配特异性表达原始优先级时才使用它。

后端和权重

将 serviceGroup.services 映射到 backendRefs,并保留权重:

rules:
  - matches:
      - path:
          type: PathPrefix
          value: /
    backendRefs:
      - name: api-v1
        port: 8080
        weight: 90
      - name: api-v2
        port: 8080
        weight: 10

当后端 Service 位于其他命名空间时,请在后端命名空间中添加一个 ReferenceGrant。

重写

ALB rewrite_base 和 rewrite_target 是正则表达式匹配与替换对。标准 Gateway API URLRewrite 仅支持 ReplaceFullPath 和 ReplacePrefixMatch;它无法表达正则表达式捕获组。

对于简单的前缀重写,请使用标准过滤器:

filters:
  - type: URLRewrite
    urlRewrite:
      path:
        type: ReplacePrefixMatch
        replacePrefixMatch: /

对于依赖捕获组的规则,请使用带有 ReplaceRegexMatch 的 Envoy Gateway HTTPRouteFilter:

apiVersion: gateway.envoyproxy.io/v1alpha1
kind: HTTPRouteFilter
metadata:
  name: api-rewrite
  namespace: application
spec:
  urlRewrite:
    path:
      type: ReplaceRegexMatch
      replaceRegexMatch:
        pattern: "^/api(/|$)(.*)$"
        substitution: "/\\2"
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: api
  namespace: application
spec:
  parentRefs:
    - name: public-gateway
      namespace: gateway-system
      sectionName: https
  hostnames:
    - app.example.com
  rules:
    - matches:
        - path:
            type: RegularExpression
            value: "^/api(/|$)(.*)$"
      filters:
        - type: ExtensionRef
          extensionRef:
            group: gateway.envoyproxy.io
            kind: HTTPRouteFilter
            name: api-rewrite
      backendRefs:
        - name: api
          port: 8080

转换重写时,请检查以下事项:

  • 仅向实际更改路径的规则添加重写过滤器。无需添加诸如将 ^/(console-portal)(/|$)(.*)$ 重写为 /$1$2$3 这样的无操作重写;未配置重写时,HTTPRoute 会转发原始路径。
  • 使用严格边界,例如 (/|$),而不是 (.|$)。诸如 business-1(.|$) 的模式也可能匹配 business-10。
  • 不要将 ALB 通配符路径视为正则表达式。/dex/* 应转换为 PathPrefix /dex/,而不是正则表达式。
  • 仔细将 nginx 正则表达式转换为 RE2。捕获引用和前瞻/后瞻可能需要使用不同的表达式。

请求和响应标头

对于静态标头更改,请使用 RequestHeaderModifier 和 ResponseHeaderModifier:

filters:
  - type: RequestHeaderModifier
    requestHeaderModifier:
      set:
        - name: X-Forwarded-Proto
          value: https
      remove:
        - X-Internal-Debug
  - type: ResponseHeaderModifier
    responseHeaderModifier:
      set:
        - name: X-Frame-Options
          value: SAMEORIGIN

ALB rewrite-response 使用 ngx.header[key] = value,它会替换标头。当该行为很重要时,请使用 set,而不是 add。

如果 Gateway 后的每个 Ingress 都应用相同的响应标头,则使用带有 lateResponseHeaders 的 Gateway 级别 ClientTrafficPolicy,可以避免在每条路由上重复该过滤器:

apiVersion: gateway.envoyproxy.io/v1alpha1
kind: ClientTrafficPolicy
metadata:
  name: security-response-headers
  namespace: gateway-system
spec:
  targetRefs:
    - group: gateway.networking.k8s.io
      kind: Gateway
      name: public-gateway
  headers:
    lateResponseHeaders:
      set:
        - name: X-Frame-Options
          value: SAMEORIGIN
        - name: X-Content-Type-Options
          value: nosniff

仅当每条路由都需要相同标头时,才使用 Gateway 级别的策略。如果不同的 Ingress 资源设置了不同的值,请将策略或过滤器附加到受影响的路由。

来自 nginx 变量的动态标头值

ALB rewrite-request 还支持 headers_var 和 headers_add_var。它们的值是 nginx 变量,而不是静态字符串:

{"headers_var":{"X-Original-Method":"request_method"}}

标准 RequestHeaderModifier 无法计算 nginx 变量,因为它只能设置静态值。对于此模式,请使用带有 Lua 过滤器的 EnvoyExtensionPolicy,读取请求、提取值并设置目标标头。以下示例将 HTTP 方法复制到 X-Original-Method 标头:

apiVersion: gateway.envoyproxy.io/v1alpha1
kind: EnvoyExtensionPolicy
metadata:
  name: dynamic-request-headers
  namespace: application
spec:
  targetRefs:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      name: api
  lua:
    - type: Inline
      inline: |
        function envoy_on_request(handle)
          local method = handle:headers():get(":method")
          if method ~= nil then
            handle:headers():replace("x-original-method", method)
          end
        end

仅将策略附加到需要动态标头的路由;将其附加到整个 Gateway 会更改不相关的应用程序。对于会替换标头的 headers_var,使用 handle:headers():replace(...);对于会追加标头的 headers_add_var,使用 handle:headers():add(...)。如果值是静态的,请使用 RequestHeaderModifier,而不是 Lua。

重定向

不要将 ALB 重定向规则作为普通后端路由迁移。ALB 重定向规则通常指向诸如 none:8080 这样的占位后端;保留该后端会产生 Envoy 500 错误,并隐藏真实路径。

请使用标准的 RequestRedirect 过滤器:

rules:
  - matches:
      - path:
          type: PathPrefix
          value: /
    filters:
      - type: RequestRedirect
        requestRedirect:
          scheme: https
          hostname: www.example.com
          statusCode: 301

请检查重定向路由不会遮蔽现有的应用程序路由。不得将全捕获的 PathPrefix / 重定向附加到同时提供真实应用程序路由的 listener。

CORS

ALB enableCORS、corsAllowOrigin 和 corsAllowHeaders 可以映射到 SecurityPolicy.spec.cors 或路由级别的 CORS 过滤器:

apiVersion: gateway.envoyproxy.io/v1alpha1
kind: SecurityPolicy
metadata:
  name: api-cors
  namespace: application
spec:
  targetRefs:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      name: api
  cors:
    allowOrigins:
      - "https://app.example.com"
      - "https://*.example.com"
    allowMethods:
      - GET
      - POST
      - OPTIONS
    allowHeaders:
      - Authorization
      - Content-Type

将以逗号分隔的 ALB origin 和标头列表拆分为单独的列表项。Envoy Gateway origin 支持精确值、单个通配符标签和全局 *;不支持任意正则表达式,也不支持动态反映请求 origin 的值。带通配符端口的 ALB origin(例如 http://172.21.4.4:*)需要指定明确的端口。如果 ALB 使用了 $http_origin,请验证生成的行为或更改应用程序。

超时

ALB 超时在 .spec.config.timeout 中配置:

ALB 字段最接近的 Gateway API 等效项说明
proxy_connect_timeout_msBackendTrafficPolicy.spec.timeout.tcp.connectTimeout建立连接,包括 TCP 和 TLS 握手。
proxy_read_timeout_msBackendTrafficPolicy.spec.timeout.http.requestTimeout 或 ClientTrafficPolicy.spec.timeout.http.streamIdleTimeoutALB 测量连续读取之间的时间间隔;请选择语义与工作负载匹配的字段。
proxy_send_timeout_msClientTrafficPolicy.spec.timeout.http.streamIdleTimeout 或 BackendTrafficPolicy.spec.timeout.http.connectionIdleTimeout没有完全一对一的字段。请验证长连接和流式工作负载。

对于每条路由的超时,请使用标准 HTTPRoute 字段:

timeouts:
  request: 30s
  backendRequest: 30s

对于应用于 Gateway 上每条路由的超时,请使用 BackendTrafficPolicy 或 ClientTrafficPolicy。在未检查哪个超时会生效之前,请勿同时设置路由超时和相冲突的策略超时。

会话亲和性

ALB session_affinity_policy 没有单一字段可以映射。请明确选择等效项:

  • 对于基于 Cookie 的亲和性,请使用 HTTPRoute.spec.rules[].sessionPersistence:

    sessionPersistence:
      type: Cookie
      sessionName: app-session
  • 对于基于标头的亲和性,请使用带有基于客户端提供标头的一致性哈希的 BackendTrafficPolicy。请勿使用 sessionPersistence.type: Header:它会使 Gateway 将编码后的上游地址写入响应标头,而 ALB 对客户端已发送的值进行哈希。

    apiVersion: gateway.envoyproxy.io/v1alpha1
    kind: BackendTrafficPolicy
    metadata:
      name: header-affinity
      namespace: application
    spec:
      targetRefs:
        - group: gateway.networking.k8s.io
          kind: HTTPRoute
          name: api
      loadBalancer:
        type: ConsistentHash
        consistentHash:
          type: Headers
          headers:
            - name: x-session-id
  • 对于源 IP 哈希(ALB sip-hash),请使用带有一致性哈希的 BackendTrafficPolicy:

    apiVersion: gateway.envoyproxy.io/v1alpha1
    kind: BackendTrafficPolicy
    metadata:
      name: source-ip-affinity
      namespace: application
    spec:
      targetRefs:
        - group: gateway.networking.k8s.io
          kind: HTTPRoute
          name: api
      loadBalancer:
        type: ConsistentHash
        consistentHash:
          type: SourceIP

请使用真实客户端验证亲和性行为。ALB 与 Envoy Gateway 的哈希输入和 Cookie 行为并不完全相同。

HTTPS 后端

HTTPRoute 转发到 Service 时使用 HTTP,除非配置了后端 TLS 策略。如果 ALB 规则包含 backendProtocol: https,请创建一个 BackendTLSPolicy:

apiVersion: gateway.networking.k8s.io/v1
kind: BackendTLSPolicy
metadata:
  name: api-backend-tls
  namespace: application
spec:
  targetRefs:
    - group: ""
      kind: Service
      name: api
      sectionName: https
  validation:
    hostname: api.application.svc
    wellKnownCACertificates: System

targetRefs.sectionName 必须是实际的 Service 端口名称,而不是端口号。validation.hostname 必须匹配后端证书中的 SAN;它不一定是 Service 名称。如果后端使用私有 CA,请引用适当的 Secret 或 ConfigMap,而不是 wellKnownCACertificates。ACP 4.3 及更高版本提供 BackendTLSPolicy v1;ACP 4.2 提供 v1alpha3,它使用相同的 targetRefs 和 validation 字段,因此只需更改 apiVersion;ACP 4.1 及更早版本使用旧版 v1alpha2 schema,其中包含单数形式的 targetRef,以及 tls.*。

步骤 5:处理没有直接转换方式的行为

ALB rewrite-request 和 rewrite-response 对于静态值可通过 RequestHeaderModifier 和 ResponseHeaderModifier 实现,对于 headers_var 和 headers_add_var 可通过结合 Lua 的 EnvoyExtensionPolicy 实现。在每个剩余行为都有明确的替代方案或已接受的产品限制之前,请勿将路由标记为已迁移:

  • 依赖 RE2 不支持的 PCRE 功能的正则重写和 ImplementationSpecific 路径;
  • 自定义负载均衡算法,例如 EWMA;
  • 已安装的 Envoy Gateway policy 未提供的 WAF 功能;
  • 用作路由条件以选择不同后端的 SRC_IP;
  • 目标依赖动态 nginx 变量的重定向;
  • 必须逐位保留的 ALB 会话亲和性。

ALB 项目分配和端口项目隔离没有直接对应的 HTTPRoute 字段。请使用 Gateway.spec.listeners[].allowedRoutes.namespaces 保留这些设置:from: Same 将路由限制在 Gateway 命名空间内,from: Selector 按标签匹配项目命名空间,from: All 则允许所有命名空间。针对每个监听器应用此设置,使项目只能将路由附加到属于该项目的监听器。移除 ALB 之前,请确认所需的隔离行为。

迁移 L4 流量

ALB TCP 和 UDP 前端不会通过 HTTPRoute 迁移。直接创建的 L4 Frontend 可以包含自身的 spec.serviceGroup,而不需要单独的 Rule。对于每个 L4 前端、其中嵌入的 serviceGroup 以及任何直接创建的 Rule,请评估以下方案:

  • 当流量不需要 Gateway API 路由时,使用 LoadBalancer Service;
  • 当已安装的 Envoy Gateway 版本支持相应路由类型时,使用 TCPRoute 或 UDPRoute;
  • 如果已安装的版本不支持所需的路由类型,则为 L4 端口保留 ALB。

将 Frontend 或 Rule serviceGroup.services 映射到 TCPRoute 或 UDPRoute backendRefs。请勿为 TCP 或 UDP 前端创建 HTTPRoute。请分别检查后端端口和会话亲和性行为;L4 规则上的 ALB sip-hash 不同于 HTTP 会话持久性。

第 6 步:在切换前进行验证

在不删除旧资源的情况下应用新资源:

kubectl apply -f gateway.yaml
kubectl apply -f routes-and-policies.yaml

在每一层检查状态:

kubectl get gateway -A
kubectl get httproute -A -o yaml
kubectl get backendtlspolicy,clienttrafficpolicy,backendtrafficpolicy,securitypolicy -A

验证以下所有内容:

  1. Gateway 报告 Programmed=True。
  2. 每个 HTTPRoute 在 status.parents 下都有 Accepted=True 和 ResolvedRefs=True。
  3. 每个引用的 Service、Secret、policy 和扩展资源都已解析。
  4. HTTP 和 HTTPS 请求返回预期的状态、标头、重定向和响应正文。
  5. 正则路径、重写路径、会话持久性、CORS、身份验证和后端 TLS 均按预期工作。
  6. 测试主机名能够访问新 Gateway 地址,且不会访问旧 ALB。
  7. 响应时间、错误率和吞吐量符合工作负载要求。

在 DNS 更改前进行测试时,使用带有显式 Host 标头的 curl:

curl --resolve app.example.com:443:<gateway-address> \
  --cacert <ca-file> https://app.example.com/api/health

某些应用不支持 HEAD;请使用真实的 GET 请求执行最终功能检查。

第 7 步:切换并回滚

验证完成后,以受控方式迁移流量:

  1. 在更改前降低 DNS TTL。
  2. 将测试流量或一小部分流量指向 Gateway 地址。
  3. 监控请求错误、延迟、后端运行状况以及 Gateway/HTTPRoute 状态。
  4. 更新生产 DNS 记录或外部负载均衡器目标。
  5. 在观察窗口期间保留旧 ALB 或 Ingress 配置。

如果新路径失败,请将 DNS 或外部负载均衡器目标恢复为旧地址,然后在重试前检查路由和 policy 状态。在回滚窗口结束且新路径通过约定的监控周期之前,请勿缩减或删除旧 ALB。

监听器限制和大型 ALB 迁移

大多数 ALB 实例公开的端口少于 63 个,无需使用本节。仅当源 ALB 具有大量监听器时使用本节。

监听器限制取决于 ACP 版本。ACP 在每个 Gateway 和每个 ListenerSet 上最多支持 63 个监听器。当源 ALB 公开的端口数超过单个对象的容量时,请使用 ListenerSet,或将监听器拆分到多个 Gateway 中。

ACP 版本ListenerSetWeb Console迁移具有超过 63 个端口的 ALB
早于 4.4不作为受支持的产品功能提供不提供单个 Gateway 无法容纳所有监听器。将端口拆分到多个 Gateway 中(每个最多 63 个监听器),并可选择在它们之间共享一个 VIP;请参阅在多个 Gateway 之间共享 VIP。也可以减少公开的端口数,或让 ALB 继续处理超出的端口。
4.4.x通过 API 和 YAML 支持不提供通过 YAML 创建一个或多个 ListenerSet 资源,并将其附加到 Gateway。或者,将端口拆分到多个 Gateway 中并共享一个 VIP;请参阅在多个 Gateway 之间共享 VIP。
4.5.x 及更高版本支持支持在 Web Console 中创建 ListenerSet 资源。

63 个监听器的限制针对每个 Gateway 和每个 ListenerSet,而不是整个集群。多个 ListenerSet 可以附加到同一个 Gateway。在 ACP 4.4 上,迁移完全通过 YAML 支持;Web Console 缺少的支持仅影响 ListenerSet 的创建和查看方式。

有关当前的 ListenerSet 操作步骤,请参阅配置 Gateway API ListenerSet。有关各版本安装的 CRD 版本,请参阅Gateway API CRD 版本。

使用 ListenerSet 超过 63 个监听器

如果一个 ALB 公开的端口超过 63 个,请将前 63 个监听器保留在 Gateway 上,并为其他端口创建一个 ListenerSet。父 Gateway 必须允许 ListenerSet。以下示例仅显示 http 监听器和新的 allowedListeners 字段;请将 allowedListeners 添加到第 2 步中的 Gateway,而不是替换其完整的监听器列表。该示例复用了第 2 步中的 EnvoyProxy:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: public-gateway
  namespace: gateway-system
spec:
  gatewayClassName: envoy-gateway-operator-cpaas-default
  infrastructure:
    parametersRef:
      group: gateway.envoyproxy.io
      kind: EnvoyProxy
      name: public-gateway
  allowedListeners:
    namespaces:
      from: Same
  listeners:
    - name: http
      protocol: HTTP
      port: 80
      allowedRoutes:
        namespaces:
          from: All
apiVersion: gateway.networking.k8s.io/v1
kind: ListenerSet
metadata:
  name: public-gateway-extra
  namespace: gateway-system
spec:
  parentRef:
    name: public-gateway
    namespace: gateway-system
  listeners:
    - name: tcp-1805
      protocol: TCP
      port: 1805
      allowedRoutes:
        namespaces:
          from: All

通过将 parentRefs[].kind: ListenerSet 和 sectionName 设置为监听器名称,将 Route 附加到 ListenerSet 监听器。完整操作步骤请参阅配置 Gateway API ListenerSet。

在 ACP 4.4 上,通过 YAML 创建和编辑 ListenerSet。在 ACP 4.5 及更高版本中,Web Console 也提供 ListenerSet 创建页面。

在多个 Gateway 之间共享 VIP

在不支持 ListenerSet 的版本上,或当您不希望使用 ListenerSet 时,可以将监听器拆分到多个 Gateway 中,并使用 MetalLB IP 共享功能通过一个 VIP 暴露所有监听器。每个 Gateway 仍有自己的 EnvoyProxy 和自己的 Envoy data-plane Service。

这是一种变通方案,而不是默认的迁移路径。ListenerSet 可用时,优先使用 ListenerSet。

以下示例创建两个共享一个 VIP 的 Gateway:

apiVersion: metallb.io/v1beta1
kind: IPAddressPool
metadata:
  name: shared-gateway-vip
  namespace: metallb-system
spec:
  addresses:
    - 192.0.2.100/32
  autoAssign: false
---
apiVersion: metallb.io/v1beta1
kind: L2Advertisement
metadata:
  name: shared-gateway-vip
  namespace: metallb-system
spec:
  ipAddressPools:
    - shared-gateway-vip
---
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: EnvoyProxy
metadata:
  name: gw-a
  namespace: gateway-system
spec:
  provider:
    type: Kubernetes
    kubernetes:
      envoyService:
        type: LoadBalancer
        externalTrafficPolicy: Cluster
        annotations:
          metallb.io/allow-shared-ip: shared-gateway-vip
          metallb.io/loadBalancerIPs: 192.0.2.100
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: gw-a
  namespace: gateway-system
spec:
  gatewayClassName: envoy-gateway-operator-cpaas-default
  infrastructure:
    parametersRef:
      group: gateway.envoyproxy.io
      kind: EnvoyProxy
      name: gw-a
  listeners:
    - name: http-a
      protocol: HTTP
      port: 8080
      allowedRoutes:
        namespaces:
          from: All

以相同方式创建 gw-b,为其设置自己的 EnvoyProxy、相同的 allow-shared-ip 键和 VIP,以及不同的监听器端口:

apiVersion: gateway.envoyproxy.io/v1alpha1
kind: EnvoyProxy
metadata:
  name: gw-b
  namespace: gateway-system
spec:
  provider:
    type: Kubernetes
    kubernetes:
      envoyService:
        type: LoadBalancer
        externalTrafficPolicy: Cluster
        annotations:
          metallb.io/allow-shared-ip: shared-gateway-vip
          metallb.io/loadBalancerIPs: 192.0.2.100
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: gw-b
  namespace: gateway-system
spec:
  gatewayClassName: envoy-gateway-operator-cpaas-default
  infrastructure:
    parametersRef:
      group: gateway.envoyproxy.io
      kind: EnvoyProxy
      name: gw-b
  listeners:
    - name: http-b
      protocol: HTTP
      port: 8081
      allowedRoutes:
        namespaces:
          from: All

请遵循以下规则:

  • 每个 Gateway 都必须有自己的 EnvoyProxy 和 data-plane Service。请勿尝试将不同 Gateway 的监听器放入同一个 Service。
  • 在共享 VIP 的每个 Service 上设置 externalTrafficPolicy: Cluster。使用 Local 时,MetalLB 的共享后端键包含 Service selector;每个 Gateway 都有自己的 selector,因此第二个 Service 会因后端键不匹配而保持 <pending>。Local 还可能导致没有本地端点的节点丢弃流量。
  • 共享 VIP 的 Service 端口不得重叠。MetalLB 会检查 protocol/port 对:两个 Service 不能在同一个 VIP 上同时公开 TCP/8080。如果两个 Gateway 必须提供相同端口,则此变通方案不适用;请使用带有 HTTPRoute 主机名的单个监听器,或使用 ListenerSet。
  • 设置 IPAddressPool.spec.autoAssign: false,并使用 metallb.io/loadBalancerIPs 显式请求 VIP。使用 autoAssign: true 时,不相关的处于 pending 状态的 LoadBalancer Service 可能会先获得该 VIP。
  • 通过 EnvoyProxy.spec.provider.kubernetes.envoyService.annotations 设置注解,而不是直接编辑 Envoy data-plane Service;operator 会协调该 Service。
  • 请勿使用 Gateway.spec.addresses 固定 VIP。Envoy Gateway 会将该字段映射到 Service.spec.externalIPs,而不是 MetalLB 负载均衡器 IP。

MetalLB 0.15 也接受已弃用的 metallb.universe.tf/ 前缀。请使用 MetalLB 版本文档中说明的前缀;同一个注解不要混用不同前缀。

externalTrafficPolicy: Cluster 可能会丢失原始客户端源 IP,因为 kube-proxy 可能会对连接执行 SNAT。ClientTrafficPolicy.clientIPDetection 只能读取上游负载均衡器或代理已经写入 X-Forwarded-For、自定义标头或 PROXY protocol 的地址;无法恢复已被 SNAT 丢弃的地址。如果应用依赖客户端 IP,请使用带有 ListenerSet 和 Local 的单个 Gateway,或确保上游设备添加其中一个标头。这也会影响 ConsistentHash: SourceIP 和基于源 IP 的授权,它们看到的将是节点或代理 IP,而不是客户端 IP。

验证两个 Service 是否都获得了相同的 VIP,以及两个 Gateway 是否都已编程:

kubectl get gateway -n gateway-system
kubectl get svc -n <envoy-gateway-ctl-namespace> -l gateway.envoyproxy.io/owning-gateway-namespace=gateway-system -o wide

Envoy data-plane Service 会在 EnvoyGatewayCtl 所在的命名空间中创建,不一定在 Gateway 命名空间中。

如果某个 Service 保持在 <pending>,请检查 MetalLB controller 事件中是否存在分配失败。端口冲突会报告 port TCP/<port> is already in use on "<vip>";Local 共享冲突会报告后端键不匹配。

此变通方案不提供跨 Gateway 的运行状况检查或故障转移。每个 Gateway 都是独立的数据平面;请分别监控每个 Gateway 及其自身的后端运行状况。

相关文档