如何配置Ingress-Nginx仅捕获控制器自身错误而非应用错误？

要实现仅拦截Ingress-Nginx自身产生的错误（如白名单限制的403、未匹配Ingress规则的404、网关类502/503），同时保留上游应用返回的错误页，你可以通过以下两种方式实现：

方法一：基于proxy-intercept-errors的Ingress级控制 #

如果已经全局配置了custom-http-errors，可以通过在单个Ingress资源上禁用上游错误拦截，实现精准控制：

1. 保留全局ConfigMap配置：继续保留custom-http-errors: 403,404,429,503,502，确保控制器自身的错误会触发自定义页。
2. 为需要保留上游错误的Ingress添加注解：在对应的Ingress资源中添加以下annotation，禁止拦截上游返回的错误：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: your-app-ingress
  annotations:
    nginx.ingress.kubernetes.io/proxy-intercept-errors: "off"
spec:
  # ... 你的Ingress规则

原理：proxy-intercept-errors: "off"会让Ingress控制器透传上游应用返回的所有错误码，仅当控制器自身产生错误时（未转发到上游前），才会使用custom-http-errors指定的自定义页。

方法二：自定义全局错误页（不依赖custom-http-errors） #

如果不想全局拦截错误码，可通过配置Nginx原生的error_page并标记为内部访问，仅响应控制器自身的错误：

步骤1：创建自定义错误页ConfigMap #

将你的自定义错误页（如custom_403.html、custom_404.html等）打包成ConfigMap：

kubectl create configmap nginx-custom-errors \
  --from-file=./custom_403.html \
  --from-file=./custom_404.html \
  --from-file=./custom_502.html \
  --from-file=./custom_503.html

步骤2：修改Helm values.yaml配置 #

更新Ingress-Nginx的Helm部署配置，挂载自定义错误页并添加Nginx全局配置片段：

controller:
  # 挂载自定义错误页ConfigMap到控制器Pod
  extraVolumes:
    - name: custom-errors
      configMap:
        name: nginx-custom-errors
  extraVolumeMounts:
    - name: custom-errors
      mountPath: /usr/share/nginx/html/custom_errors
      readOnly: true
  # 添加Nginx全局HTTP配置片段
  config:
    http-snippet: |
      # 映射控制器自身错误到自定义页
      error_page 403 /custom_errors/custom_403.html;
      error_page 404 /custom_errors/custom_404.html;
      error_page 502 /custom_errors/custom_502.html;
      error_page 503 /custom_errors/custom_503.html;

      # 标记这些路径为内部访问，仅允许Nginx自身触发
      location = /custom_errors/custom_403.html {
        root /usr/share/nginx/html;
        internal;
      }
      location = /custom_errors/custom_404.html {
        root /usr/share/nginx/html;
        internal;
      }
      location = /custom_errors/custom_502.html {
        root /usr/share/nginx/html;
        internal;
      }
      location = /custom_errors/custom_503.html {
        root /usr/share/nginx/html;
        internal;
      }

步骤3：确保上游错误透传 #

所有Ingress资源默认proxy-intercept-errors为off，无需额外配置，上游应用返回的错误会直接透传给客户端。

关键原理说明 #

• custom-http-errors会全局开启proxy-intercept-errors: on，导致所有匹配的错误码（无论来自控制器还是上游）都会被拦截替换。
• internal标记的Nginx location仅允许Nginx内部请求访问，上游应用返回的错误无法触发这些路径，从而实现错误来源的区分。

内容的提问来源于stack exchange，提问作者RustyC0der