Nginx Ingress作为ACK托管集群中的流量入口网关,通过灵活的路由规则将外部请求精确转发至内部服务。配合使用HTTPS安全加密、灰度发布、通过注解自定义配置等能力,Nginx Ingress可以满足安全、高可用、可扩展的七层(L7)网络访问需求。
-
因传统型负载均衡CLB按规格计费停止售卖,容器服务 Kubernetes 版自2025年09月11日起,通过控制台新建负载均衡类型的Service与新安装Nginx Ingress Controller时,将默认使用NLB实例。同时,通过控制台创建CLB实例类型的Service转为白名单开放。对于仍需创建CLB的场景,将默认使用按使用量计费模式。更多详细内容,请参见【产品变更】关于新建Service与Nginx Ingress Controller默认负载均衡类型与计费方式变更的公告。
-
由于Ingress NGINX开源项目于2026年3月后停止维护更新,容器服务 Kubernetes 版 将停止Nginx Ingress Controller组件维护,请充分了解使用风险。更多详细内容,请参见【产品公告】关于停止维护Nginx Ingress Controller组件的公告。
注意事项
-
请勿删除Nginx Ingress Controller默认使用的服务。安装组件后将默认创建
kube-system命名空间下的nginx-ingress-lb服务,将其删除将会导致组件运行不稳定,严重时会出现崩溃。 -
请通过组件管理或者OpenAPI方式配置组件的自定义参数。通过其他渠道修改组件配置可能会导致组件功能异常,且会影响组件后续的升级过程。
-
请优先使用Nginx Ingress配置词典来实现所需功能。若使用Snippet或Lua代码等方式对组件进行额外配置,所出现的与预期功能不符等问题无法得到技术支持。
-
请及时升级Nginx Ingress Controller组件,以避免上游社区版组件的Bug或漏洞导致业务受损。
安装Nginx Ingress Controller组件
创建示例应用
示例应用将部署两个名称分别为coffee和tea的无状态工作负载(Deployment)以及对应的coffee-svc和tea-svc服务(Service)。
控制台
|
1. 创建资源
|
|
2. 查看创建结果 在Yaml 资源创建结果弹窗中,单击资源右侧操作列中的查看,确认创建结果。 |
kubectl
-
创建test-deployment-service.yaml文件。
-
创建Deployment和Service。
kubectl apply -f test-deployment-service.yaml -
查看
coffee和tea的创建进度。kubectl get deployment coffee tea预期输出:
NAME READY UP-TO-DATE AVAILABLE AGE coffee 2/2 2 2 14m tea 2/2 2 2 14m -
查看
coffee-svc和tea-svc服务。kubectl get service coffee-svc tea-svc预期输出:
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE coffee-svc ClusterIP 192.168.xxx.xxx <none> 80/TCP 15m tea-svc ClusterIP 192.168.xxx.xxx <none> 80/TCP 15m
创建Nginx Ingress
以下示例的规则(rules)中的域名(host)以test-nginx-ingress.com为例,请替换为实际注册域名;规则中的路径映射(paths)以创建示例应用为例,请按实际情况修改。
控制台
|
1. 创建资源
|
|
2. 获取访问地址 创建完成后,等待约1分钟,然后单击右上角刷新按钮。若端点显示对应的弹性公网IP(即关联公网CLB实例的服务地址),说明Nginx Ingress已创建成功。
若长时间未更新端点信息,可单击路由名称,进入事件页签,进行异常排查。 |
kubectl
-
创建test-ingress.yaml文件。
apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: test-nginx-ingress namespace: default spec: ingressClassName: nginx rules: - host: test-nginx-ingress.com # 请替换为实际注册域名 http: paths: - path: /coffee backend: service: name: coffee-svc port: number: 80 pathType: ImplementationSpecific - path: /tea backend: service: name: tea-svc port: number: 80 pathType: ImplementationSpecific - host: www.test-nginx-ingress.com # 请替换为实际注册域名 http: paths: - path: /coffee backend: service: name: coffee-svc port: number: 80 pathType: ImplementationSpecific - path: /tea backend: service: name: tea-svc port: number: 80 pathType: ImplementationSpecific重点参数说明:
-
name:Ingress的名称。本示例为test-nginx-ingress。 -
host:指定服务访问域名。本示例为test-nginx-ingress.com,请替换为实际注册域名。 -
path:指定访问的URL路径。CLB将流量转发到backend之前,所有的入站请求都要先匹配host和path。本示例为/coffee和/tea。 -
backend:由服务名称和服务端口组成。-
服务名称:Ingress转发的backend服务名称。本示例为
coffee-svc和tea-svc。 -
服务端口:服务暴露的端口。本示例为
80。
-
-
-
创建Ingress。
kubectl apply -f test-ingress.yaml -
查看Ingress并获取弹性公网IP,如
8.xxx.xxx.117。kubectl get ingress预期输出:
NAME CLASS HOSTS ADDRESS PORTS AGE test-nginx-ingress nginx test-nginx-ingress.com,www.test-nginx-ingress.com 8.xxx.xxx.117 80 2m39s -
请使用实际获取的弹性公网IP,验证Nginx Ingress是否生效。
curl http://8.xxx.xxx.117/coffee -H "Host: test-nginx-ingress.com"预期输出:
... <title>Hello World</title> ... <p><span>Server address:</span> <span>10.xxx.xxx.19:80</span></p> <p><span>Server name:</span> <span>coffee-96d4bc87-l29dh</span></p> <p class="smaller"><span>Date:</span> <span>08/Aug/2025:02:21:02 +0000</span></p> <p class="smaller"><span>URI:</span> <span>/coffee</span></p> ... <div id="footer"> <div id="center" align="center"> Request ID: 42e2d73c85b16b55b6ab52deb7d995d4<br/> © NGINX, Inc. 2018 </div> </div> ...
配置域名解析
注册域名,并完成ICP备案。添加域名的操作仅适用于非阿里云注册域名。若通过阿里云域名注册购买的域名,会自动同步到DNS公网权威解析列表,可直接添加解析记录。
|
1. 添加域名
|
|
2. 添加解析记录
更多详细内容,请参见添加网站解析。 |
|
3. 验证域名和路径生效 在浏览器中访问
还可参考解析生效测试方法进行确认,如发现解析不生效,可参考解析不生效问题快速排查。 |
配置HTTPS安全加密(TLS配置)
购买正式证书或个人测试证书,并完成申请证书,确认待使用的证书处于已签发状态。然后参考以下步骤下载证书并添加TLS配置,从而实现通过HTTPS加密通信的方式访问域名。
控制台
|
1. 下载证书
更多详细内容,请参见下载SSL证书。 |
|
2. 创建保密字典
|
|
3. 添加TLS配置
|
|
4. 验证HTTPS访问 在浏览器中访问
|
kubectl
-
登录数字证书管理服务控制台。在左侧导航栏,选择。
-
在正式证书或个人测试证书(原免费证书)页签,选中需要下载的证书,在证书列表左下方单击下载。
-
在弹出的对话框,选择Nginx服务器类型下载证书包并解压。
-
使用已下载的证书文件(.pem)和证书私钥文件(.key)创建保密字典。
kubectl create secret tls nginx-ingress-tls --cert test-nginx-ingress.com.pem --key test-nginx-ingress.com.key -n default -
为
test-nginx-ingress路由添加TLS配置。请将命令中的test-nginx-ingress.com替换为实际注册域名。kubectl patch ingress test-nginx-ingress -p '{"spec":{"tls":[{"hosts":["test-nginx-ingress.com"],"secretName":"nginx-ingress-tls"}]}}' -
请使用实际的弹性公网IP,验证通过HTTPS加密通信的方式访问域名及业务路径生效。
curl -v -k https://8.xxx.xxx.117/coffee -H "Host: test-nginx-ingress.com"-
参数说明:
-
-v:显示详细的通信过程,包括TLS握手信息等。 -
-k(或 --insecure):若使用自签名证书可以忽略证书验证。
-
-
预期输出:
... * Trying 8.xxx.xxx.117:443... * Connected to 8.xxx.xxx.117 (8.xxx.xxx.117) port 443 * ALPN: curl offers h2,http/1.1 * (304) (OUT), TLS handshake, Client hello (1): * (304) (IN), TLS handshake, Server hello (2): * (304) (IN), TLS handshake, Unknown (8): * (304) (IN), TLS handshake, Certificate (11): * (304) (IN), TLS handshake, CERT verify (15): * (304) (IN), TLS handshake, Finished (20): * (304) (OUT), TLS handshake, Finished (20): ... <title>Hello World</title> ... <p><span>Server address:</span> <span>10.xxx.xxx.159:80</span></p> <p><span>Server name:</span> <span>coffee-96d4bc87-6cstv</span></p> <p class="smaller"><span>Date:</span> <span>14/Aug/2025:09:27:42 +0000</span></p> <p class="smaller"><span>URI:</span> <span>/coffee</span></p> ... <div id="footer"> <div id="center" align="center"> Request ID: fee5fe107106748a35d99a2dbbbc6652<br/> © NGINX, Inc. 2018 </div> </div> ...
-
更多配置
灰度发布
当对服务进行版本更新升级时,需要使用到滚动升级、分批暂停发布、蓝绿发布以及灰度发布等发布方式。详细操作,请参见通过Nginx Ingress实现灰度发布和蓝绿发布。
后端服务协议
指定后端服务的协议,设置后会添加注解nginx.ingress.kubernetes.io/backend-protocol。支持HTTP、HTTPS、gRPC、gRPCS四种服务协议。配置示例,请参见为Nginx Ingress配置gRPC服务。
重写路径
当您在使用Nginx Ingress Controller的时候,Nginx会将路径完整转发到后端(如,从Ingress访问的/service1/api路径会直接转发到后端Pod的/service1/api路径)。如果您后端的服务路径为/api,则会出现路径错误,导致404的情况。该情况下,您可以通过配置nginx.ingress.kubernetes.io/rewrite-target的方式,来将路径重写至需要的目录。
详细操作,请参见配置URL重定向的路由服务。
添加注解
Nginx Ingress支持通过添加注解(Annotations)来启用更多功能。详细操作,请参见Nginx Ingress配置词典和Nginx Ingress高级用法。
可观测性
在创建集群时启用日志服务,然后在阿里云日志服务SLS查看Nginx Ingress的访问日志分析报表和监控Nginx Ingress实时状态。相关内容,请参见Nginx Ingress访问日志分析与监控。
高负载场景
关于如何提升Nginx Ingress Controller高负载场景下的性能和稳定性,请参见配置高负载场景的Nginx Ingress Controller和Nginx Ingress Controller使用建议。
常见问题
为什么从集群内访问集群LoadBalancer的外部地址不通?
如何支持客户端Header或者Cookie过大的请求?
Nginx Ingress如何配置跨域?
如何配置透传客户端IP?
相关文档
-
关于Nginx Ingress Controller组件的版本和变更记录,请参见Nginx Ingress Controller组件。
-
关于更多常见问题和异常排查方法,请参见Nginx Ingress FAQ和Nginx Ingress异常问题排查。


