1. 为什么需要Ingress-Nginx在Kubernetes集群中当你有多个服务需要对外暴露时传统做法是为每个Service创建LoadBalancer或NodePort。但这会带来几个明显问题每个服务都需要独立的外部IP或端口造成资源浪费缺乏统一的路由规则管理难以实现基于路径或域名的路由SSL/TLS证书需要在每个服务单独配置缺乏高级流量管理功能如A/B测试、灰度发布Ingress-Nginx正是为解决这些问题而生。它本质上是一个运行在Kubernetes集群中的Nginx但通过Ingress资源实现了声明式配置。我在生产环境中使用它已有三年最大的感受是它让将内部服务暴露给外部这件事从运维工作变成了开发配置。2. Ingress-Nginx核心架构解析2.1 组件构成一个完整的Ingress-Nginx部署包含以下核心组件Ingress Controller Pod主容器运行定制化的Nginx默认包含Lua脚本支持用于动态配置通过监听Kubernetes API实时更新配置Service资源通常使用LoadBalancer类型在云环境中会自动创建外部负载均衡器ConfigMap存储Nginx全局配置参数例如proxy-connect-timeout、keep-alive等2.2 请求处理流程当外部请求到达时完整的处理链路如下客户端DNS解析指向Ingress Service的外部IP云负载均衡器将请求转发到集群节点kube-proxy通过iptables/ipvs规则将请求路由到Ingress PodNginx根据Ingress规则匹配Host和Path请求被转发到对应Service的后端Pod关键点所有流量都会经过Ingress Pod这使其成为性能瓶颈和单点故障的风险点。我的经验是至少部署3个副本并使用PodAntiAffinity分散到不同节点。3. 从零开始部署Ingress-Nginx3.1 部署方式选择根据环境不同主要有三种部署方案环境类型推荐方式注意事项本地开发Docker Desktop内置无需额外配置云环境官方Helm Chart自动集成云厂商LB裸金属服务器NodePort 外部负载均衡器需手动配置外部LB健康检查以AWS EKS为例最稳妥的安装命令是helm upgrade --install ingress-nginx ingress-nginx \ --repo https://kubernetes.github.io/ingress-nginx \ --namespace ingress-nginx --create-namespace \ --set controller.service.annotations.service\.beta\.kubernetes\.io/aws-load-balancer-typenlb3.2 关键配置参数在values.yaml中必须检查的参数controller: replicaCount: 3 config: # 防止大文件上传失败 proxy-body-size: 20m # 保持与后端的长连接 upstream-keepalive-connections: 200 metrics: enabled: true # 开启Prometheus指标 service: annotations: # AWS特定配置 service.beta.kubernetes.io/aws-load-balancer-backend-protocol: tcp4. Ingress资源配置实战4.1 基础路由配置一个完整的Ingress示例apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: shop-ingress annotations: nginx.ingress.kubernetes.io/rewrite-target: /$2 spec: ingressClassName: nginx rules: - host: shop.example.com http: paths: - path: /api(/|$)(.*) pathType: Prefix backend: service: name: api-service port: number: 8000 - path: / backend: service: name: web-service port: number: 80这个配置实现了将shop.example.com/api路由到后端api-service其他路径路由到web-service使用rewrite-target清理路径去掉/api前缀4.2 高级功能实现4.2.1 金丝雀发布通过注解实现按权重分流annotations: nginx.ingress.kubernetes.io/canary: true nginx.ingress.kubernetes.io/canary-weight: 304.2.2 基于Header的路由annotations: nginx.ingress.kubernetes.io/canary-by-header: X-Env nginx.ingress.kubernetes.io/canary-by-header-value: staging4.2.3 限速配置annotations: nginx.ingress.kubernetes.io/limit-rps: 100 nginx.ingress.kubernetes.io/limit-burst: 2005. 生产环境运维要点5.1 监控与告警必须监控的关键指标Nginx指标nginx_ingress_controller_requests请求量nginx_ingress_controller_request_duration_seconds延迟业务指标5xx错误率建议告警阈值1%4xx错误率建议告警阈值5%示例Prometheus告警规则- alert: HighErrorRate expr: | sum(rate(nginx_ingress_controller_requests{status~5..}[1m])) by (ingress) / sum(rate(nginx_ingress_controller_requests[1m])) by (ingress) * 100 1 for: 5m5.2 性能调优根据负载测试结果调整以下参数worker_processes建议设置为节点CPU核数worker_connections默认1024高并发场景可提升到4096keepalive_timeout根据业务特点调整长连接场景适当延长调整方法是通过ConfigMapdata: worker-processes: 4 worker-connections: 4096 keep-alive: 75s6. 常见问题排查指南6.1 502 Bad Gateway排查步骤检查后端服务是否健康kubectl get endpoints service-name查看Nginx日志kubectl logs -n ingress-nginx pod-name | grep 502检查网络策略是否阻止流量6.2 413 Request Entity Too Large需要调整客户端最大body大小annotations: nginx.ingress.kubernetes.io/proxy-body-size: 20m6.3 路由规则不生效检查顺序Ingress资源是否关联了正确的IngressClass注解语法是否正确特别注意下划线和横线的区别是否存在多个Ingress Controller冲突7. 安全加固实践7.1 TLS最佳实践推荐配置spec: tls: - hosts: - shop.example.com secretName: tls-secret annotations: nginx.ingress.kubernetes.io/ssl-ciphers: ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256 nginx.ingress.kubernetes.io/ssl-protocols: TLSv1.2 TLSv1.37.2 防DDoS配置annotations: nginx.ingress.kubernetes.io/limit-connections: 100 nginx.ingress.kubernetes.io/limit-rps: 50 nginx.ingress.kubernetes.io/deny-common-exploits: true7.3 IP白名单annotations: nginx.ingress.kubernetes.io/whitelist-source-range: 192.168.0.0/24, 10.0.0.18. 进阶场景与替代方案8.1 多集群流量分发通过ExternalName Service实现跨集群路由apiVersion: v1 kind: Service metadata: name: cross-cluster-service spec: type: ExternalName externalName: another-cluster.example.com8.2 替代方案对比方案优点缺点Traefik更轻量配置简单功能较少Istio Ingress功能强大集成服务网格资源消耗大学习曲线陡峭ALB IngressAWS原生集成仅适用于AWS在日请求量超过100万的场景中我实测发现Ingress-Nginx比ALB Ingress节省约30%的成本同时提供更灵活的路由控制。但对于中小规模部署云厂商提供的托管Ingress可能是更简单的选择。 
长河君 · 2026/10/31 13:36:39 · 阅读 1.2k Kubernetes Ingress-Nginx 部署与优化指南
1. 为什么需要Ingress-Nginx在Kubernetes集群中当你有多个服务需要对外暴露时传统做法是为每个Service创建LoadBalancer或NodePort。但这会带来几个明显问题每个服务都需要独立的外部IP或端口造成资源浪费缺乏统一的路由规则管理难以实现基于路径或域名的路由SSL/TLS证书需要在每个服务单独配置缺乏高级流量管理功能如A/B测试、灰度发布Ingress-Nginx正是为解决这些问题而生。它本质上是一个运行在Kubernetes集群中的Nginx但通过Ingress资源实现了声明式配置。我在生产环境中使用它已有三年最大的感受是它让将内部服务暴露给外部这件事从运维工作变成了开发配置。2. Ingress-Nginx核心架构解析2.1 组件构成一个完整的Ingress-Nginx部署包含以下核心组件Ingress Controller Pod主容器运行定制化的Nginx默认包含Lua脚本支持用于动态配置通过监听Kubernetes API实时更新配置Service资源通常使用LoadBalancer类型在云环境中会自动创建外部负载均衡器ConfigMap存储Nginx全局配置参数例如proxy-connect-timeout、keep-alive等2.2 请求处理流程当外部请求到达时完整的处理链路如下客户端DNS解析指向Ingress Service的外部IP云负载均衡器将请求转发到集群节点kube-proxy通过iptables/ipvs规则将请求路由到Ingress PodNginx根据Ingress规则匹配Host和Path请求被转发到对应Service的后端Pod关键点所有流量都会经过Ingress Pod这使其成为性能瓶颈和单点故障的风险点。我的经验是至少部署3个副本并使用PodAntiAffinity分散到不同节点。3. 从零开始部署Ingress-Nginx3.1 部署方式选择根据环境不同主要有三种部署方案环境类型推荐方式注意事项本地开发Docker Desktop内置无需额外配置云环境官方Helm Chart自动集成云厂商LB裸金属服务器NodePort 外部负载均衡器需手动配置外部LB健康检查以AWS EKS为例最稳妥的安装命令是helm upgrade --install ingress-nginx ingress-nginx \ --repo https://kubernetes.github.io/ingress-nginx \ --namespace ingress-nginx --create-namespace \ --set controller.service.annotations.service\.beta\.kubernetes\.io/aws-load-balancer-typenlb3.2 关键配置参数在values.yaml中必须检查的参数controller: replicaCount: 3 config: # 防止大文件上传失败 proxy-body-size: 20m # 保持与后端的长连接 upstream-keepalive-connections: 200 metrics: enabled: true # 开启Prometheus指标 service: annotations: # AWS特定配置 service.beta.kubernetes.io/aws-load-balancer-backend-protocol: tcp4. Ingress资源配置实战4.1 基础路由配置一个完整的Ingress示例apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: shop-ingress annotations: nginx.ingress.kubernetes.io/rewrite-target: /$2 spec: ingressClassName: nginx rules: - host: shop.example.com http: paths: - path: /api(/|$)(.*) pathType: Prefix backend: service: name: api-service port: number: 8000 - path: / backend: service: name: web-service port: number: 80这个配置实现了将shop.example.com/api路由到后端api-service其他路径路由到web-service使用rewrite-target清理路径去掉/api前缀4.2 高级功能实现4.2.1 金丝雀发布通过注解实现按权重分流annotations: nginx.ingress.kubernetes.io/canary: true nginx.ingress.kubernetes.io/canary-weight: 304.2.2 基于Header的路由annotations: nginx.ingress.kubernetes.io/canary-by-header: X-Env nginx.ingress.kubernetes.io/canary-by-header-value: staging4.2.3 限速配置annotations: nginx.ingress.kubernetes.io/limit-rps: 100 nginx.ingress.kubernetes.io/limit-burst: 2005. 生产环境运维要点5.1 监控与告警必须监控的关键指标Nginx指标nginx_ingress_controller_requests请求量nginx_ingress_controller_request_duration_seconds延迟业务指标5xx错误率建议告警阈值1%4xx错误率建议告警阈值5%示例Prometheus告警规则- alert: HighErrorRate expr: | sum(rate(nginx_ingress_controller_requests{status~5..}[1m])) by (ingress) / sum(rate(nginx_ingress_controller_requests[1m])) by (ingress) * 100 1 for: 5m5.2 性能调优根据负载测试结果调整以下参数worker_processes建议设置为节点CPU核数worker_connections默认1024高并发场景可提升到4096keepalive_timeout根据业务特点调整长连接场景适当延长调整方法是通过ConfigMapdata: worker-processes: 4 worker-connections: 4096 keep-alive: 75s6. 常见问题排查指南6.1 502 Bad Gateway排查步骤检查后端服务是否健康kubectl get endpoints service-name查看Nginx日志kubectl logs -n ingress-nginx pod-name | grep 502检查网络策略是否阻止流量6.2 413 Request Entity Too Large需要调整客户端最大body大小annotations: nginx.ingress.kubernetes.io/proxy-body-size: 20m6.3 路由规则不生效检查顺序Ingress资源是否关联了正确的IngressClass注解语法是否正确特别注意下划线和横线的区别是否存在多个Ingress Controller冲突7. 安全加固实践7.1 TLS最佳实践推荐配置spec: tls: - hosts: - shop.example.com secretName: tls-secret annotations: nginx.ingress.kubernetes.io/ssl-ciphers: ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256 nginx.ingress.kubernetes.io/ssl-protocols: TLSv1.2 TLSv1.37.2 防DDoS配置annotations: nginx.ingress.kubernetes.io/limit-connections: 100 nginx.ingress.kubernetes.io/limit-rps: 50 nginx.ingress.kubernetes.io/deny-common-exploits: true7.3 IP白名单annotations: nginx.ingress.kubernetes.io/whitelist-source-range: 192.168.0.0/24, 10.0.0.18. 进阶场景与替代方案8.1 多集群流量分发通过ExternalName Service实现跨集群路由apiVersion: v1 kind: Service metadata: name: cross-cluster-service spec: type: ExternalName externalName: another-cluster.example.com8.2 替代方案对比方案优点缺点Traefik更轻量配置简单功能较少Istio Ingress功能强大集成服务网格资源消耗大学习曲线陡峭ALB IngressAWS原生集成仅适用于AWS在日请求量超过100万的场景中我实测发现Ingress-Nginx比ALB Ingress节省约30%的成本同时提供更灵活的路由控制。但对于中小规模部署云厂商提供的托管Ingress可能是更简单的选择。