文档中心

容器服务

迁移路由规则

Nginx Ingress 迁移到 ALB Ingress

由于 Ingress NGINX Controller 正式进入退役流程，继续使用 Nginx Ingress 会在扩展性、安全性、稳定性上逐渐产生风险。为保证您的业务安全，建议及时将集群中的 Nginx Ingress 切换为其他路由策略。本文介绍如何在保证业务安全的前提下，将 Nginx Ingress 迁移到 ALB Ingress。

背景信息

Nginx Ingress 停止维护带来的问题

由于 Nginx Ingress 即将停止维护（详情请参见【产品公告】NGINX Ingress 停止维护公告）。继续使用将带来以下问题：

安全隐患：无法获取后续安全补丁，易暴露于未修复的漏洞风险中。

功能瓶颈：不再迭代新特性，难以支撑业务对高级 API 治理（如限流、熔断）、多协议支持（gRPC、WebSocket）等复杂场景的需求。

长期稳定性风险：缺乏官方技术支持，遇到问题时难以快速解决，影响业务连续性。

ALB Ingress 的替代可行性

火山引擎应用型负载均衡（Application Load Balancer，ALB）是专门面向七层业务场景设计的云端负载均衡产品。在 VKE 集群中，相比传统 Nginx Ingress 具备以下核心优势：

更高的容量与协议支持能力：单实例可承载百万级 QPS，原生支持 HTTP、HTTPS、HTTP/2、WebSocket、QUIC 等多种应用层协议，完美适配电商、音视频、大流量等复杂业务场景，在吞吐容量和协议覆盖度上显著优于基于社区 Nginx Ingress 方案。

全托管免运维体验：ALB 作为火山引擎官方托管服务，由平台侧统一负责版本迭代、功能升级和底层基础设施维护。用户仅需通过标准 Kubernetes Ingress 规则及注解下发配置即可实现流量管理，无需关注网关组件的运维操作。相比传统 Nginx Ingress 依赖社区版本节奏、需要用户自行维护版本升级和问题排查的模式，大幅降低长期运维成本。

原生 Kubernetes 生态集成：在 VKE 集群中，ALB Ingress 可直接作为 Kubernetes 原生 Nginx Ingress 的替代方案，能够将集群内的服务快速绑定到 ALB 实例，无需用户自研或额外部署网关组件。通过 ALB 自身的高性能转发能力和丰富的高级路由特性，可有效提升集群整体的流量稳定性和服务可用性。

完善的可观测能力：ALB 原生提供全量七层访问日志，包含客户端 IP、请求路径、服务端响应状态、时延等核心字段，可直接对接日志服务实现用户行为分析、精细化运维和故障快速定位，无需用户额外部署日志采集组件。

自动转换的 Annotation 列表

使用自动迁移工具对集群中的 Nginx Ingress 进行迁移时，迁移工具支持将下表中的 Nginx Ingress Annotation 自动转换为 ALB Ingress Annotation。

注意

不在下表中的 Nginx Ingress Annotation 在转换过程中会被保留，并在转换结果中展示。请您在转换完成后确认转换后的 ALB Ingress 的配置是否符合预期，以及是否存在未转换的 Nginx Ingress Annotation，以避免转换后的配置与业务要求不符。

ALB Ingress 的 Annotation 详细说明，请参见使用 Annotation 配置 ALB Ingress。

功能	原 Nginx Ingress Annotation	转换后的 ALB Annotation
调度算法（Scheduler）	nginx.ingress.kubernetes.io/load-balance	ingress.vke.volcengine.com/loadbalancer-scheduler
跨域（CORS）	nginx.ingress.kubernetes.io/enable-cors	ingress.vke.volcengine.com/loadbalancer-actions.{{service-name}}: \| [ { "type": "Cors", ... } } ]
			nginx.ingress.kubernetes.io/cors-allow-methods
			nginx.ingress.kubernetes.io/cors-allow-origin
			nginx.ingress.kubernetes.io/cors-max-age
			nginx.ingress.kubernetes.io/cors-allow-headers
重定向（Redirect）	nginx.ingress.kubernetes.io/ssl-redirectnginx.ingress.kubernetes.io/force-ssl	ingress.vke.volcengine.com/loadbalancer-actions.{{service-name}}: \| [ { "type": "Redirect", ... } } ]
重写（Rewrite）	nginx.ingress.kubernetes.io/rewrite-target	ingress.vke.volcengine.com/loadbalancer-actions.{{service-name}}: \| [ { "type": "Rewrite", ... } } ]
后端协议（Protocol）	nginx.ingress.kubernetes.io/backend-protocol	ingress.vke.volcengine.com/loadbalancer-protocol

迁移流程

某用户使用 VKE 集群部署在线业务，通过 Nginx Ingress 配置路由转发规则，包括域名和路径的转发策略。并使用 DNS 完成自定义域名（本文中以 example.com 为例）的解析。客户端访问域名 example.com 时，Nginx Ingress 接收到请求会根据转发策略，将流量转发至对应 Service 的后端 Pod 上。

基于业务发展需要和维护性、安全性考虑，该用户需要将 Nginx Ingress 迁移到 ALB Ingress 上。为了保持业务稳定，希望在不改变对外服务域名和后端业务服务配置的前提下完成迁移。此时，可以通过在 VKE 集群上配置 ALB Ingress，使 ALB Ingress 提供的转发策略与 Nginx Ingress 一致，然后利用 DNS 域名解析的权重设置完成流量的迁移。

迁移后，当将流量完全转移至 ALB Ingress 后，删除 DNS 解析中的 Nginx Ingress 解析记录，并删除集群中的 Nginx Ingress 资源，整个流程客户端无感。

迁移步骤

注意

建议在业务低谷期进行流量迁移。

流量迁移前，请首先对比 Nginx Ingress 和 ALB Ingress 的转发规则和功能，并进行充分测试，确保两者功能完全一致，避免切换过程中对业务造成影响。如发现 ALB 支持的功能或注解不满足业务要求，请提交工单或联系技术支持。

使用 ALB 云产品会产生额外费用，详情请参见计费规则。

步骤一：配置转换

VKE 集群支持使用自动转换工具完成 Nginx Ingress 到 ALB Ingress 的配置转换。该工具不会直接替您创建最终可用的 ALB 资源，而是读取集群中的 Nginx Ingress 配置，并输出可供人工确认的 ALBInstance 与 Ingress YAML。您需要在检查配置无误后，再手动执行下发。

操作步骤如下：

使用 kubectl 连接集群。

创建自动转换工具 YAML 文件，该文件包含了执行转换任务所需的 Job 以及配套的 RBAC 权限。示例文件nginxingress2albconfig.yaml代码如下：

apiVersion: batch/v1
kind: Job
metadata:
name: nginxingress2albconfig
namespace: default
spec:
template:
spec:
containers:
- name: nginxingress2albconfig
image: open-registry-cn-beijing.cr.volces.com/vke/nginxingress2albconfig:v0.0.1
command: ["./nginxingress2albconfig", "print"]
restartPolicy: Never
serviceAccount: nginxingress2albconfig
serviceAccountName: nginxingress2albconfig
backoffLimit: 4
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: system:nginxingress2albconfig
rules:
- apiGroups:
- networking.k8s.io
resources:
- ingresses
- ingressclasses
verbs:
- get
- list
- watch
- update
- create
- patch
---
apiVersion: v1
kind: ServiceAccount
metadata:
name: nginxingress2albconfig
namespace: default
---
kind: ClusterRoleBinding
apiVersion: rbac.authorization.k8s.io/v1
metadata:
name: system:nginxingress2albconfig
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: ClusterRole
name: system:nginxingress2albconfig
subjects:
- kind: ServiceAccount
name: nginxingress2albconfig
namespace: default

执行以下命令，创建自动转换任务。

kubectl apply -f nginxingress2albconfig.yaml

预期结果如下。

job.batch/nginxingress2albconfig created
clusterrole.rbac.authorization.k8s.io/system:nginxingress2albconfig created
serviceaccount/nginxingress2albconfig created
clusterrolebinding.rbac.authorization.k8s.io/system:nginxingress2albconfig created

查看执行转换任务的 Pod 状态。

kubectl get pod -l job-name=nginxingress2albconfig

预期输出如下，当 Pod 的STATUS变为Completed，时，表示配置转换任务已完成。

NAME READY STATUS RESTARTS AGE
nginxingress2albconfig-6m*** 0/1 Completed 0 11s

执行以下命令，查看配置转换任务 Pod 日志，获取最终的 ALB 配置文件。其中，请将nginxingress2albconfig-6m***替换为实际转换任务的 Job 名称。

kubectl logs nginxingress2albconfig-6m***

预期结果如下，自动转换工具将输出详细的配置解析概览、ALBInstance 配置以及转换后的 Ingress 规则。

- default/nginx-ingress
共检测到 1 个 Ingress 资源，其中需要转换的 Nginx Ingress 数量为: 1

=== ALBInstance 配置 ===
apiVersion: loadbalancer.vke.volcengine.com/v1beta1
kind: ALBInstance
metadata:
name: from-nginx
spec:
instance:
name: from-nginx
edition: Standard
zoneMappings:
- subnetId: subnet-xxx # 集群子网 ID，用于 ALB 实例在此可用区下的私网 IP 地址分配
- subnetId: subnet-yyy # 集群子网 ID，用于 ALB 实例在此可用区下的私网 IP 地址分配
listeners:
- port: 80
protocol: HTTP
- port: 443
protocol: HTTPS
certificateSource: cert_center # 监听器证书来源
certificateID: cert-**** # 指定域名绑定服务器证书

=== Ingresses 配置 ===

--- Ingress 1 --->
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
annotations:
ingress.vke.volcengine.com/loadbalancer-actions.service-demo: |-
[
{
"corsConfig": {
"allowHeaders": [
"CT"
],
"allowMethods": [
"GET"
],
"allowOrigin": [
"*"
],
"maxAge": 7777
},
"type": "Cors"
},
{
"rewriteConfig": {
"path": "/${2}"
},
"type": "Rewrite"
},
{
"redirectConfig": {
"httpCode": "308",
"port": 443,
"protocol": "HTTPS"
},
"type": "Redirect"
}
]
ingress.vke.volcengine.com/loadbalancer-backend-protocol: tcp
nginx.ingress.kubernetes.io/permanent-redirect: https://www.volcengine.com # 不支持自动转换的 Nginx Ingress Annotation
creationTimestamp: null
labels: {}
name: alb-nginx-ingress
namespace: default
spec:
ingressClassName: from-nginx
rules:
- host: example.com
http:
paths:
- backend:
service:
name: service-demo
port:
name: use-annotation
path: /
pathType: Prefix
tls: []

注意

当前不支持自动转换的 Nginx Ingress Annotation 在转换过程中会被保留，并在转换结果中展示。例如本例中的nginx.ingress.kubernetes.io/permanent-redirect: https://www.volcengine.com。请您在转换完成后确认转换后的 ALB Ingress 的配置是否符合预期，以避免转换后的配置与业务要求不符。

步骤二：创建 ALB Ingress

确认自动转换工具日志中生成的 YAML 文件无误后：

将日志中的 ALBInstance 配置内容复制并保存为alb-instance.yaml文件，并修改配置中的subnetId、certificateID等内容，要求与集群实际一致。

apiVersion: loadbalancer.vke.volcengine.com/v1beta1
kind: ALBInstance
metadata:
name: from-nginx
spec:
instance:
name: from-nginx
edition: Standard
zoneMappings:
- subnetId: subnet-iiv1ux50my*** # 集群子网 ID，用于 ALB 实例在此可用区下的私网 IP 地址分配
- subnetId: subnet-iiv23muxjo*** # 集群子网 ID，用于 ALB 实例在此可用区下的私网 IP 地址分配
listeners:
- port: 80
protocol: HTTP
- port: 443
protocol: HTTPS
certificateSource: cert_center # 监听器证书来源
certificateID: cert-bfe8f*** # 指定域名绑定服务器证书

执行以下命令，将 ALBInstance 配置下发到集群中。

kubectl apply -f alb-instance.yaml

将日志中的 Ingresses 配置内容复制并保存为alb-ingress.yaml文件。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
annotations:
ingress.vke.volcengine.com/loadbalancer-actions.service-demo: |-
[
{
"corsConfig": {
"allowHeaders": [
"CT"
],
"allowMethods": [
"GET"
],
"allowOrigin": [
"*"
],
"maxAge": 7777
},
"type": "Cors"
},
{
"rewriteConfig": {
"path": "/${2}"
},
"type": "Rewrite"
},
{
"redirectConfig": {
"httpCode": "308",
"port": 443,
"protocol": "HTTPS"
},
"type": "Redirect"
}
]
ingress.vke.volcengine.com/loadbalancer-backend-protocol: tcp
creationTimestamp: null
labels: {}
name: alb-nginx-ingress
namespace: default
spec:
ingressClassName: from-nginx
rules:
- host: example.com
http:
paths:
- backend:
service:
name: service-demo
port:
name: use-annotation
path: /
pathType: Prefix
tls: []

执行以下命令，将 ALB Ingress 配置下发到集群中。

kubectl apply -f alb-ingress.yaml

步骤三：流量切换

流量迁移前，假设您已将业务域名通过 A 记录解析的方式指向了 Nginx Ingress 的公网地址。此时，您可以在原 DNS 记录中新增 ALB 实例的 IP 地址，并开启负载均衡，然后通过调整 DNS 解析权重，逐步将访问原 Nginx Ingress 的流量切换至 ALB Ingress。

本文以火山引擎域名管理产品为例。

登录云解析 DNS 控制台。

在左侧导航栏选择公网域名管理。

在域名列表中单击目标域名名称，进入域名详情页面。

编辑目标域名的解析记录，开启负载均衡，并在记录值中添加 ALB 实例的 IP 地址，并配置权重。

完成配置后，确认 DNS 解析和业务是否正常。

DNS 查询：使用 dig 或 nslookup 命令查询域名。

dig example.com +short

预期结果如下，返回的 IP 地址列表中同时包含了 Nginx Ingress 和 ALB Ingress 的地址。

118.xxx.xxx.xxx
14.xxx.xxx.xxx

业务验证：验证并观察业务流量是否正常，观察是否存在错误码或异常。确认流量已被转发至 ALB Ingress，并无异常产生。

登录应用型负载均衡控制台。

在左侧导航栏中，选择实例管理。单击目标实例名称，进入实例详情页面。

选择监控信息页签，查看 ALB 实例的流量是否正常。

逐步调整 DNS 解析权重，直至全部流量均已被转发至 ALB Ingress。

步骤四：删除冗余资源

流量通过 ALB Ingress 正确转发，同时 Nginx Ingress 长连接全部处理完成后，您可以根据业务场景静默观察一段时间后释放冗余资源。

删除或禁用域名解析记录中的 Nginx Ingress 记录。待超过 DNS 缓存时间后，新的请求将全部切到 ALB 实例上。

使用容器服务集群云原生观测中的 Ingress 服务观测功能，持续监控 Nginx Ingress 上的流量，待流量归零后，即可删除集群中的 Nginx Ingress 资源。

其他说明

常见事件

listener is not exist in alb：表示 Ingress 请求的监听器（例如 80/HTTP, 443/HTTPS）未在关联的 ALB 实例上创建。请检查 ALBInstance 中 listeners 的定义。

none certificate found for host：表示 Ingress 为某个域名开启了 TLS，但 ALB 未能找到匹配该域名的证书。请检查证书来源（Secret、自动发现等）是否配置正确，以及证书本身是否有效。

不兼容注解和功能

在迁移过程中，如果您遇到一些 ALB Ingress 当前暂不支持的 Nginx 特有注解或功能，可以提交工单或联系技术支持。

回退流程

如果在流量迁移过程中或迁移后，发现 ALB 实例异常，可以进行流量迁移回退。回退是迁移的逆流程，其基本原理与迁移一致，即通过控制域名解析地址，由 ALB 实例 IP 变更为 Nginx Ingress 相关 IP 地址来实现无损回退。

将 DNS 中指向 ALB 的解析记录权重逐步下调至 0，或直接恢复为原 Nginx Ingress 对应解析记录。

持续观察业务访问成功率、错误码、时延和后端服务健康状态。

确认回退完成且业务恢复稳定后，再排查 ALB 配置问题。

最近更新时间：2026.06.08 11:21:42

这个页面对您有帮助吗？

有用

无用