Kubernetes生产运维08Ingress报404和502怎么顺着七层链路分清是路由错还是后端挂写在前面Ingress报错时很多人不区分404和502一律去重启Ingress控制器或改规则试。其实这两个错误码指向完全不同的位置。粗略地说404请求到了Ingress控制器但没有匹配到任何转发规则或者匹配到的规则没有对应后端。问题在路由层。502或503请求匹配到了规则但转发到后端时后端不可用比如没有就绪Endpoint、后端拒绝连接或返回错误。问题在后端。504匹配并连上了后端但后端响应超时。问题在后端处理时间或超时配置。先看错误码就能把排查方向分成查路由还是查后端两大类避免一上来就乱改。因此Ingress排查沿着这条七层链路逐段确认客户端报错 → 先看是404还是502/503/504 → 404查host、path、IngressClass和规则是否命中 → 502/503查规则指向的Service和Endpoint是否可用 → 504查后端响应时间和超时配置 → 结合Ingress控制器日志定位断点 → 针对性修复并验证 → 补七层监控与配置校验本文按照Kubernetes官方机制和常见Ingress控制器行为整理。由于当前没有连接可验证的实验集群命令没有在统一版本的真实集群完整执行案例和终端输出均为C级生产化重建不是生产原始记录。不同Ingress控制器如ingress-nginx、Traefik等、Kubernetes版本、证书方案和云厂商LB可能改变错误码细节、字段和行为执行前应以目标集群和控制器文档为准。一、先理解Ingress的七层链路1.1 一次请求要经过哪些环节从客户端到容器HTTP请求大致经过客户端 → DNS解析Ingress域名到入口IP → 云LB或NodePort到达Ingress控制器 → Ingress控制器按host和path匹配Ingress规则 → 规则指向某个Service → Service通过EndpointSlice找到就绪Pod → 转发到Pod容器端口任何一段断了都可能报错但错误码会提示大致位置。1.2 Ingress只是规则控制器才是执行者一个关键概念Ingress资源本身只是一组路由规则声明真正接收流量、做匹配和转发的是Ingress控制器如ingress-nginx、Traefik。所以Ingress规则写了不代表生效要有对应的控制器在运行并加载了规则ingressClassName决定这条Ingress由哪个控制器处理写错或缺失可能导致规则根本没被任何控制器接管排查要同时看Ingress资源和控制器状态、日志1.3 404和502的分工错误码大致含义断点位置404 Not Found没匹配到规则或规则无对应后端路由层host、path、IngressClass、规则502 Bad Gateway转发到后端失败后端拒绝或返回无效响应后端Endpoint、Pod、端口503 Service Unavailable没有可用后端后端无就绪Endpoint504 Gateway Timeout后端响应超时后端处理时间或超时配置这个映射是排障方向指引不是精确契约。不同控制器在边界情况下可能返回不同码例如无后端有的返回503有的返回502要结合控制器文档和日志确认。二、Ingress排查决策树Ingress报错 │ ├─ 先看错误码 │ ├─ 404 → 路由层 │ │ ├─ host不匹配 │ │ ├─ path不匹配或pathType不符 │ │ ├─ ingressClassName错误或缺失 │ │ └─ 规则指向的Service不存在 │ ├─ 502/503 → 后端层 │ │ ├─ Service无就绪Endpoint │ │ ├─ 后端端口或协议不符 │ │ └─ 后端拒绝连接 │ └─ 504 → 后端超时 │ ├─ 后端处理慢 │ └─ 控制器超时配置过小 │ ├─ 结合Ingress控制器日志定位 │ ├─ 针对性修复并验证 │ └─ 补七层监控与校验先确认Ingress资源和控制器都在NSnamespaceINGingress-namekubectl get ingress$ING-n$NS-owide kubectl get pods-ningress-controller-namespace-lcontroller-label-owideIngress的ADDRESS为空可能说明控制器没接管这条规则往IngressClass和控制器查。三、取证先看错误码指向哪一层3.1 查Ingress资源本身kubectl describe ingress$ING-n$NSkubectl get ingress$ING-n$NS\-ojsonpath{class}{.spec.ingressClassName}{\n}{range .spec.rules[*]}{host}{.host}{\n}{range .http.paths[*]}{ path}{.path}{ type}{.pathType}{ svc}{.backend.service.name}{:}{.backend.service.port.number}{\n}{end}{end}关注ingressClassName是否是集群里实际存在的类每条规则的host、path、pathType每个path指向的Service名和端口describe底部Events和ADDRESS3.2 404分支查路由是否命中404意味着请求到了控制器但没匹配到规则。逐项核对# 确认请求用的host和path与Ingress规则一致# 确认IngressClass存在kubectl get ingressclass# 确认规则指向的Service存在kubectl get svc-n$NS常见404原因请求的host与Ingress的host不一致包括大小写、末尾点、泛域名path不匹配或pathType用了Exact导致精确路径外的请求不命中ingressClassName错误或缺失规则没被控制器接管控制器返回默认404规则指向的Service名写错或不存在3.3 502/503分支查后端是否可用502/503意味着规则命中了但后端不可用。这时问题和第06篇Service排查衔接# 规则指向的Service有没有就绪EndpointSVCbackend-servicekubectl get endpointslices-n$NS-lkubernetes.io/service-name$SVC\-ocustom-columnsNAME:.metadata.name,ADDRESSES:.endpoints[*].addresses,READY:.endpoints[*].conditions.ready,PORTS:.ports[*].port没有就绪Endpoint → 后端Pod未就绪或Selector不匹配回到Service和Pod排查有Endpoint但502 → 后端端口、协议不符或后端拒绝连接Ingress的targetPort、Service的targetPort、容器端口三者要对齐3.4 504分支查超时504意味着连上了后端但超时后端处理时间超过控制器的转发超时控制器的超时注解配置过小后端偶发慢或过载处理要区分是后端真的慢还是超时配置不合理两者修复不同。3.5 关键取证Ingress控制器日志错误码只是方向控制器日志才是决定性证据kubectl logs-ningress-controller-namespace\-lcontroller-label--tail100|grephost-or-path控制器访问日志通常记录每个请求的host、path、匹配到的后端、上游响应码和耗时能直接看出是没匹配规则、上游无响应还是上游超时。3.6 边界不同Ingress控制器的日志格式、注解和错误码行为不同以实际控制器文档为准云厂商LB可能在Ingress控制器之前也会产生自己的错误码要区分是LB还是控制器返回直接抓包或改控制器配置属于更深或变更操作放在只读取证之后四、常见断点与判断现象更可能的断点优先检查不能直接得出的结论404其他host正常该host或path规则问题Ingress host、path、pathType不一定是后端问题404整个Ingress不生效IngressClass或控制器未接管ingressClassName、控制器状态不一定是规则写错502规则命中后端无就绪Endpoint或端口不符EndpointSlice、targetPort不一定是控制器故障503没有可用后端后端Pod就绪、Selector不一定是网络问题504后端慢或超时配置小后端响应时间、超时注解不一定是后端崩溃证书错误或HTTPS失败TLS Secret或证书配置Ingress tls、Secret、证书有效期不一定是路由问题偶发502后端滚动发布或就绪抖动发布期就绪、优雅关闭不一定是持续故障一个核心区分404往路由查502/503往后端查,504往超时查。先按错误码分流能避免在错误的层反复试。五、C级生产化重建案例新加的域名一直4045.1 先说明哪些是真的哪些是重建的下面不是作者声称亲历的生产事故而是根据Kubernetes Ingress和控制器路由机制构造的生产化重建用于展示从404走到可验证根因的取证过程。内容证据属性Ingress规则、host匹配、IngressClass和控制器转发的机制Kubernetes官方机制新增域名访问一直404机制一致的重建场景Namespace、资源名、域名、path和终端输出为讲解构造的说明性信息新Ingress缺少ingressClassName模拟根因不是作者生产记录修正单一变量后验证路由生效受控验证设计不声称已在当前集群执行所有输出按真实对象关系编排但没有连接实际集群采集读者不能把下面的域名、path或输出引用为真实事故数据。5.2 现场卡片团队上线了一个新服务配了新的Ingress域名。访问旧域名都正常唯独新域名一直返回404。后端Pod看起来都在运行。团队最初怀疑新服务的应用有问题。重建的相对时间线相对时间观察或动作当时能够得出的结论T00新域名上线后访问返回404只能确认路由没通原因未知T02怀疑新服务应用有问题待验证假设T04直接访问后端Service正常后端本身没问题转向路由T06新Ingress的ADDRESS为空控制器可能没接管这条规则T09对比新旧Ingress发现缺ingressClassName得到可验证的主假设T验证只补ingressClassName观察是否生效单变量验证相对时间只表示排查顺序不代表真实数值。5.3 先确认是404而非后端问题先在集群内直接访问后端Service绕过IngressNSexample-prod kubectl run curltest--rm-it--restartNever-n$NS\--imageapproved-debug-image--\sh-ccurl -s -o /dev/null -w %{http_code}\n http://new-app.example-prod.svc/healthz机制一致的说明性输出200后端Service直接访问返回200说明后端Pod、Service和Endpoint都正常。问题不在后端而在Ingress路由层。这条命令用临时Pod属主动操作需经审批镜像并自动清理。5.4 查Ingress资源和控制器接管情况INGnew-app kubectl get ingress$ING-n$NS-owide机制一致的说明性输出NAME CLASS HOSTS ADDRESS PORTS AGE new-app none new.example.com 80 10m关键发现CLASS是noneADDRESS为空。对比旧的正常Ingresskubectl get ingress-n$NS-ocustom-columnsNAME:.metadata.name,CLASS:.spec.ingressClassName,ADDRESS:.status.loadBalancer.ingress[*].ip机制一致的说明性输出NAME CLASS ADDRESS old-app nginx 203.0.113.10 new-app none旧Ingress有nginx类且分到了ADDRESS新Ingress没有类、没有ADDRESS。这说明新Ingress没有被任何控制器接管请求落到控制器默认后端返回404。5.5 确认集群的IngressClasskubectl get ingressclass机制一致的说明性输出NAME CONTROLLER nginx k8s.io/ingress-nginx集群里有nginx这个类旧Ingress用的就是它。新Ingress漏写了ingressClassName且集群没有设置默认IngressClass所以规则悬空。证据链后端Service直接访问200后端正常 新Ingress的CLASS为none、ADDRESS为空 旧Ingress有nginx类且分到ADDRESS 集群存在nginx类但无默认类 新Ingress漏写ingressClassName 强烈支持缺少ingressClassName导致规则未被控制器接管而404这仍是主假设验证前不写成根因已闭环。5.6 止损与单变量验证修正只补一个字段ingressClassName不动host、path、后端Service和控制器配置apiVersion:networking.k8s.io/v1kind:Ingressmetadata:name:new-appnamespace:example-prodspec:ingressClassName:nginxrules:-host:new.example.comhttp:paths:-path:/pathType:Prefixbackend:service:name:new-appport:number:80验证并保存修复后证据kubectl apply-fnew-app-ingress.yaml kubectl get ingress new-app-n$NS-owide机制一致的说明性输出NAME CLASS HOSTS ADDRESS PORTS AGE new-app nginx new.example.com 203.0.113.10 80 11m再从外部或集群内验证路由kubectl run curltest--rm-it--restartNever-n$NS\--imageapproved-debug-image--\sh-ccurl -s -o /dev/null -w %{http_code}\n -H Host: new.example.com http://ingress-address/机制一致的说明性输出200补上IngressClass后控制器接管了规则、分配了ADDRESS路由从404变为200。这些输出分别证明不同范围的事实输出能够支持不能单独证明后端Service直接200后端本身正常Ingress路由一定正常Ingress有CLASS和ADDRESS控制器已接管规则所有path都正确带Host请求返回200该host路由已通其他host和TLS都正常5.7 根因闭环条件修正版与问题版只有ingressClassName这一项主要差异。修正后Ingress分到ADDRESS控制器接管规则。后端在修正前后都正常排除后端因素。该域名从404变为200。观察窗口内路由稳定没有反复。如果补了IngressClass仍404就要停止把它当作唯一原因转查host、path、pathType和控制器日志。六、修复方案要分六层层次本文场景中的动作关键边界应急止损补正确的ingressClassName或修正路由规则确认不影响同控制器的其他Ingress现场取证保存Ingress、IngressClass、控制器日志、后端Endpoint临时Pod属主动操作需经审批镜像根因验证只改一个路由字段并观察是否生效不同时改host、path和后端永久修复在Git或Helm源配置补全IngressClass或设置集群默认IngressClass监控预防监控七层状态码、后端可用性和证书有效期区分404路由问题和502后端问题运行治理Ingress模板校验、IngressClass约定、发布检查ingressClassName纳入模板必填临时恢复不等于根因确认。补上IngressClass后路由通了只说明变更与故障相关仍需后端正常、控制器接管和单变量验证共同支撑。不要一报错就重启Ingress控制器或大改规则。404是路由未匹配重启控制器无效502是后端问题改路由规则也无效。先按错误码分流。七、可直接使用的只读Ingress采集脚本脚本只读取对象和日志不修改Ingress、不重启控制器、不创建调试Pod。连通性测试需另用临时Pod属主动操作。#!/usr/bin/env bashset-uset-opipefailNS${1:?用法:$0 namespace ingress-name[controller-namespace][controller-label]}ING${2:?用法:$0 namespace ingress-name[controller-namespace][controller-label]}CTRL_NS${3:-ingress-nginx}CTRL_LABEL${4:-app.kubernetes.io/nameingress-nginx}STAMP$(date%Y%m%d-%H%M%S)OUTingress-evidence-${NS}-${ING}-${STAMP}mkdir-p$OUTumask077capture(){localfile$1shiftprintf采集 %s\n$fileif!$$OUT/$file2$OUT/$file.err;thenprintf失败: %s查看 %s.err\n$file$file2fi}capture context.txt kubectl config current-context capture version.txt kubectl version capture ingress.yaml kubectl get ingress$ING-n$NS-oyaml capture ingress-describe.txt kubectl describe ingress$ING-n$NScapture ingress-wide.txt kubectl get ingress$ING-n$NS-owide capture ingressclass.txt kubectl get ingressclass capture services.txt kubectl get svc-n$NS-owide capture endpointslices.txt kubectl get endpointslices-n$NS-owide capture controller-pods.txt kubectl get pods-n$CTRL_NS-l$CTRL_LABEL-owide capture controller-logs.txt kubectl logs-n$CTRL_NS-l$CTRL_LABEL--tail200printf采集完成: %s\n$OUTprintf路由连通性测试请另用经审批镜像的临时Pod属主动操作\nprintf分享前请检查域名、地址、证书和配置引用中的敏感信息\n使用方式bashcollect-ingress-evidence.shnamespaceingress-namecontroller-namespacecontroller-label脚本边界控制器命名空间和标签因安装方式不同默认按ingress-nginx需按实际调整连通性测试需另用临时Pod属主动操作不同控制器日志格式不同需结合控制器文档解读脚本用于保存首轮现场不能替代按错误码选择下一步八、监控、证书与治理8.1 监控什么按host和path的4xx、5xx状态码比例Ingress后端可用性和就绪Endpoint数上游响应时间和504超时率TLS证书有效期和到期告警Ingress控制器负载和重载错误告警要区分层次4xx升高多是路由或客户端问题5xx升高多是后端问题分开告警便于快速定位。8.2 发布前校验Ingress必须设置正确的ingressClassName或依赖明确的默认类host、path、pathType与实际访问方式一致规则指向的Service存在且有就绪后端TLS配置引用的Secret存在且证书有效控制器超时注解与后端实际响应时间匹配8.3 证书与治理证书临近到期前告警避免HTTPS突然失败ingressClassName作为Ingress模板的必填项后端就绪和优雅关闭配置好减少发布期偶发502Ingress变更走灰度和验证避免影响同控制器其他域名九、常见误区误区1不分404和502一起处理404是路由未匹配502是后端不可用方向完全不同。误区2一报错就重启Ingress控制器路由未匹配和后端问题重启控制器都无效。误区3忘记ingressClassName漏写且无默认类时规则不被任何控制器接管返回404。误区4pathType用错Exact要求精确匹配Prefix是前缀匹配用错会导致部分路径404。误区5502时只改路由规则502是后端问题改路由无效要查Endpoint和端口。误区6忽略后端就绪导致的偶发502滚动发布时后端未就绪或未优雅关闭会产生偶发502。误区7证书到期无告警TLS证书到期会让HTTPS突然失败需提前告警。误区8把云LB的错误当成控制器的云LB在控制器之前也会返回错误码要区分来源。十、面试怎么说60秒版本Ingress报错我先看错误码分流。404是请求到了控制器但没匹配到规则查host、path、pathType、ingressClassName和规则指向的Service。502或503是规则命中但后端不可用查Service的就绪Endpoint和端口和Service排查衔接。504是后端超时查后端响应时间和超时配置。控制器日志是决定性证据能看出是没匹配、上游无响应还是超时。修复只改一个字段并验证不盲目重启控制器。最后按host和path分层监控4xx和5xx。3分钟场景版本假设新上线域名一直404旧域名正常后端Pod都在跑。我先在集群内直接访问后端Service返回200说明后端正常问题在路由层。看新Ingress发现CLASS是none、ADDRESS为空而旧Ingress有nginx类且有ADDRESS。查IngressClass集群里有nginx但没有默认类说明新Ingress漏写了ingressClassName规则没被控制器接管请求落到默认后端返回404。我只给新Ingress补上ingressClassName为nginx不动host、path和后端apply后Ingress分到ADDRESS、控制器接管、访问从404变200。这样我能区分是路由配置问题而不是应用故障也不会用重启控制器这种无关动作去掩盖。十一、延伸问答1. 404和502最本质的区别404是请求没匹配到转发规则或规则无后端问题在路由层502是匹配到了但后端不可用问题在后端。2. Ingress的ADDRESS为空说明什么通常说明没有控制器接管这条Ingress常见于ingressClassName错误或缺失、控制器未运行。3. pathType的Exact和Prefix有什么区别Exact要求路径精确相等Prefix按路径前缀匹配。用错会导致部分请求404。4. 502一定是应用崩了吗不一定。可能是无就绪Endpoint、端口不符、后端拒绝连接也可能是发布期就绪抖动。5. 504怎么处理先区分是后端真的慢还是控制器超时配置过小前者优化后端或扩容后者调整超时注解。6. 为什么直接访问Service能通但Ingress不通说明后端正常问题在Ingress路由层如host、path、IngressClass或控制器。7. 证书问题会报什么TLS握手失败或证书错误和404、502不同要查Ingress的tls配置、引用的Secret和证书有效期。8. 不同Ingress控制器行为一样吗不完全一样。错误码边界、注解、默认后端和日志格式因控制器而异要以实际控制器文档为准。小结Ingress报错先看错误码404查路由502/503查后端504查超时。Ingress只是规则控制器才是执行者规则要被正确的控制器接管。ingressClassName错误或缺失会让规则悬空返回404。502要和Service排查衔接查就绪Endpoint和端口。控制器日志是定位断点的决定性证据。直接访问后端Service可快速区分是路由还是后端问题。修复只改一个字段并验证不盲目重启控制器。长期治理覆盖IngressClass约定、证书告警、分层状态码监控和发布校验。下一篇预告下一篇进入PVC Pending与挂载失败。我们会沿着StorageClass、PV绑定、CSI、拓扑和权限区分制备失败、绑定冲突和挂载错误并整理一份存储故障决策树。参考资料Kubernetes官方文档IngressKubernetes官方文档Ingress ControllersKubernetes官方文档ServiceKubernetes官方文档EndpointSlicesKubernetes官方文档Debug ServicesKubernetes官方文档Liveness, Readiness and Startup ProbesKubernetes官方文档DNS for Services and PodsKubernetes官方文档Ingress APIKubernetes官方文档IngressClassingress-nginx官方文档 Kubernetes生产运维08：Ingress报404和502，怎么顺着七层链路分清是路由错还是后端挂
Kubernetes生产运维08Ingress报404和502怎么顺着七层链路分清是路由错还是后端挂写在前面Ingress报错时很多人不区分404和502一律去重启Ingress控制器或改规则试。其实这两个错误码指向完全不同的位置。粗略地说404请求到了Ingress控制器但没有匹配到任何转发规则或者匹配到的规则没有对应后端。问题在路由层。502或503请求匹配到了规则但转发到后端时后端不可用比如没有就绪Endpoint、后端拒绝连接或返回错误。问题在后端。504匹配并连上了后端但后端响应超时。问题在后端处理时间或超时配置。先看错误码就能把排查方向分成查路由还是查后端两大类避免一上来就乱改。因此Ingress排查沿着这条七层链路逐段确认客户端报错 → 先看是404还是502/503/504 → 404查host、path、IngressClass和规则是否命中 → 502/503查规则指向的Service和Endpoint是否可用 → 504查后端响应时间和超时配置 → 结合Ingress控制器日志定位断点 → 针对性修复并验证 → 补七层监控与配置校验本文按照Kubernetes官方机制和常见Ingress控制器行为整理。由于当前没有连接可验证的实验集群命令没有在统一版本的真实集群完整执行案例和终端输出均为C级生产化重建不是生产原始记录。不同Ingress控制器如ingress-nginx、Traefik等、Kubernetes版本、证书方案和云厂商LB可能改变错误码细节、字段和行为执行前应以目标集群和控制器文档为准。一、先理解Ingress的七层链路1.1 一次请求要经过哪些环节从客户端到容器HTTP请求大致经过客户端 → DNS解析Ingress域名到入口IP → 云LB或NodePort到达Ingress控制器 → Ingress控制器按host和path匹配Ingress规则 → 规则指向某个Service → Service通过EndpointSlice找到就绪Pod → 转发到Pod容器端口任何一段断了都可能报错但错误码会提示大致位置。1.2 Ingress只是规则控制器才是执行者一个关键概念Ingress资源本身只是一组路由规则声明真正接收流量、做匹配和转发的是Ingress控制器如ingress-nginx、Traefik。所以Ingress规则写了不代表生效要有对应的控制器在运行并加载了规则ingressClassName决定这条Ingress由哪个控制器处理写错或缺失可能导致规则根本没被任何控制器接管排查要同时看Ingress资源和控制器状态、日志1.3 404和502的分工错误码大致含义断点位置404 Not Found没匹配到规则或规则无对应后端路由层host、path、IngressClass、规则502 Bad Gateway转发到后端失败后端拒绝或返回无效响应后端Endpoint、Pod、端口503 Service Unavailable没有可用后端后端无就绪Endpoint504 Gateway Timeout后端响应超时后端处理时间或超时配置这个映射是排障方向指引不是精确契约。不同控制器在边界情况下可能返回不同码例如无后端有的返回503有的返回502要结合控制器文档和日志确认。二、Ingress排查决策树Ingress报错 │ ├─ 先看错误码 │ ├─ 404 → 路由层 │ │ ├─ host不匹配 │ │ ├─ path不匹配或pathType不符 │ │ ├─ ingressClassName错误或缺失 │ │ └─ 规则指向的Service不存在 │ ├─ 502/503 → 后端层 │ │ ├─ Service无就绪Endpoint │ │ ├─ 后端端口或协议不符 │ │ └─ 后端拒绝连接 │ └─ 504 → 后端超时 │ ├─ 后端处理慢 │ └─ 控制器超时配置过小 │ ├─ 结合Ingress控制器日志定位 │ ├─ 针对性修复并验证 │ └─ 补七层监控与校验先确认Ingress资源和控制器都在NSnamespaceINGingress-namekubectl get ingress$ING-n$NS-owide kubectl get pods-ningress-controller-namespace-lcontroller-label-owideIngress的ADDRESS为空可能说明控制器没接管这条规则往IngressClass和控制器查。三、取证先看错误码指向哪一层3.1 查Ingress资源本身kubectl describe ingress$ING-n$NSkubectl get ingress$ING-n$NS\-ojsonpath{class}{.spec.ingressClassName}{\n}{range .spec.rules[*]}{host}{.host}{\n}{range .http.paths[*]}{ path}{.path}{ type}{.pathType}{ svc}{.backend.service.name}{:}{.backend.service.port.number}{\n}{end}{end}关注ingressClassName是否是集群里实际存在的类每条规则的host、path、pathType每个path指向的Service名和端口describe底部Events和ADDRESS3.2 404分支查路由是否命中404意味着请求到了控制器但没匹配到规则。逐项核对# 确认请求用的host和path与Ingress规则一致# 确认IngressClass存在kubectl get ingressclass# 确认规则指向的Service存在kubectl get svc-n$NS常见404原因请求的host与Ingress的host不一致包括大小写、末尾点、泛域名path不匹配或pathType用了Exact导致精确路径外的请求不命中ingressClassName错误或缺失规则没被控制器接管控制器返回默认404规则指向的Service名写错或不存在3.3 502/503分支查后端是否可用502/503意味着规则命中了但后端不可用。这时问题和第06篇Service排查衔接# 规则指向的Service有没有就绪EndpointSVCbackend-servicekubectl get endpointslices-n$NS-lkubernetes.io/service-name$SVC\-ocustom-columnsNAME:.metadata.name,ADDRESSES:.endpoints[*].addresses,READY:.endpoints[*].conditions.ready,PORTS:.ports[*].port没有就绪Endpoint → 后端Pod未就绪或Selector不匹配回到Service和Pod排查有Endpoint但502 → 后端端口、协议不符或后端拒绝连接Ingress的targetPort、Service的targetPort、容器端口三者要对齐3.4 504分支查超时504意味着连上了后端但超时后端处理时间超过控制器的转发超时控制器的超时注解配置过小后端偶发慢或过载处理要区分是后端真的慢还是超时配置不合理两者修复不同。3.5 关键取证Ingress控制器日志错误码只是方向控制器日志才是决定性证据kubectl logs-ningress-controller-namespace\-lcontroller-label--tail100|grephost-or-path控制器访问日志通常记录每个请求的host、path、匹配到的后端、上游响应码和耗时能直接看出是没匹配规则、上游无响应还是上游超时。3.6 边界不同Ingress控制器的日志格式、注解和错误码行为不同以实际控制器文档为准云厂商LB可能在Ingress控制器之前也会产生自己的错误码要区分是LB还是控制器返回直接抓包或改控制器配置属于更深或变更操作放在只读取证之后四、常见断点与判断现象更可能的断点优先检查不能直接得出的结论404其他host正常该host或path规则问题Ingress host、path、pathType不一定是后端问题404整个Ingress不生效IngressClass或控制器未接管ingressClassName、控制器状态不一定是规则写错502规则命中后端无就绪Endpoint或端口不符EndpointSlice、targetPort不一定是控制器故障503没有可用后端后端Pod就绪、Selector不一定是网络问题504后端慢或超时配置小后端响应时间、超时注解不一定是后端崩溃证书错误或HTTPS失败TLS Secret或证书配置Ingress tls、Secret、证书有效期不一定是路由问题偶发502后端滚动发布或就绪抖动发布期就绪、优雅关闭不一定是持续故障一个核心区分404往路由查502/503往后端查,504往超时查。先按错误码分流能避免在错误的层反复试。五、C级生产化重建案例新加的域名一直4045.1 先说明哪些是真的哪些是重建的下面不是作者声称亲历的生产事故而是根据Kubernetes Ingress和控制器路由机制构造的生产化重建用于展示从404走到可验证根因的取证过程。内容证据属性Ingress规则、host匹配、IngressClass和控制器转发的机制Kubernetes官方机制新增域名访问一直404机制一致的重建场景Namespace、资源名、域名、path和终端输出为讲解构造的说明性信息新Ingress缺少ingressClassName模拟根因不是作者生产记录修正单一变量后验证路由生效受控验证设计不声称已在当前集群执行所有输出按真实对象关系编排但没有连接实际集群采集读者不能把下面的域名、path或输出引用为真实事故数据。5.2 现场卡片团队上线了一个新服务配了新的Ingress域名。访问旧域名都正常唯独新域名一直返回404。后端Pod看起来都在运行。团队最初怀疑新服务的应用有问题。重建的相对时间线相对时间观察或动作当时能够得出的结论T00新域名上线后访问返回404只能确认路由没通原因未知T02怀疑新服务应用有问题待验证假设T04直接访问后端Service正常后端本身没问题转向路由T06新Ingress的ADDRESS为空控制器可能没接管这条规则T09对比新旧Ingress发现缺ingressClassName得到可验证的主假设T验证只补ingressClassName观察是否生效单变量验证相对时间只表示排查顺序不代表真实数值。5.3 先确认是404而非后端问题先在集群内直接访问后端Service绕过IngressNSexample-prod kubectl run curltest--rm-it--restartNever-n$NS\--imageapproved-debug-image--\sh-ccurl -s -o /dev/null -w %{http_code}\n http://new-app.example-prod.svc/healthz机制一致的说明性输出200后端Service直接访问返回200说明后端Pod、Service和Endpoint都正常。问题不在后端而在Ingress路由层。这条命令用临时Pod属主动操作需经审批镜像并自动清理。5.4 查Ingress资源和控制器接管情况INGnew-app kubectl get ingress$ING-n$NS-owide机制一致的说明性输出NAME CLASS HOSTS ADDRESS PORTS AGE new-app none new.example.com 80 10m关键发现CLASS是noneADDRESS为空。对比旧的正常Ingresskubectl get ingress-n$NS-ocustom-columnsNAME:.metadata.name,CLASS:.spec.ingressClassName,ADDRESS:.status.loadBalancer.ingress[*].ip机制一致的说明性输出NAME CLASS ADDRESS old-app nginx 203.0.113.10 new-app none旧Ingress有nginx类且分到了ADDRESS新Ingress没有类、没有ADDRESS。这说明新Ingress没有被任何控制器接管请求落到控制器默认后端返回404。5.5 确认集群的IngressClasskubectl get ingressclass机制一致的说明性输出NAME CONTROLLER nginx k8s.io/ingress-nginx集群里有nginx这个类旧Ingress用的就是它。新Ingress漏写了ingressClassName且集群没有设置默认IngressClass所以规则悬空。证据链后端Service直接访问200后端正常 新Ingress的CLASS为none、ADDRESS为空 旧Ingress有nginx类且分到ADDRESS 集群存在nginx类但无默认类 新Ingress漏写ingressClassName 强烈支持缺少ingressClassName导致规则未被控制器接管而404这仍是主假设验证前不写成根因已闭环。5.6 止损与单变量验证修正只补一个字段ingressClassName不动host、path、后端Service和控制器配置apiVersion:networking.k8s.io/v1kind:Ingressmetadata:name:new-appnamespace:example-prodspec:ingressClassName:nginxrules:-host:new.example.comhttp:paths:-path:/pathType:Prefixbackend:service:name:new-appport:number:80验证并保存修复后证据kubectl apply-fnew-app-ingress.yaml kubectl get ingress new-app-n$NS-owide机制一致的说明性输出NAME CLASS HOSTS ADDRESS PORTS AGE new-app nginx new.example.com 203.0.113.10 80 11m再从外部或集群内验证路由kubectl run curltest--rm-it--restartNever-n$NS\--imageapproved-debug-image--\sh-ccurl -s -o /dev/null -w %{http_code}\n -H Host: new.example.com http://ingress-address/机制一致的说明性输出200补上IngressClass后控制器接管了规则、分配了ADDRESS路由从404变为200。这些输出分别证明不同范围的事实输出能够支持不能单独证明后端Service直接200后端本身正常Ingress路由一定正常Ingress有CLASS和ADDRESS控制器已接管规则所有path都正确带Host请求返回200该host路由已通其他host和TLS都正常5.7 根因闭环条件修正版与问题版只有ingressClassName这一项主要差异。修正后Ingress分到ADDRESS控制器接管规则。后端在修正前后都正常排除后端因素。该域名从404变为200。观察窗口内路由稳定没有反复。如果补了IngressClass仍404就要停止把它当作唯一原因转查host、path、pathType和控制器日志。六、修复方案要分六层层次本文场景中的动作关键边界应急止损补正确的ingressClassName或修正路由规则确认不影响同控制器的其他Ingress现场取证保存Ingress、IngressClass、控制器日志、后端Endpoint临时Pod属主动操作需经审批镜像根因验证只改一个路由字段并观察是否生效不同时改host、path和后端永久修复在Git或Helm源配置补全IngressClass或设置集群默认IngressClass监控预防监控七层状态码、后端可用性和证书有效期区分404路由问题和502后端问题运行治理Ingress模板校验、IngressClass约定、发布检查ingressClassName纳入模板必填临时恢复不等于根因确认。补上IngressClass后路由通了只说明变更与故障相关仍需后端正常、控制器接管和单变量验证共同支撑。不要一报错就重启Ingress控制器或大改规则。404是路由未匹配重启控制器无效502是后端问题改路由规则也无效。先按错误码分流。七、可直接使用的只读Ingress采集脚本脚本只读取对象和日志不修改Ingress、不重启控制器、不创建调试Pod。连通性测试需另用临时Pod属主动操作。#!/usr/bin/env bashset-uset-opipefailNS${1:?用法:$0 namespace ingress-name[controller-namespace][controller-label]}ING${2:?用法:$0 namespace ingress-name[controller-namespace][controller-label]}CTRL_NS${3:-ingress-nginx}CTRL_LABEL${4:-app.kubernetes.io/nameingress-nginx}STAMP$(date%Y%m%d-%H%M%S)OUTingress-evidence-${NS}-${ING}-${STAMP}mkdir-p$OUTumask077capture(){localfile$1shiftprintf采集 %s\n$fileif!$$OUT/$file2$OUT/$file.err;thenprintf失败: %s查看 %s.err\n$file$file2fi}capture context.txt kubectl config current-context capture version.txt kubectl version capture ingress.yaml kubectl get ingress$ING-n$NS-oyaml capture ingress-describe.txt kubectl describe ingress$ING-n$NScapture ingress-wide.txt kubectl get ingress$ING-n$NS-owide capture ingressclass.txt kubectl get ingressclass capture services.txt kubectl get svc-n$NS-owide capture endpointslices.txt kubectl get endpointslices-n$NS-owide capture controller-pods.txt kubectl get pods-n$CTRL_NS-l$CTRL_LABEL-owide capture controller-logs.txt kubectl logs-n$CTRL_NS-l$CTRL_LABEL--tail200printf采集完成: %s\n$OUTprintf路由连通性测试请另用经审批镜像的临时Pod属主动操作\nprintf分享前请检查域名、地址、证书和配置引用中的敏感信息\n使用方式bashcollect-ingress-evidence.shnamespaceingress-namecontroller-namespacecontroller-label脚本边界控制器命名空间和标签因安装方式不同默认按ingress-nginx需按实际调整连通性测试需另用临时Pod属主动操作不同控制器日志格式不同需结合控制器文档解读脚本用于保存首轮现场不能替代按错误码选择下一步八、监控、证书与治理8.1 监控什么按host和path的4xx、5xx状态码比例Ingress后端可用性和就绪Endpoint数上游响应时间和504超时率TLS证书有效期和到期告警Ingress控制器负载和重载错误告警要区分层次4xx升高多是路由或客户端问题5xx升高多是后端问题分开告警便于快速定位。8.2 发布前校验Ingress必须设置正确的ingressClassName或依赖明确的默认类host、path、pathType与实际访问方式一致规则指向的Service存在且有就绪后端TLS配置引用的Secret存在且证书有效控制器超时注解与后端实际响应时间匹配8.3 证书与治理证书临近到期前告警避免HTTPS突然失败ingressClassName作为Ingress模板的必填项后端就绪和优雅关闭配置好减少发布期偶发502Ingress变更走灰度和验证避免影响同控制器其他域名九、常见误区误区1不分404和502一起处理404是路由未匹配502是后端不可用方向完全不同。误区2一报错就重启Ingress控制器路由未匹配和后端问题重启控制器都无效。误区3忘记ingressClassName漏写且无默认类时规则不被任何控制器接管返回404。误区4pathType用错Exact要求精确匹配Prefix是前缀匹配用错会导致部分路径404。误区5502时只改路由规则502是后端问题改路由无效要查Endpoint和端口。误区6忽略后端就绪导致的偶发502滚动发布时后端未就绪或未优雅关闭会产生偶发502。误区7证书到期无告警TLS证书到期会让HTTPS突然失败需提前告警。误区8把云LB的错误当成控制器的云LB在控制器之前也会返回错误码要区分来源。十、面试怎么说60秒版本Ingress报错我先看错误码分流。404是请求到了控制器但没匹配到规则查host、path、pathType、ingressClassName和规则指向的Service。502或503是规则命中但后端不可用查Service的就绪Endpoint和端口和Service排查衔接。504是后端超时查后端响应时间和超时配置。控制器日志是决定性证据能看出是没匹配、上游无响应还是超时。修复只改一个字段并验证不盲目重启控制器。最后按host和path分层监控4xx和5xx。3分钟场景版本假设新上线域名一直404旧域名正常后端Pod都在跑。我先在集群内直接访问后端Service返回200说明后端正常问题在路由层。看新Ingress发现CLASS是none、ADDRESS为空而旧Ingress有nginx类且有ADDRESS。查IngressClass集群里有nginx但没有默认类说明新Ingress漏写了ingressClassName规则没被控制器接管请求落到默认后端返回404。我只给新Ingress补上ingressClassName为nginx不动host、path和后端apply后Ingress分到ADDRESS、控制器接管、访问从404变200。这样我能区分是路由配置问题而不是应用故障也不会用重启控制器这种无关动作去掩盖。十一、延伸问答1. 404和502最本质的区别404是请求没匹配到转发规则或规则无后端问题在路由层502是匹配到了但后端不可用问题在后端。2. Ingress的ADDRESS为空说明什么通常说明没有控制器接管这条Ingress常见于ingressClassName错误或缺失、控制器未运行。3. pathType的Exact和Prefix有什么区别Exact要求路径精确相等Prefix按路径前缀匹配。用错会导致部分请求404。4. 502一定是应用崩了吗不一定。可能是无就绪Endpoint、端口不符、后端拒绝连接也可能是发布期就绪抖动。5. 504怎么处理先区分是后端真的慢还是控制器超时配置过小前者优化后端或扩容后者调整超时注解。6. 为什么直接访问Service能通但Ingress不通说明后端正常问题在Ingress路由层如host、path、IngressClass或控制器。7. 证书问题会报什么TLS握手失败或证书错误和404、502不同要查Ingress的tls配置、引用的Secret和证书有效期。8. 不同Ingress控制器行为一样吗不完全一样。错误码边界、注解、默认后端和日志格式因控制器而异要以实际控制器文档为准。小结Ingress报错先看错误码404查路由502/503查后端504查超时。Ingress只是规则控制器才是执行者规则要被正确的控制器接管。ingressClassName错误或缺失会让规则悬空返回404。502要和Service排查衔接查就绪Endpoint和端口。控制器日志是定位断点的决定性证据。直接访问后端Service可快速区分是路由还是后端问题。修复只改一个字段并验证不盲目重启控制器。长期治理覆盖IngressClass约定、证书告警、分层状态码监控和发布校验。下一篇预告下一篇进入PVC Pending与挂载失败。我们会沿着StorageClass、PV绑定、CSI、拓扑和权限区分制备失败、绑定冲突和挂载错误并整理一份存储故障决策树。参考资料Kubernetes官方文档IngressKubernetes官方文档Ingress ControllersKubernetes官方文档ServiceKubernetes官方文档EndpointSlicesKubernetes官方文档Debug ServicesKubernetes官方文档Liveness, Readiness and Startup ProbesKubernetes官方文档DNS for Services and PodsKubernetes官方文档Ingress APIKubernetes官方文档IngressClassingress-nginx官方文档