Ingress NGINX Controller 自定义错误页（Custom Errors）完整指南：从 ConfigMap 配置到自定义 default-backend 实现

Ingress NGINX Controller 自定义错误页Custom Errors完整指南从 ConfigMap 配置到自定义 default-backend 实现【免费下载链接】ingress-nginxIngress NGINX Controller for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/in/ingress-nginx本文以 Ingress NGINX Controller本仓库ingress-nginx官方文档 docs/user-guide/custom-errors.md 为核心骨架系统讲解如何通过custom-http-errors配置启用自定义错误页机制NGINX 在发生指定 HTTP 错误时如何把错误请求转发给default-backend以及如何编写/部署一个能够按客户端Accept头动态返回 HTML、JSON 等不同格式错误页面的自定义后端。读完本文你将掌握该特性的完整配置链路、官方custom-error-pages镜像的内部实现原理以及手动部署、Helm 部署与全集群维护页三种实战方案。一、特性概述错误发生时谁在处理响应默认情况下当 Ingress 后端返回错误如 404、503时NGINX 会直接向客户端返回默认错误页。而启用custom-http-errors后Ingress Controller 会配置 NGINX 将错误请求转发给default-backend由自定义的错误后端根据请求上下文生成最合适的错误响应。该机制的核心依赖 NGINX 的两个指令本仓库模板 rootfs/etc/nginx/template/nginx.tmpl 中均有体现proxy_intercept_errors on;让 NGINX 拦截上游返回的 HTTP 错误响应转而处理error_page指令模板第 494 行附近按配置全局开启第 847、1044 行也有按场景关闭的处理error_page code custom_backend_code;把指定错误码重定向到内部的custom_*location模板第 502 行、第 1405 行。在 docs/user-guide/nginx-configuration/configmap.md 中官方对custom-http-errors的解释是启用哪些 HTTP 状态码应通过error_page指令交给错误后端处理只要设置至少一个状态码同时也会开启处理error_page所必需的proxy_intercept_errors。因此配置该特性时你只需关心把哪些错误码交给错误后端其余联动行为由 Controller 自动完成。二、转发到 default-backend 的 8 个请求头当custom-http-errors启用后NGINX 在发生错误并转发给default-backend时会附加以下请求头来自原文档的完整表格HeaderValueX-CodeHTTP status code returned by the requestX-FormatValue of theAcceptheader sent by the clientX-Original-URIURI that caused the errorX-NamespaceNamespace where the backend Service is locatedX-Ingress-NameName of the Ingress where the backend is definedX-Service-NameName of the Service backing the backendX-Service-PortPort number of the Service backing the backendX-Request-IDUnique ID that identifies the request - same as for backend service这些请求头在 NGINX 模板的CUSTOM_ERRORS定义中逐一生成见 rootfs/etc/nginx/template/nginx.tmpl 附近的custom_*内部 locationlocation custom_{{ $upstreamName }}_{{ $errCode }} { internal; proxy_intercept_errors off; proxy_set_header X-Code {{ $errCode }}; proxy_set_header X-Format $http_accept; proxy_set_header X-Original-URI $request_uri; proxy_set_header X-Namespace $namespace; proxy_set_header X-Ingress-Name $ingress_name; proxy_set_header X-Service-Name $service_name; proxy_set_header X-Service-Port $service_port; proxy_set_header X-Request-ID $req_id; ... rewrite (.*) / break; proxy_pass http://upstream_balancer; }自定义错误后端可以读取这些信息返回最能表达错误的页面。例如如果客户端发送的Accept头是application/json一个精心设计的后端可以返回 JSON 格式的错误载荷而不是 HTML——这正是同一个错误码、多种内容协商的核心价值。⚠️ 重要约束自定义后端必须返回正确的 HTTP 状态码而不是一律返回200。因为NGINX 不会修改自定义 default-backend 返回的响应原文档 Important 说明。也就是说错误码的语义最终由你的后端负责还原——它收到X-Code: 404就应该回写404状态码实现细节见下文官方镜像源码。三、官方参考实现custom-error-pages 镜像原文档明确指出仓库内提供了一个开箱即用的自定义错误后端示例位于images/custom-error-pages本文按仓库根目录相对路径为 images/custom-error-pages。3.1 目录结构与启动入口该镜像基于 Go 编写核心实现位于 images/custom-error-pages/rootfs/main.go从源码可以看出其设计定义了与上表一一对应的请求头常量X-Format、X-Code、X-Original-URI、X-Namespace、X-Ingress-Name、X-Service-Name、X-Service-Port、X-Request-ID用于从 NGINX 转发的请求中读取错误上下文启动时监听:8080端口同时暴露/metricsPrometheus 指标和/healthz健康检查接口支持两个环境变量ERROR_FILES_PATH错误页面文件所在目录默认/wwwDEFAULT_RESPONSE_FORMAT客户端未指定或无法识别的Accept时的默认响应格式默认text/html设置DEBUG环境变量时会把收到的全部X-*请求头原样回写进响应头便于调试排查。3.2 内容协商与文件命名规则errorHandler的核心逻辑是内容协商 文件查找读取X-Format请求头即客户端的Accept为空则使用默认格式多个格式用逗号分隔时取第一个通过mime.ExtensionsByType把 MIME 类型映射为文件扩展名如application/json→.jsontext/html→.html并兼容.htm→.html读取X-Code得到错误码拼接文件路径/www/codeext如/www/404.html降级策略若精确文件如404.html不存在则回退到/www/首位数字xxext如4xx.html保证任意 4xx/5xx 错误都有兜底页面再找不到则返回 404关键一步w.WriteHeader(code)——用从X-Code解析出的状态码原样回写满足前文必须返回正确状态码的硬性要求。镜像预置的错误页面文件位于 images/custom-error-pages/rootfs/www共 8 个文件内容示例404.htmlspanThe page youre looking for could not be found./span404.json{ message: The page youre looking for could not be found }4xx.html/4xx.json任意 4xx 错误的兜底页500.html/500.json500 精确页5xx.html/5xx.json任意 5xx 错误的兜底页镜像的构建方式可参考 images/custom-error-pages/rootfs/Dockerfile多阶段构建先用golang镜像编译出静态二进制nginx-errors再以 distroless 无 root 用户镜像打包最终以nonroot用户运行CMD [/nginx-errors]。四、实战部署一Helm Chart 方式原文档对应的 Helm 示例位于 docs/examples/customization/custom-errors/custom-default-backend.helm.values.yaml核心配置如下controller: config: custom-http-errors: 404,503 defaultBackend: enabled: true image: registry: registry.k8s.io image: ingress-nginx/custom-error-pages tag: v1.2.9sha256:203d3020005dbdd735c1ad51f238d8663b9851399b52cc0c9c9e3f7273b6b299 extraVolumes: - name: custom-error-pages configMap: name: custom-error-pages items: - key: 404 path: 404.html - key: 503 path: 503.html extraVolumeMounts: - name: custom-error-pages mountPath: /www要点解读controller.config.custom-http-errors与手动部署时 ConfigMap 中的键完全一致即只有 404 与 503 会被交给错误后端defaultBackend.enabled: true使 Chart 直接部署官方custom-error-pages镜像作为默认后端通过extraVolumes/extraVolumeMounts把自定义 ConfigMap 挂载到/www即ERROR_FILES_PATH默认目录实现不重新打镜像即可替换错误页内容。别忘了先创建错误页 ConfigMap见 docs/examples/customization/custom-errors/custom-default-backend-error_pages.configMap.yaml其数据结构为data.状态码: 页面内容apiVersion: v1 kind: ConfigMap metadata: name: custom-error-pages data: 404: | !DOCTYPE html html headtitlePAGE NOT FOUND/title/head bodyPAGE NOT FOUND/body /html 503: | !DOCTYPE html html headtitleCUSTOM SERVICE UNAVAILABLE/title/head bodyCUSTOM SERVICE UNAVAILABLE/body /html该 ConfigMap 的键404、503会通过items映射为挂载目录下的404.html、503.html正好命中镜像精确码文件优先的查找规则。五、实战部署二手动 kubectl 部署不使用 Helm 时按 docs/examples/customization/custom-errors/README.md 的步骤操作。5.1 创建自定义 default-backend使用示例清单 docs/examples/customization/custom-errors/custom-default-backend.yaml 创建 Deployment 与 Service$ kubectl create -f custom-default-backend.yaml service nginx-errors created deployment.apps nginx-errors created该清单定义了一个名为nginx-errors的 Deployment副本数 1镜像为registry.k8s.io/ingress-nginx/custom-error-pages容器端口8080和对应的 Service端口80→targetPort: 8080。清单中注释还演示了两个可选能力设置环境变量DEBUG: true可在客户端响应中回显 Controller 转发过来的全部X-*头便于排查通过注释掉的volumeMounts/volumes片段把自定义错误页 ConfigMap 挂载到/www目录。验证部署$ kubectl get deploy,svc NAME DESIRED CURRENT READY AGE deployment.apps/nginx-errors 1 1 1 10s NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE service/nginx-errors ClusterIP 10.0.0.12 none 80/TCP 10s5.2 配置 Ingress Controller如果尚未部署 Ingress-Nginx Controller请先按部署指南完成部署然后依次进行编辑ingress-nginx-controllerDeployment将启动参数--default-backend-service的值改为新创建的错误后端名称例如--default-backend-servicenamespace/nginx-errors原文档示例中该 flag 指向新建的nginx-errors后端编辑ingress-nginx-controllerConfigMap新增键custom-http-errors值为404,503记下 Ingress Controller Service 的 IP$ kubectl get svc ingress-nginx NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE ingress-nginx ClusterIP 10.0.0.13 none 80/TCP,443/TCP 10m注意示例中ingress-nginxService 类型为ClusterIP实际环境可能不同请确保在继续之前能用该 Service 正常访问 NGINX。5.3 用 cURL 验证错误页向 Ingress Controller 发送不带路径的请求命中的是默认后端返回 404 与自定义 HTML$ curl -D- http://10.0.0.13/ HTTP/1.1 404 Not Found Server: nginx/1.13.12 Date: Tue, 12 Jun 2018 19:11:24 GMT Content-Type: */* Transfer-Encoding: chunked Connection: keep-alive spanThe page youre looking for could not be found./span携带Accept: application/json再请求错误后端按内容协商返回 JSON$ curl -D- -H Accept: application/json http://10.0.0.13/ HTTP/1.1 404 Not Found Server: nginx/1.13.12 Date: Tue, 12 Jun 2018 19:12:36 GMT Content-Type: application/json Transfer-Encoding: chunked Connection: keep-alive Vary: Accept-Encoding { message: The page youre looking for could not be found }注意两次响应都保持了404 Not Found状态码——这正是后端必须回写正确状态码约束的直观体现。更进一步可以部署自己的应用与 Ingress然后验证后端返回 503 的场景例如把某个 Deployment 缩容到 0 副本确认响应仍是正确格式。六、从源码看参数解析链路custom-http-errors的完整处理链路贯穿 Controller 的多个模块掌握它可以帮你更精准地排查问题ConfigMap 解析键custom-http-errors在 internal/ingress/controller/template/configmap.go 中定义为常量customHTTPErrors默认值[]int{}见 internal/ingress/controller/config/config.go 附近读取时经filterErrors过滤非法值configmap.go测试用例 configmap_test.go 覆盖了300,400,demo这类含非法项的输入最终得到[]int{300, 400}说明非数字项会被剔除Ingress 级覆盖每个 Ingress/location 也可携带自己的错误码集合见 internal/ingress/controller/controller.go 的loc.CustomHTTPErrors anns.CustomHTTPErrors即 annotations 中提供的注解同样可以按 Ingress 覆盖全局配置而 controller.go 还显示当后端无可用 Endpoints 且该 location 配置了CustomHTTPErrors时请求会按自定义错误逻辑处理模板渲染全局与 location 级错误码分别在 rootfs/etc/nginx/template/nginx.tmpl 与第 1405 行渲染error_page指令并在第 834 行的CUSTOM_ERRORS模板中生成带X-*请求头的内部转发 location模板单元测试 template_test.go 覆盖了错误码集合变化如401,402→402,403、501,502→504,505时模板输出随之更新的场景。七、进阶技巧7.1 完全自研错误后端参考官方镜像images/custom-error-pages/rootfs/main.go即可自己实现一个错误后端只需满足读取上述 8 个X-*请求头至少读取X-Code与X-Format按X-Format内容协商选择 HTML / JSON / 纯文本等展示格式用X-Code指定的状态码原样返回响应这是最容易踩的坑健康检查接口可选但建议暴露/healthz供就绪探针使用。7.2 全集群维护页方案原文档还给出了一个极具实用价值的场景把自定义错误页升级为全集群维护页在计划维护期间阻止用户访问业务服务。具体三步按上文指南为503错误启用自定义错误页将 Controller 启动参数--watch-namespace-selector的值设置为某个不存在的命名空间例如nonexistent-namespace这会阻止 Controller 读取集群中任何命名空间的Ingress资源在 ConfigMap 中设置location-snippet: return 503;让 NGINX 对所有请求一律返回 503 状态码。此时所有请求都会被 503 错误页接管客户端看到的是统一维护页面维护结束后撤销上述配置即可恢复。原文档特别指出维护页以503 Service Unavailable状态码返回给客户端。7.3 按需关闭错误拦截全局配置项disable-proxy-intercept-errors可显式关闭error_page/custom-http-errors联动开启的proxy_intercept_errors字段定义见 internal/ingress/controller/config/config.go默认false。当出现错误响应被意外改写的奇怪现象时可检查是否与此配置相关。八、小结自定义错误页是 Ingress NGINX Controller 提供的、基于标准 NGINX 指令error_pageproxy_intercept_errors的扩展能力。它的完整形态是一个开关ConfigMap 键custom-http-errors全局或 Ingress 注解局部声明哪些状态码交给错误后端一条链路NGINX 拦截错误 → 通过X-Code、X-Format等 8 个请求头携带上下文 → 转发给default-backend一个后端官方custom-error-pages镜像Go 实现按状态码 MIME 类型查找/www下的页面文件原样回写状态码也可自行实现三种落地方式Helm values、手动kubectl部署、以及全集群维护页的组合玩法。掌握这套机制后你可以让集群的每一个错误响应都符合自己的品牌、格式与语义要求同时保持 HTTP 状态码的规范性。【免费下载链接】ingress-nginxIngress NGINX Controller for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/in/ingress-nginx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考