如何让Nginx Ingress Controller在502/503错误时返回自定义维护页面？

要实现后端服务宕机时自动展示自定义维护页面、服务恢复后自动恢复正常服务的需求，可按以下步骤配置：

1. 创建存储自定义错误页面的ConfigMap #

将提供的维护页面HTML存入ConfigMap，便于Nginx Ingress Controller读取：

apiVersion: v1
kind: ConfigMap
metadata:
  name: custom-error-pages
  namespace: <你的命名空间>  # 需与Ingress、Ingress Controller同命名空间，或按需调整
data:
  50x.html: |
    <!doctype html>
    <title>Site Maintenance</title>
    <style>
      body { text-align: center; padding: 150px; }
      h1 { font-size: 50px; }
      body { font: 20px Helvetica, sans-serif; color: #333; }
      article { display: block; text-align: left; width: 650px; margin: 0 auto; }
      a { color: #dc8100; text-decoration: none; }
      a:hover { color: #333; text-decoration: none; }
    </style>

    <article>
        <h1>We&rsquo;ll be back soon!</h1>
        <div>
            <p>Sorry for the inconvenience but we&rsquo;re performing some maintenance at the moment. If you need to you can always <a href="mailto:#">contact us</a>, otherwise we&rsquo;ll be back online shortly!</p>
            <p>&mdash; The Team</p>
        </div>
    </article>

执行命令创建：

kubectl apply -f custom-error-pages-configmap.yaml

2. 配置Nginx Ingress Controller挂载ConfigMap #

修改Ingress Controller的Deployment或DaemonSet（取决于你的部署方式），将ConfigMap挂载到容器内的Nginx可访问路径，比如/usr/share/nginx/html/custom-errors：

找到Ingress Controller的Pod模板部分，添加volume和volumeMounts：

spec:
  template:
    spec:
      volumes:
        - name: custom-error-pages
          configMap:
            name: custom-error-pages
      containers:
        - name: nginx-ingress-controller
          volumeMounts:
            - name: custom-error-pages
              mountPath: /usr/share/nginx/html/custom-errors
              readOnly: true

更新Ingress Controller：

kubectl apply -f nginx-ingress-controller-deployment.yaml

3. 在Ingress资源中添加错误页面映射注解 #

编辑你的应用Ingress资源，添加Nginx Ingress的专属注解，指定502、503错误时跳转的自定义页面：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: your-app-ingress
  namespace: <你的命名空间>
  annotations:
    nginx.ingress.kubernetes.io/custom-http-errors: "502,503"
    nginx.ingress.kubernetes.io/error-page-502: /custom-errors/50x.html
    nginx.ingress.kubernetes.io/error-page-503: /custom-errors/50x.html
spec:
  # 你的Ingress规则配置...
  rules:
    - host: your-app-domain.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: your-app-service
                port:
                  number: 80

执行命令更新Ingress：

kubectl apply -f your-app-ingress.yaml

原理说明 #

• 当后端服务宕机时，Nginx Ingress Controller检测到后端无可用端点，返回502/503状态码，此时会自动读取挂载的ConfigMap中的自定义页面返回给用户。
• 当后端服务恢复正常后，Ingress Controller会自动路由请求到正常服务，无需手动干预。

内容的提问来源于stack exchange，提问作者devops-admin