Ingress NGINX Controller 快速入门基于 Kubernetes Ingress 与 ConfigMap 的架构解析与部署实战【免费下载链接】ingress-nginxIngress NGINX Controller for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/in/ingress-nginx本篇技术指南以docs/index.md为骨架系统介绍 Ingress NGINX Controller 的核心架构围绕 Kubernetes Ingress 资源、以 ConfigMap 承载控制器配置、当前项目的退役状态及其对存量部署的影响并完整展开快速开始、本地/在线测试、云厂商与裸金属环境部署等实战内容。读完本文你将掌握通过 Helm 与 YAML 清单两种方式部署控制器、验证运行状态、创建并调试第一个 Ingress 的完整能力。项目退役状态部署前必须了解的前提截至当前仓库状态Ingress NGINX 项目已进入退役Retirement阶段官方公告的核心结论如下尽力维护将持续到 2026 年 3 月此后将不再发布新版本、不再修复 Bug也不会针对新发现的安全漏洞提供更新已部署的 Ingress NGINX 实例不会被破坏现有 Helm Chart、容器镜像等项目产物仍可获取使用。这意味着如果你已经依赖 Ingress NGINX现有生产环境可以继续运行但需要提前规划替代方案Kubernetes 官方建议评估 Gateway API 实现如果尚未使用则不建议在此时新建部署依赖。本文以下内容面向存量维护者与需要理解其工作机制的读者完整文档仍保留在本仓库的 docs 目录。架构概述Ingress 资源 ConfigMap 配置从docs/index.md的 Overview 可知Ingress NGINX Controller 的核心设计围绕两个要素Kubernetes Ingress 资源控制器监听集群中的 Ingress 对象依据其规则host、path、backend生成 NGINX 反向代理配置将外部流量路由到集群内 Service 与 Pod。ConfigMap控制器使用一个 ConfigMap 保存全局配置NGINX 各项参数、超时、日志格式等这是它与传统 NGINX 配置文件的核心差异——配置以 Kubernetes 原生对象的形式存在随集群 API 一起被 watch 与热更新。从源码可以印证这一设计控制器的主配置结构体Configuration定义在 internal/ingress/controller/controller.go其中包含ConfigMapName、TCPConfigMapName、UDPConfigMapName等字段控制器通过 store 包 中的本地存储监听 ConfigMap 变化并在 controller.go 中按名称解析、加载 TCP/UDP 流式服务定义。换言之Ingress 规则定义路由什么ConfigMap 定义如何路由二者共同驱动 NGINX 配置生成。快速开始两种安装方式docs/deploy/index.md安装指南提供了两条官方安装路径大多数集群开箱即用、无需额外配置。方式一使用 Helm 安装推荐helm upgrade --install ingress-nginx ingress-nginx \ --repo https://kubernetes.github.io/ingress-nginx \ --namespace ingress-nginx --create-namespace该命令会把控制器安装到ingress-nginx命名空间不存在则自动创建且具备幂等性未安装则安装已安装则升级。本仓库的 Chart 定义在 charts/ingress-nginx/Chart.yaml当前appVersion为 1.15.1、Chart 版本为 4.15.1kubeVersion要求1.21.0-0。安装前查看可配置的全部 valueshelm show values ingress-nginx --repo https://kubernetes.github.io/ingress-nginx⚠️注意Helm Chart 的默认 values 是通用开箱即用配置并未针对任何云厂商做适配。云厂商 LB 相关的注解需要自行定制。方式二使用 YAML 清单kubectl apply不装 Helm 或偏好清单时可以应用由helm template生成的静态清单资源构成与 Helm 安装几乎一致kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.15.1/deploy/static/provider/cloud/deploy.yaml该清单对应的仓库源文件位于 deploy/static/provider/cloud/deploy.yaml也可下载到本地后执行kubectl apply -f deploy.yaml。若运行 Kubernetes 1.18 及更早版本请先阅读下文旧版本兼容一节因为 API 弃用可能导致默认清单无法应用。云厂商 LoadBalancer 注解示例以 AWS 为例当使用--type LoadBalancer的 Service 时需按云厂商定制注解。官方在安装指南中给出了一组 AWS NLB 推荐注解健康检查注解对 target-type IP 是必需项annotations: service.beta.kubernetes.io/aws-load-balancer-target-group-attributes: deregistration_delay.timeout_seconds270 service.beta.kubernetes.io/aws-load-balancer-nlb-target-type: ip service.beta.kubernetes.io/aws-load-balancer-healthcheck-path: /healthz service.beta.kubernetes.io/aws-load-balancer-healthcheck-port: 10254 service.beta.kubernetes.io/aws-load-balancer-healthcheck-protocol: http service.beta.kubernetes.io/aws-load-balancer-healthcheck-success-codes: 200-299 service.beta.kubernetes.io/aws-load-balancer-scheme: internet-facing service.beta.kubernetes.io/aws-load-balancer-backend-protocol: tcp service.beta.kubernetes.io/aws-load-balancer-cross-zone-load-balancing-enabled: true service.beta.kubernetes.io/aws-load-balancer-type: nlb service.beta.kubernetes.io/aws-load-balancer-manage-backend-security-group-rules: true service.beta.kubernetes.io/aws-load-balancer-access-log-enabled: true service.beta.kubernetes.io/aws-load-balancer-security-groups: sg-something1 sg-something2 service.beta.kubernetes.io/aws-load-balancer-access-log-s3-bucket-name: somebucket service.beta.kubernetes.io/aws-load-balancer-access-log-s3-bucket-prefix: ingress-nginx service.beta.kubernetes.io/aws-load-balancer-access-log-emit-interval: 5注意其中的健康检查端口10254正是控制器 healthz 端点的默认端口见下文 CLI 参数表。防火墙与预检安装后需要放通以下端口8443/tcp用于 Ingress NGINX 的准入控制器admission controller需要在所有运行 Kubernetes 节点的宿主机之间开放80/tcpHTTP与 443/tcpHTTPS对外公开指向应用 DNS 所解析的节点。检查实际使用的端口可查看kubectl -n ingress-nginx get pod -o yaml验证 Pod 是否全部就绪kubectl get pods --namespaceingress-nginx等待控制器 Pod 变为 ready超时 120skubectl wait --namespace ingress-nginx \ --forconditionready pod \ --selectorapp.kubernetes.io/componentcontroller \ --timeout120s本地测试port-forward 快速验证创建示例后端 Deployment 与 Servicekubectl create deployment demo --imagehttpd --port80 kubectl expose deployment demo创建使用nginxIngressClass 的 Ingress主机名映射到localhostkubectl create ingress demo-localhost --classnginx \ --ruledemo.localdev.me/*demo:80将本地 8080 端口转发到控制器的 Service 80 端口kubectl port-forward --namespaceingress-nginx service/ingress-nginx-controller 8080:80说明port-forward把本地 TCP 8080 端口映射到控制器 Service 的 80 端口从而在本地模拟来自集群外部的请求。它仅用于演示不适用于生产环境生产场景请使用 LoadBalancer 或下文的环境特定方案。最后用curl --resolve绕过 DNS 直接访问curl --resolve demo.localdev.me:8080:127.0.0.1 http://demo.localdev.me:8080应返回包含It works!的 HTML 页面。在线测试LoadBalancer 与真实域名如果集群支持LoadBalancer类型 Service控制器会被分配外部 IP 或 FQDNkubectl get service ingress-nginx-controller --namespaceingress-nginx查看EXTERNAL-IP字段若为pending说明集群无法供给负载均衡器通常是不支持LoadBalancer类型。为外部 IP 配置 DNS 记录后创建 Ingresskubectl create ingress demo --classnginx \ --rulewww.demo.io/*demo:80该命令等价于kubectl create ingress demo --classnginx \ --rule www.demo.io/demo:80之后访问http://www.demo.io/即可看到 It works! 页面——一个由 Kubernetes 集群托管的公网网站就此诞生。环境特定部署本地开发集群环境命令minikubeminikube addons enable ingressMicroK8smicrok8s enable ingressDocker Desktop在 Docker 设置中启用 Kuberneteskubectl get nodes应显示名为docker-desktop的节点然后按上文快速开始安装多数情况下控制器会获得localhost的 EXTERNAL-IP否则回退到 port-forward 方案Rancher Desktop底层为 K3s默认 Ingress 控制器是 Traefik需在 Preference Kubernetes 中禁用 Traefik 后再按快速开始安装云环境通用优化若云厂商负载均衡器对后端做主动健康检查多数如此可将控制器 Service 的externalTrafficPolicy改为Local以省去一跳转发helm upgrade --install ingress-nginx ingress-nginx \ --repo https://kubernetes.github.io/ingress-nginx \ --namespace ingress-nginx --create-namespace \ --set controller.service.externalTrafficPolicyLocal若负载均衡器支持 PROXY 协议可让控制器看到客户端真实 IP否则只会看到上游 LB 的 IP。这需要两侧同时开启控制器侧--set controller.config.use-proxy-protocoltrue云厂商 LB 侧开启 PROXY protocol。各云厂商的专用清单源文件可在仓库 deploy/static/provider/ 下找到含 aws、do、scw、exoscale、oracle、cloud、baremetal、kind 等子目录。几个要点AWS使用 NLB 暴露控制器。如需在 LB 侧终结 TLS下载nlb-with-tls-termination模板修改其中的proxy-real-ip-cidr改为集群 VPC CIDR与 ACM 证书 ARN 后再kubectl apply -f deploy.yaml。AWS NLB 的 TCP 空闲超时默认 350s可调 60–6000s务必保证 NGINXkeepalive_timeout默认 75s小于该值。GCE/GKE默认 GKE LoadBalancer不支持 PROXY 协议开启use-proxy-protocol无效私有集群还需放行主节点到工作节点 8443/tcp 的防火墙规则。Azure应用provider/cloud下的清单即可。Digital Ocean默认只配置了service.beta.kubernetes.io/do-loadbalancer-enable-proxy-protocol: true一个注解若要让 DO LoadBalancer 图表显示数据需要补充其他注解。Scaleway / Exoscale / Oracle / OVHcloud分别有专用清单或 Helm 安装方式详见 docs/deploy/index.md。裸金属集群裸金属或自建 VM 集群没有按需供给的云负载均衡器官方提供了四种方案详见 docs/deploy/baremetal.mdMetalLB纯软件方案为集群提供 LoadBalancer Service 实现Layer 2 模式下由单节点吸引全部流量需为IPAddressPool分配一段专用 IP不可复用节点 IP 或 DHCP 地址。NodePort Service最简单通过kube-proxy在所有节点暴露同一未特权端口默认 30000–32767。客户端访问需携带 NodePort如http://myapp.example.com:30100由于默认做源地址转换若要保留源 IP 需设置externalTrafficPolicy: Local注意这会丢弃发往未运行控制器的节点的包。不推荐通过修改--service-node-port-range把 NodePort 压到 80/443可能引发端口冲突等意外问题。hostNetwork控制器 Pod 直接绑定节点网络接口可独占 80/443每个节点只能调度一个控制器 Pod端口互斥建议以 DaemonSet 部署。注意hostNetwork: true的 Pod 默认不使用集群 DNS需设置dnsPolicy: ClusterFirstWithHostNet且无 Service 可发布需启用--report-node-internal-ip-address标志让 Ingress 状态写入节点内网 IP。自建边缘Self-provisioned edge由硬件或软件边缘组件如 HAProxy在集群外提供公网入口把 80/443 流量转发到节点上的 NodePort适合节点无公网 IP 的私有集群。常用运维要点Miscellaneous查看控制器版本POD_NAMESPACEingress-nginx POD_NAME$(kubectl get pods -n $POD_NAMESPACE -l app.kubernetes.io/nameingress-nginx --field-selectorstatus.phaseRunning -o name) kubectl exec $POD_NAME -n $POD_NAMESPACE -- /nginx-ingress-controller --version限制监听范围Scope默认控制器 watch 所有命名空间的 Ingress。可通过--watch-namespace标志或 Helm valuecontroller.scope限定到单个命名空间。注意default-ssl-certificate所引用的 Secret 必须同时存在于被 watch 的命名空间中。Webhook 网络可达性控制器通过准入 Webhook校验 Ingress 定义。务必保证 API Server 到ingress-nginx-controller-admissionService 的链路不被 NetworkPolicy 或防火墙阻断否则创建/更新 Ingress 会被拦截。证书生成延迟控制器首次启动时两个 Job 会为准入 Webhook 生成 SSL 证书导致最长约两分钟的初始化延迟。等待其就绪后再执行后续命令kubectl wait --namespace ingress-nginx \ --forconditionready pod \ --selectorapp.kubernetes.io/componentcontroller \ --timeout120sKubernetes 1.19 之前的兼容性Ingress API 经历了extensions/v1beta1→networking.k8s.io/v1beta1→networking.k8s.io/v1的演进兼容矩阵如下Kubernetes 版本支持的 Ingress API 1.19仅v1beta11.19 – 1.21v1beta1与v1均支持≥ 1.22仅v1控制器侧v1.0 之前仅支持v1beta1v1.0 及以后仅支持v1。因此 Kubernetes 1.19 可直接使用最新控制器1.18 及更早需使用 0.X 版本如 0.49。Helm Chart 在第 4 版切换到 Chart 版本 1若运行 Kubernetes 1.19 及更早应使用 3.X 版 Charthelm install时加--version4。源码视角关键 CLI 参数与配置入口docs/index.md强调 ConfigMap 承载控制器配置而控制器的完整可调参数以命令行参数形式暴露详见 docs/user-guide/cli-arguments.md它们被写进 Deployment 的容器 spec 中。以下是与日常运维强相关的核心参数参数作用默认值--configmap承载全局配置的 ConfigMap 名称与上文架构对应--controller-class本控制器满足的 IngressClass Controller 值Ingress 通过ingressClassName字段匹配--ingress-class满足的 Ingress class 名称默认nginx未设置或为默认值时也会处理 class 为空或为nginx的 Ingress--watch-namespace限制 watch 的命名空间空则 watch 全部--default-backend-servicecatch-all 默认后端格式namespace/name--default-ssl-certificate默认 HTTPS catch-all 服务器所用证书 Secret格式namespace/name--healthz-porthealthz 端点端口默认 10254即云厂商健康检查注解使用的端口--health-check-path健康检查路径默认/healthz--http-port/--https-port服务 HTTP/HTTPS 的端口默认 80 / 443--tcp-services-configmap/--udp-services-configmap定义 TCP/UDP 流式服务暴露的 ConfigMap值格式namespace/name:port--publish-service前置控制器的 Servicenamespace/name与--update-status配合把其端点地址镜像到 Ingress 的 load-balancer 状态--publish-status-address自定义写入 Ingress 状态的地址列表逗号分隔--report-node-internal-ip-address将 Ingress 状态设置为节点内网 IP裸金属 hostNetwork 场景常用--enable-ssl-passthrough启用 SSL Passthrough默认 false--validating-webhook启动准入校验 Webhook 的监听地址host:port--annotations-prefix注解前缀默认nginx.ingress.kubernetes.io--sync-period/--sync-rate-limit本地对象存储强制重载周期默认关闭/ 同步频率上限默认 0.3--enable-metrics开启 NGINX 指标采集默认 false这些参数对应源码中的Configuration结构体internal/ingress/controller/controller.go与 internal/ingress/controller/config/config.go而 TCP/UDP 流式服务的加载逻辑按 ConfigMap 名称解析namespace/name:port引用可在 controller.go 中看到实际实现。结语Ingress NGINX Controller 以 Kubernetes Ingress 资源为路由事实源、以 ConfigMap 为全局配置载体配合准入 Webhook、健康检查与状态上报机制构成了一个声明式的七层入口控制器。尽管项目已进入退役阶段理解其架构与部署方式对于存量集群的日常维护、排障以及向 Gateway API 方案的迁移规划仍有直接价值。更深入的主题ConfigMap 全部可配项、注解、监控、故障排查可继续阅读仓库 docs 目录 下的 user-guide 与 troubleshooting.md。【免费下载链接】ingress-nginxIngress NGINX Controller for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/in/ingress-nginx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Ingress NGINX Controller 快速入门：基于 Kubernetes Ingress 与 ConfigMap 的架构解析与部署实战
Ingress NGINX Controller 快速入门基于 Kubernetes Ingress 与 ConfigMap 的架构解析与部署实战【免费下载链接】ingress-nginxIngress NGINX Controller for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/in/ingress-nginx本篇技术指南以docs/index.md为骨架系统介绍 Ingress NGINX Controller 的核心架构围绕 Kubernetes Ingress 资源、以 ConfigMap 承载控制器配置、当前项目的退役状态及其对存量部署的影响并完整展开快速开始、本地/在线测试、云厂商与裸金属环境部署等实战内容。读完本文你将掌握通过 Helm 与 YAML 清单两种方式部署控制器、验证运行状态、创建并调试第一个 Ingress 的完整能力。项目退役状态部署前必须了解的前提截至当前仓库状态Ingress NGINX 项目已进入退役Retirement阶段官方公告的核心结论如下尽力维护将持续到 2026 年 3 月此后将不再发布新版本、不再修复 Bug也不会针对新发现的安全漏洞提供更新已部署的 Ingress NGINX 实例不会被破坏现有 Helm Chart、容器镜像等项目产物仍可获取使用。这意味着如果你已经依赖 Ingress NGINX现有生产环境可以继续运行但需要提前规划替代方案Kubernetes 官方建议评估 Gateway API 实现如果尚未使用则不建议在此时新建部署依赖。本文以下内容面向存量维护者与需要理解其工作机制的读者完整文档仍保留在本仓库的 docs 目录。架构概述Ingress 资源 ConfigMap 配置从docs/index.md的 Overview 可知Ingress NGINX Controller 的核心设计围绕两个要素Kubernetes Ingress 资源控制器监听集群中的 Ingress 对象依据其规则host、path、backend生成 NGINX 反向代理配置将外部流量路由到集群内 Service 与 Pod。ConfigMap控制器使用一个 ConfigMap 保存全局配置NGINX 各项参数、超时、日志格式等这是它与传统 NGINX 配置文件的核心差异——配置以 Kubernetes 原生对象的形式存在随集群 API 一起被 watch 与热更新。从源码可以印证这一设计控制器的主配置结构体Configuration定义在 internal/ingress/controller/controller.go其中包含ConfigMapName、TCPConfigMapName、UDPConfigMapName等字段控制器通过 store 包 中的本地存储监听 ConfigMap 变化并在 controller.go 中按名称解析、加载 TCP/UDP 流式服务定义。换言之Ingress 规则定义路由什么ConfigMap 定义如何路由二者共同驱动 NGINX 配置生成。快速开始两种安装方式docs/deploy/index.md安装指南提供了两条官方安装路径大多数集群开箱即用、无需额外配置。方式一使用 Helm 安装推荐helm upgrade --install ingress-nginx ingress-nginx \ --repo https://kubernetes.github.io/ingress-nginx \ --namespace ingress-nginx --create-namespace该命令会把控制器安装到ingress-nginx命名空间不存在则自动创建且具备幂等性未安装则安装已安装则升级。本仓库的 Chart 定义在 charts/ingress-nginx/Chart.yaml当前appVersion为 1.15.1、Chart 版本为 4.15.1kubeVersion要求1.21.0-0。安装前查看可配置的全部 valueshelm show values ingress-nginx --repo https://kubernetes.github.io/ingress-nginx⚠️注意Helm Chart 的默认 values 是通用开箱即用配置并未针对任何云厂商做适配。云厂商 LB 相关的注解需要自行定制。方式二使用 YAML 清单kubectl apply不装 Helm 或偏好清单时可以应用由helm template生成的静态清单资源构成与 Helm 安装几乎一致kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.15.1/deploy/static/provider/cloud/deploy.yaml该清单对应的仓库源文件位于 deploy/static/provider/cloud/deploy.yaml也可下载到本地后执行kubectl apply -f deploy.yaml。若运行 Kubernetes 1.18 及更早版本请先阅读下文旧版本兼容一节因为 API 弃用可能导致默认清单无法应用。云厂商 LoadBalancer 注解示例以 AWS 为例当使用--type LoadBalancer的 Service 时需按云厂商定制注解。官方在安装指南中给出了一组 AWS NLB 推荐注解健康检查注解对 target-type IP 是必需项annotations: service.beta.kubernetes.io/aws-load-balancer-target-group-attributes: deregistration_delay.timeout_seconds270 service.beta.kubernetes.io/aws-load-balancer-nlb-target-type: ip service.beta.kubernetes.io/aws-load-balancer-healthcheck-path: /healthz service.beta.kubernetes.io/aws-load-balancer-healthcheck-port: 10254 service.beta.kubernetes.io/aws-load-balancer-healthcheck-protocol: http service.beta.kubernetes.io/aws-load-balancer-healthcheck-success-codes: 200-299 service.beta.kubernetes.io/aws-load-balancer-scheme: internet-facing service.beta.kubernetes.io/aws-load-balancer-backend-protocol: tcp service.beta.kubernetes.io/aws-load-balancer-cross-zone-load-balancing-enabled: true service.beta.kubernetes.io/aws-load-balancer-type: nlb service.beta.kubernetes.io/aws-load-balancer-manage-backend-security-group-rules: true service.beta.kubernetes.io/aws-load-balancer-access-log-enabled: true service.beta.kubernetes.io/aws-load-balancer-security-groups: sg-something1 sg-something2 service.beta.kubernetes.io/aws-load-balancer-access-log-s3-bucket-name: somebucket service.beta.kubernetes.io/aws-load-balancer-access-log-s3-bucket-prefix: ingress-nginx service.beta.kubernetes.io/aws-load-balancer-access-log-emit-interval: 5注意其中的健康检查端口10254正是控制器 healthz 端点的默认端口见下文 CLI 参数表。防火墙与预检安装后需要放通以下端口8443/tcp用于 Ingress NGINX 的准入控制器admission controller需要在所有运行 Kubernetes 节点的宿主机之间开放80/tcpHTTP与 443/tcpHTTPS对外公开指向应用 DNS 所解析的节点。检查实际使用的端口可查看kubectl -n ingress-nginx get pod -o yaml验证 Pod 是否全部就绪kubectl get pods --namespaceingress-nginx等待控制器 Pod 变为 ready超时 120skubectl wait --namespace ingress-nginx \ --forconditionready pod \ --selectorapp.kubernetes.io/componentcontroller \ --timeout120s本地测试port-forward 快速验证创建示例后端 Deployment 与 Servicekubectl create deployment demo --imagehttpd --port80 kubectl expose deployment demo创建使用nginxIngressClass 的 Ingress主机名映射到localhostkubectl create ingress demo-localhost --classnginx \ --ruledemo.localdev.me/*demo:80将本地 8080 端口转发到控制器的 Service 80 端口kubectl port-forward --namespaceingress-nginx service/ingress-nginx-controller 8080:80说明port-forward把本地 TCP 8080 端口映射到控制器 Service 的 80 端口从而在本地模拟来自集群外部的请求。它仅用于演示不适用于生产环境生产场景请使用 LoadBalancer 或下文的环境特定方案。最后用curl --resolve绕过 DNS 直接访问curl --resolve demo.localdev.me:8080:127.0.0.1 http://demo.localdev.me:8080应返回包含It works!的 HTML 页面。在线测试LoadBalancer 与真实域名如果集群支持LoadBalancer类型 Service控制器会被分配外部 IP 或 FQDNkubectl get service ingress-nginx-controller --namespaceingress-nginx查看EXTERNAL-IP字段若为pending说明集群无法供给负载均衡器通常是不支持LoadBalancer类型。为外部 IP 配置 DNS 记录后创建 Ingresskubectl create ingress demo --classnginx \ --rulewww.demo.io/*demo:80该命令等价于kubectl create ingress demo --classnginx \ --rule www.demo.io/demo:80之后访问http://www.demo.io/即可看到 It works! 页面——一个由 Kubernetes 集群托管的公网网站就此诞生。环境特定部署本地开发集群环境命令minikubeminikube addons enable ingressMicroK8smicrok8s enable ingressDocker Desktop在 Docker 设置中启用 Kuberneteskubectl get nodes应显示名为docker-desktop的节点然后按上文快速开始安装多数情况下控制器会获得localhost的 EXTERNAL-IP否则回退到 port-forward 方案Rancher Desktop底层为 K3s默认 Ingress 控制器是 Traefik需在 Preference Kubernetes 中禁用 Traefik 后再按快速开始安装云环境通用优化若云厂商负载均衡器对后端做主动健康检查多数如此可将控制器 Service 的externalTrafficPolicy改为Local以省去一跳转发helm upgrade --install ingress-nginx ingress-nginx \ --repo https://kubernetes.github.io/ingress-nginx \ --namespace ingress-nginx --create-namespace \ --set controller.service.externalTrafficPolicyLocal若负载均衡器支持 PROXY 协议可让控制器看到客户端真实 IP否则只会看到上游 LB 的 IP。这需要两侧同时开启控制器侧--set controller.config.use-proxy-protocoltrue云厂商 LB 侧开启 PROXY protocol。各云厂商的专用清单源文件可在仓库 deploy/static/provider/ 下找到含 aws、do、scw、exoscale、oracle、cloud、baremetal、kind 等子目录。几个要点AWS使用 NLB 暴露控制器。如需在 LB 侧终结 TLS下载nlb-with-tls-termination模板修改其中的proxy-real-ip-cidr改为集群 VPC CIDR与 ACM 证书 ARN 后再kubectl apply -f deploy.yaml。AWS NLB 的 TCP 空闲超时默认 350s可调 60–6000s务必保证 NGINXkeepalive_timeout默认 75s小于该值。GCE/GKE默认 GKE LoadBalancer不支持 PROXY 协议开启use-proxy-protocol无效私有集群还需放行主节点到工作节点 8443/tcp 的防火墙规则。Azure应用provider/cloud下的清单即可。Digital Ocean默认只配置了service.beta.kubernetes.io/do-loadbalancer-enable-proxy-protocol: true一个注解若要让 DO LoadBalancer 图表显示数据需要补充其他注解。Scaleway / Exoscale / Oracle / OVHcloud分别有专用清单或 Helm 安装方式详见 docs/deploy/index.md。裸金属集群裸金属或自建 VM 集群没有按需供给的云负载均衡器官方提供了四种方案详见 docs/deploy/baremetal.mdMetalLB纯软件方案为集群提供 LoadBalancer Service 实现Layer 2 模式下由单节点吸引全部流量需为IPAddressPool分配一段专用 IP不可复用节点 IP 或 DHCP 地址。NodePort Service最简单通过kube-proxy在所有节点暴露同一未特权端口默认 30000–32767。客户端访问需携带 NodePort如http://myapp.example.com:30100由于默认做源地址转换若要保留源 IP 需设置externalTrafficPolicy: Local注意这会丢弃发往未运行控制器的节点的包。不推荐通过修改--service-node-port-range把 NodePort 压到 80/443可能引发端口冲突等意外问题。hostNetwork控制器 Pod 直接绑定节点网络接口可独占 80/443每个节点只能调度一个控制器 Pod端口互斥建议以 DaemonSet 部署。注意hostNetwork: true的 Pod 默认不使用集群 DNS需设置dnsPolicy: ClusterFirstWithHostNet且无 Service 可发布需启用--report-node-internal-ip-address标志让 Ingress 状态写入节点内网 IP。自建边缘Self-provisioned edge由硬件或软件边缘组件如 HAProxy在集群外提供公网入口把 80/443 流量转发到节点上的 NodePort适合节点无公网 IP 的私有集群。常用运维要点Miscellaneous查看控制器版本POD_NAMESPACEingress-nginx POD_NAME$(kubectl get pods -n $POD_NAMESPACE -l app.kubernetes.io/nameingress-nginx --field-selectorstatus.phaseRunning -o name) kubectl exec $POD_NAME -n $POD_NAMESPACE -- /nginx-ingress-controller --version限制监听范围Scope默认控制器 watch 所有命名空间的 Ingress。可通过--watch-namespace标志或 Helm valuecontroller.scope限定到单个命名空间。注意default-ssl-certificate所引用的 Secret 必须同时存在于被 watch 的命名空间中。Webhook 网络可达性控制器通过准入 Webhook校验 Ingress 定义。务必保证 API Server 到ingress-nginx-controller-admissionService 的链路不被 NetworkPolicy 或防火墙阻断否则创建/更新 Ingress 会被拦截。证书生成延迟控制器首次启动时两个 Job 会为准入 Webhook 生成 SSL 证书导致最长约两分钟的初始化延迟。等待其就绪后再执行后续命令kubectl wait --namespace ingress-nginx \ --forconditionready pod \ --selectorapp.kubernetes.io/componentcontroller \ --timeout120sKubernetes 1.19 之前的兼容性Ingress API 经历了extensions/v1beta1→networking.k8s.io/v1beta1→networking.k8s.io/v1的演进兼容矩阵如下Kubernetes 版本支持的 Ingress API 1.19仅v1beta11.19 – 1.21v1beta1与v1均支持≥ 1.22仅v1控制器侧v1.0 之前仅支持v1beta1v1.0 及以后仅支持v1。因此 Kubernetes 1.19 可直接使用最新控制器1.18 及更早需使用 0.X 版本如 0.49。Helm Chart 在第 4 版切换到 Chart 版本 1若运行 Kubernetes 1.19 及更早应使用 3.X 版 Charthelm install时加--version4。源码视角关键 CLI 参数与配置入口docs/index.md强调 ConfigMap 承载控制器配置而控制器的完整可调参数以命令行参数形式暴露详见 docs/user-guide/cli-arguments.md它们被写进 Deployment 的容器 spec 中。以下是与日常运维强相关的核心参数参数作用默认值--configmap承载全局配置的 ConfigMap 名称与上文架构对应--controller-class本控制器满足的 IngressClass Controller 值Ingress 通过ingressClassName字段匹配--ingress-class满足的 Ingress class 名称默认nginx未设置或为默认值时也会处理 class 为空或为nginx的 Ingress--watch-namespace限制 watch 的命名空间空则 watch 全部--default-backend-servicecatch-all 默认后端格式namespace/name--default-ssl-certificate默认 HTTPS catch-all 服务器所用证书 Secret格式namespace/name--healthz-porthealthz 端点端口默认 10254即云厂商健康检查注解使用的端口--health-check-path健康检查路径默认/healthz--http-port/--https-port服务 HTTP/HTTPS 的端口默认 80 / 443--tcp-services-configmap/--udp-services-configmap定义 TCP/UDP 流式服务暴露的 ConfigMap值格式namespace/name:port--publish-service前置控制器的 Servicenamespace/name与--update-status配合把其端点地址镜像到 Ingress 的 load-balancer 状态--publish-status-address自定义写入 Ingress 状态的地址列表逗号分隔--report-node-internal-ip-address将 Ingress 状态设置为节点内网 IP裸金属 hostNetwork 场景常用--enable-ssl-passthrough启用 SSL Passthrough默认 false--validating-webhook启动准入校验 Webhook 的监听地址host:port--annotations-prefix注解前缀默认nginx.ingress.kubernetes.io--sync-period/--sync-rate-limit本地对象存储强制重载周期默认关闭/ 同步频率上限默认 0.3--enable-metrics开启 NGINX 指标采集默认 false这些参数对应源码中的Configuration结构体internal/ingress/controller/controller.go与 internal/ingress/controller/config/config.go而 TCP/UDP 流式服务的加载逻辑按 ConfigMap 名称解析namespace/name:port引用可在 controller.go 中看到实际实现。结语Ingress NGINX Controller 以 Kubernetes Ingress 资源为路由事实源、以 ConfigMap 为全局配置载体配合准入 Webhook、健康检查与状态上报机制构成了一个声明式的七层入口控制器。尽管项目已进入退役阶段理解其架构与部署方式对于存量集群的日常维护、排障以及向 Gateway API 方案的迁移规划仍有直接价值。更深入的主题ConfigMap 全部可配项、注解、监控、故障排查可继续阅读仓库 docs 目录 下的 user-guide 与 troubleshooting.md。【免费下载链接】ingress-nginxIngress NGINX Controller for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/in/ingress-nginx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
