将由 ALB 提供服务的 Ingress 和 ALB 规则迁移到 Gateway API
目录
概述迁移模型步骤 1:盘点现有配置步骤 2:创建或选择 Gateway步骤 3:将由 ALB 提供服务的 Ingress 转换为 HTTPRoute步骤 4:转换 ALB 规则匹配条件后端和权重重写请求和响应标头来自 nginx 变量的动态标头值重定向CORS超时会话亲和性HTTPS 后端步骤 5:处理没有直接转换方式的行为迁移 L4 流量第 6 步:在切换前进行验证第 7 步:切换并回滚监听器限制和大型 ALB 迁移使用 ListenerSet 超过 63 个监听器在多个 Gateway 之间共享 VIP相关文档概述
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 流量。开始之前,请确定工作负载使用的是哪种形式:
Gateway API 是一种新的配置模型。它不提供 ALB 规则、Ingress 注解或 ALB dslx 表达式的运行时兼容性。迁移意味着创建等效的 Gateway、HTTPRoute 和策略资源,对其进行验证,然后迁移流量。
ALB 已弃用。仅当应用需要 Gateway API 无法表示的 Ingress 特定行为时,才使用 Ingress NGINX Operator。对于新的 L7 流量,请使用 Envoy Gateway 和 Gateway API。
本指南涵盖 L7 HTTP/HTTPS 流量。对于 ALB TCP/UDP 前端和规则,请参阅 迁移 L4 流量,并评估已安装的 Envoy Gateway 版本对 TCPRoute/UDPRoute 的支持情况。
迁移模型
步骤 1:盘点现有配置
导出 ALB 对象和 Ingress 资源:
如需对导出的 ALB2、Frontend、Rule、相关 Namespace 和源 Ingress YAML 进行初步转换,请参阅 ALB2/Frontend/Rule 到 Gateway API 迁移助手。该助手会生成 Gateway API YAML 和转换报告。请将其输出视为初步草稿:它不会应用资源,并且在切换前,必须根据本指南检查报告中的每条警告和缺口。
查找生成的规则及其源 Ingress:
对于每个源对象,记录:
- 前端端口和协议,以及证书 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:
将 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 已完成编程:
Gateway 应报告 Programmed=True,并且其状态应包含客户端可以访问的地址。
大多数 ALB 实例暴露的端口少于 63 个。如果源 ALB 暴露的端口超过 63 个,请参阅本指南末尾的Listener 限制和大型 ALB 迁移。
步骤 3:将由 ALB 提供服务的 Ingress 转换为 HTTPRoute
当源对象是由 ALB 提供服务的 Ingress 时,请迁移该 Ingress。生成的 Rule 资源由 ALB controller 重新创建,不能作为稳定的迁移输入。
包含主机、前缀路径和 Service 后端的 Ingress 可以表示如下:
转换规则如下:
- 将
spec.rules[].host映射到hostnames; - 将
pathType: Prefix映射到PathPrefix,并将pathType: Exact映射到Exact; - 对于
pathType: ImplementationSpecific,检查生成的 Ruledslx。当路径不包含正则表达式元字符时,ALB 使用STARTS_WITH,否则使用REGEX。将普通路径映射到PathPrefix,将正则表达式路径映射到RegularExpression; - ALB 正则表达式使用搜索匹配或前缀匹配,而 Envoy Gateway
RegularExpression必须匹配整个路径。除非原始模式以$结尾,否则追加.*或(/.*)?; PathPrefix匹配路径元素:/v1匹配/v1和/v1/...,但不匹配/v1beta;而 ALBSTARTS_WITH /v1还会匹配/v1beta;- 将 Ingress 后端 Service 和端口映射到
backendRefs; - 将
ingressClassName替换为适当的parentRefs和 listenersectionName; - 尽可能将一个源 Ingress 保持为一个
HTTPRoute,每个路径对应一条规则; - 仅当某项策略或兼容性行为需要更小的附加范围时,才拆分路由。
迁移后,将 Ingress 注解保留在相同的作用域。Ingress 上的注解适用于整个 Ingress;HTTPRoute 过滤器可以应用于单条规则、整个路由或 Gateway。不要将每个 Ingress 注解复制到每条 HTTPRoute 规则。
请阅读配置 Gateway API 路由,了解路由附加和匹配行为。
步骤 4:转换 ALB 规则
对于直接创建的 Rule,将 Rule spec 的每个部分映射到一个 HTTPRoute。
匹配条件
不同类型的 dslx 条目之间使用 AND 组合。同一条目中的多个值使用 OR 组合。
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 的规则转换为:
当一条 ALB 规则包含多个 URL 值时,请为每个值创建一个 matches[] 条目。当一条规则组合多个类型时,请将一个组合中的所有条件放在同一匹配项中。
ALB 规则 priority 没有直接对应的 Gateway API 字段。请勿依赖 YAML 文件中规则的顺序。应使重叠路由明确无歧义:对必须优先匹配的路由使用 Exact,并避免更宽泛的前缀或正则表达式路由捕获同一请求。作为最后手段,EnvoyProxy.spec.preserveRouteOrder 可以保留整个 Gateway 的规则顺序,但它会改变该 Gateway 上每条路由的优先级;仅当无法通过匹配特异性表达原始优先级时才使用它。
后端和权重
将 serviceGroup.services 映射到 backendRefs,并保留权重:
当后端 Service 位于其他命名空间时,请在后端命名空间中添加一个 ReferenceGrant。
重写
ALB rewrite_base 和 rewrite_target 是正则表达式匹配与替换对。标准 Gateway API URLRewrite 仅支持 ReplaceFullPath 和 ReplacePrefixMatch;它无法表达正则表达式捕获组。
对于简单的前缀重写,请使用标准过滤器:
对于依赖捕获组的规则,请使用带有 ReplaceRegexMatch 的 Envoy Gateway HTTPRouteFilter:
转换重写时,请检查以下事项:
- 仅向实际更改路径的规则添加重写过滤器。无需添加诸如将
^/(console-portal)(/|$)(.*)$重写为/$1$2$3这样的无操作重写;未配置重写时,HTTPRoute 会转发原始路径。 - 使用严格边界,例如
(/|$),而不是(.|$)。诸如business-1(.|$)的模式也可能匹配business-10。 - 不要将 ALB 通配符路径视为正则表达式。
/dex/*应转换为PathPrefix /dex/,而不是正则表达式。 - 仔细将 nginx 正则表达式转换为 RE2。捕获引用和前瞻/后瞻可能需要使用不同的表达式。
请求和响应标头
对于静态标头更改,请使用 RequestHeaderModifier 和 ResponseHeaderModifier:
ALB rewrite-response 使用 ngx.header[key] = value,它会替换标头。当该行为很重要时,请使用 set,而不是 add。
如果 Gateway 后的每个 Ingress 都应用相同的响应标头,则使用带有 lateResponseHeaders 的 Gateway 级别 ClientTrafficPolicy,可以避免在每条路由上重复该过滤器:
仅当每条路由都需要相同标头时,才使用 Gateway 级别的策略。如果不同的 Ingress 资源设置了不同的值,请将策略或过滤器附加到受影响的路由。
来自 nginx 变量的动态标头值
ALB rewrite-request 还支持 headers_var 和 headers_add_var。它们的值是 nginx 变量,而不是静态字符串:
标准 RequestHeaderModifier 无法计算 nginx 变量,因为它只能设置静态值。对于此模式,请使用带有 Lua 过滤器的 EnvoyExtensionPolicy,读取请求、提取值并设置目标标头。以下示例将 HTTP 方法复制到 X-Original-Method 标头:
仅将策略附加到需要动态标头的路由;将其附加到整个 Gateway 会更改不相关的应用程序。对于会替换标头的 headers_var,使用 handle:headers():replace(...);对于会追加标头的 headers_add_var,使用 handle:headers():add(...)。如果值是静态的,请使用 RequestHeaderModifier,而不是 Lua。
重定向
不要将 ALB 重定向规则作为普通后端路由迁移。ALB 重定向规则通常指向诸如 none:8080 这样的占位后端;保留该后端会产生 Envoy 500 错误,并隐藏真实路径。
请使用标准的 RequestRedirect 过滤器:
请检查重定向路由不会遮蔽现有的应用程序路由。不得将全捕获的 PathPrefix / 重定向附加到同时提供真实应用程序路由的 listener。
CORS
ALB enableCORS、corsAllowOrigin 和 corsAllowHeaders 可以映射到 SecurityPolicy.spec.cors 或路由级别的 CORS 过滤器:
将以逗号分隔的 ALB origin 和标头列表拆分为单独的列表项。Envoy Gateway origin 支持精确值、单个通配符标签和全局 *;不支持任意正则表达式,也不支持动态反映请求 origin 的值。带通配符端口的 ALB origin(例如 http://172.21.4.4:*)需要指定明确的端口。如果 ALB 使用了 $http_origin,请验证生成的行为或更改应用程序。
超时
ALB 超时在 .spec.config.timeout 中配置:
对于每条路由的超时,请使用标准 HTTPRoute 字段:
对于应用于 Gateway 上每条路由的超时,请使用 BackendTrafficPolicy 或 ClientTrafficPolicy。在未检查哪个超时会生效之前,请勿同时设置路由超时和相冲突的策略超时。
会话亲和性
ALB session_affinity_policy 没有单一字段可以映射。请明确选择等效项:
-
对于基于 Cookie 的亲和性,请使用
HTTPRoute.spec.rules[].sessionPersistence: -
对于基于标头的亲和性,请使用带有基于客户端提供标头的一致性哈希的
BackendTrafficPolicy。请勿使用sessionPersistence.type: Header:它会使 Gateway 将编码后的上游地址写入响应标头,而 ALB 对客户端已发送的值进行哈希。 -
对于源 IP 哈希(ALB
sip-hash),请使用带有一致性哈希的BackendTrafficPolicy:
请使用真实客户端验证亲和性行为。ALB 与 Envoy Gateway 的哈希输入和 Cookie 行为并不完全相同。
HTTPS 后端
HTTPRoute 转发到 Service 时使用 HTTP,除非配置了后端 TLS 策略。如果 ALB 规则包含 backendProtocol: https,请创建一个 BackendTLSPolicy:
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 路由时,使用
LoadBalancerService; - 当已安装的 Envoy Gateway 版本支持相应路由类型时,使用
TCPRoute或UDPRoute; - 如果已安装的版本不支持所需的路由类型,则为 L4 端口保留 ALB。
将 Frontend 或 Rule serviceGroup.services 映射到 TCPRoute 或 UDPRoute backendRefs。请勿为 TCP 或 UDP 前端创建 HTTPRoute。请分别检查后端端口和会话亲和性行为;L4 规则上的 ALB sip-hash 不同于 HTTP 会话持久性。
第 6 步:在切换前进行验证
在不删除旧资源的情况下应用新资源:
在每一层检查状态:
验证以下所有内容:
- Gateway 报告
Programmed=True。 - 每个 HTTPRoute 在
status.parents下都有Accepted=True和ResolvedRefs=True。 - 每个引用的 Service、Secret、policy 和扩展资源都已解析。
- HTTP 和 HTTPS 请求返回预期的状态、标头、重定向和响应正文。
- 正则路径、重写路径、会话持久性、CORS、身份验证和后端 TLS 均按预期工作。
- 测试主机名能够访问新 Gateway 地址,且不会访问旧 ALB。
- 响应时间、错误率和吞吐量符合工作负载要求。
在 DNS 更改前进行测试时,使用带有显式 Host 标头的 curl:
某些应用不支持 HEAD;请使用真实的 GET 请求执行最终功能检查。
第 7 步:切换并回滚
验证完成后,以受控方式迁移流量:
- 在更改前降低 DNS TTL。
- 将测试流量或一小部分流量指向 Gateway 地址。
- 监控请求错误、延迟、后端运行状况以及 Gateway/HTTPRoute 状态。
- 更新生产 DNS 记录或外部负载均衡器目标。
- 在观察窗口期间保留旧 ALB 或 Ingress 配置。
如果新路径失败,请将 DNS 或外部负载均衡器目标恢复为旧地址,然后在重试前检查路由和 policy 状态。在回滚窗口结束且新路径通过约定的监控周期之前,请勿缩减或删除旧 ALB。
监听器限制和大型 ALB 迁移
大多数 ALB 实例公开的端口少于 63 个,无需使用本节。仅当源 ALB 具有大量监听器时使用本节。
监听器限制取决于 ACP 版本。ACP 在每个 Gateway 和每个 ListenerSet 上最多支持 63 个监听器。当源 ALB 公开的端口数超过单个对象的容量时,请使用 ListenerSet,或将监听器拆分到多个 Gateway 中。
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:
通过将 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:
以相同方式创建 gw-b,为其设置自己的 EnvoyProxy、相同的 allow-shared-ip 键和 VIP,以及不同的监听器端口:
请遵循以下规则:
- 每个 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 状态的LoadBalancerService 可能会先获得该 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 是否都已编程:
Envoy data-plane Service 会在 EnvoyGatewayCtl 所在的命名空间中创建,不一定在 Gateway 命名空间中。
如果某个 Service 保持在 <pending>,请检查 MetalLB controller 事件中是否存在分配失败。端口冲突会报告 port TCP/<port> is already in use on "<vip>";Local 共享冲突会报告后端键不匹配。
此变通方案不提供跨 Gateway 的运行状况检查或故障转移。每个 Gateway 都是独立的数据平面;请分别监控每个 Gateway 及其自身的后端运行状况。