Kubernetes Ingress详解 (一) (二) (三) (四)

(一) Kubernetes Ingress详解

Ingress 是 Kubernetes 提供的一种 API 对象，用于管理外部访问集群内服务的 HTTP 和 HTTPS 路由规则。它相当于一个反向代理或负载均衡器，能够根据域名、路径等规则将流量分发到不同的 Service。

---

一、Ingress 的核心作用

1. HTTP/HTTPS 路由：基于域名、路径等规则将外部请求路由到不同的 Service。
2. 负载均衡：自动将流量分发到多个 Pod（通过 Service 实现）。
3. SSL/TLS 终止：支持 HTTPS 加密通信（通过 Ingress Controller 实现）。
4. 虚拟主机：一个 Ingress 可以管理多个域名（如 example.com 和 api.example.com）。
5. 路径重写：支持 URL 路径重写（如 /api → /）。

---

二、Ingress 的组成

Ingress 由两部分组成：

1. Ingress 资源：定义路由规则（YAML 文件配置）。
2. Ingress Controller：实际处理 Ingress 规则的组件（如 Nginx Ingress Controller、Traefik、HAProxy 等）。

关键区别：

• Ingress 资源：只是规则定义（类似 Nginx 的 server 和 location 配置）。
• Ingress Controller：实际运行并处理流量的组件（必须部署在集群中）。

---

三、Ingress 的典型使用场景

1. 多域名访问：
   • example.com → Service A
   • api.example.com → Service B
2. 路径路由：
   • /app → Service A
   • /api → Service B
3. SSL/TLS 加密：
   • 自动为 https://example.com 提供 HTTPS 支持。
4. 负载均衡：
   • 将流量分发到多个 Pod（通过 Service 实现）。

---

四、Ingress 的基本配置（YAML 示例）

1. 最简单的 Ingress 规则（单域名）

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-ingress
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /  # 可选：路径重写
spec:
  rules:
  - host: example.com  # 访问域名
    http:
      paths:
      - path: /        # 访问路径
        pathType: Prefix
        backend:
          service:
            name: my-service  # 目标 Service 名称
            port:
              number: 80      # 目标 Service 端口

说明：

• host：访问域名（如 example.com）。
• path：访问路径（如 / 或 /api）。
• backend：目标 Service 和端口。

2. 多域名 + 路径路由

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: multi-ingress
spec:
  rules:
  - host: example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: web-service
            port:
              number: 80
  - host: api.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: api-service
            port:
              number: 80

3. HTTPS 支持（需要 Ingress Controller 支持 TLS）

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: https-ingress
spec:
  tls:
  - hosts:
    - example.com  # 需要配置的域名
    secretName: my-tls-secret  # TLS 证书 Secret 名称（需提前创建）
  rules:
  - host: example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: web-service
            port:
              number: 80

说明：

• tls：配置 HTTPS 支持。
• secretName：TLS 证书 Secret 名称（需提前创建，格式为 tls.crt 和 tls.key）。

---

五、Ingress Controller 的部署

Ingress Controller 是实际处理 Ingress 规则的组件，常见的有：

1. Nginx Ingress Controller（最常用）
2. Traefik
3. HAProxy
4. Istio Ingress Gateway（Service Mesh 场景）

1. 安装 Nginx Ingress Controller（以 kubeadm 集群为例）

kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.8.1/deploy/static/provider/cloud/deploy.yaml

验证安装：

kubectl get pods -n ingress-nginx  # 查看 Ingress Controller Pod
kubectl get svc -n ingress-nginx   # 查看 Ingress Controller Service（通常是 LoadBalancer 或 NodePort）

2. 获取 Ingress Controller 的外部访问地址

• 如果是 LoadBalancer 类型：

  kubectl get svc -n ingress-nginx
  

  输出示例：

  NAME                                 TYPE           CLUSTER-IP      EXTERNAL-IP     PORT(S)                      AGE
  ingress-nginx-controller             LoadBalancer   10.96.123.45    123.45.67.89    80:30080/TCP,443:30443/TCP   1m
  

  外部访问地址：http://123.45.67.89 或 https://123.45.67.89。

• 如果是 NodePort 类型：

  kubectl get svc -n ingress-nginx
  

  输出示例：

  NAME                                 TYPE       CLUSTER-IP      EXTERNAL-IP   PORT(S)                      AGE
  ingress-nginx-controller             NodePort   10.96.123.45    <none>        80:30080/TCP,443:30443/TCP   1m
  

  外部访问地址：http://<NodeIP>:30080 或 https://<NodeIP>:30443。

---

六、Ingress 的高级功能

1. 路径重写：
   • 使用 nginx.ingress.kubernetes.io/rewrite-target 注解（Nginx Ingress Controller）。
   • 示例：

     annotations:
       nginx.ingress.kubernetes.io/rewrite-target: /new-path
     

2. 自定义错误页面：
   • 使用 nginx.ingress.kubernetes.io/default-backend 注解。
3. 速率限制：
   • 使用 nginx.ingress.kubernetes.io/limit-connections 等注解。
4. WebSocket 支持：
   • Nginx Ingress Controller 默认支持 WebSocket。

---

七、Ingress 与 Service 的关系

• Ingress：负责外部访问的路由（基于域名、路径）。
• Service：负责将流量分发到 Pod（ClusterIP、NodePort、LoadBalancer）。
• Pod：实际运行应用的服务实例。

---

八、常见问题

1. Ingress 无法访问？

• 检查 Ingress Controller 是否运行：

  kubectl get pods -n ingress-nginx
  

• 检查 Ingress 规则是否正确：

  kubectl get ingress
  kubectl describe ingress <ingress名>
  

• 检查 Service 是否正常：

  kubectl get svc
  kubectl describe svc <service名>
  

2. 如何配置 HTTPS？

• 需要：
  1. 准备 TLS 证书（tls.crt 和 tls.key）。
  2. 创建 Kubernetes Secret：

     kubectl create secret tls my-tls-secret --cert=tls.crt --key=tls.key
     

  3. 在 Ingress 中配置 tls 字段（参考前面的 YAML 示例）。

3. 如何调试 Ingress？

• 查看 Ingress 日志：

  kubectl logs -n ingress-nginx <ingress-controller-pod名>
  

• 检查 Ingress 规则：

  kubectl get ingress -o yaml
  

---

九、总结

组件	作用
Ingress	定义 HTTP/HTTPS 路由规则（基于域名、路径）
Ingress Controller	实际处理 Ingress 规则（如 Nginx、Traefik）
Service	将流量分发到 Pod
Pod	运行应用的服务实例

典型工作流程：

1. 用户访问 https://example.com。
2. Ingress Controller 接收请求，根据 Ingress 规则路由到 example-service。
3. example-service 将流量分发到后端 Pod。

Ingress 是 Kubernetes 中管理外部访问的核心组件，结合 Ingress Controller 可以实现灵活的路由、负载均衡和 HTTPS 支持。

(二) Ingress Controller 和 Ingress 资源如何协同工作

在 Kubernetes 中，Ingress Controller 和 Ingress 资源 是两个紧密配合的组件，共同实现外部访问集群内服务的路由、负载均衡和 SSL/TLS 终止等功能。它们的关系可以类比为 “规则制定者” 和 “规则执行者”。

---

一、Ingress 资源的作用

Ingress 资源是 Kubernetes 的一个 API 对象，用于定义外部访问集群内服务的规则（类似 Nginx 的 server 和 location 配置）。它本身不处理流量，只是存储路由规则。

Ingress 资源的核心功能

1. 定义路由规则：
   • 根据域名（host）、路径（path）将请求路由到不同的 Service。
   • 支持 HTTP/HTTPS 协议。
2. 支持 SSL/TLS：
   • 可以配置 HTTPS 加密通信（需配合 Ingress Controller 实现）。
3. 路径重写：
   • 支持 URL 路径重写（如 /api → /）。
4. 虚拟主机：
   • 一个 Ingress 可以管理多个域名（如 example.com 和 api.example.com）。

Ingress 资源的典型配置（YAML 示例）

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-ingress
spec:
  rules:
  - host: example.com  # 访问域名
    http:
      paths:
      - path: /        # 访问路径
        pathType: Prefix
        backend:
          service:
            name: my-service  # 目标 Service 名称
            port:
              number: 80      # 目标 Service 端口

说明：

• host：访问域名（如 example.com）。
• path：访问路径（如 / 或 /api）。
• backend：目标 Service 和端口。

---

二、Ingress Controller 的作用

Ingress Controller 是实际处理 Ingress 规则的组件，它负责：

1. 监听 Ingress 资源的变化：
   • 当 Ingress 资源被创建、修改或删除时，Ingress Controller 会自动更新路由规则。
2. 处理外部流量：
   • 接收外部用户的 HTTP/HTTPS 请求，并根据 Ingress 规则路由到对应的 Service。
3. 提供负载均衡：
   • 将流量分发到多个 Pod（通过 Service 实现）。
4. 支持 SSL/TLS 终止：
   • 解密 HTTPS 请求，并将明文流量转发到后端服务（如果需要）。
5. 高级功能：
   • 路径重写、速率限制、WebSocket 支持等（取决于 Ingress Controller 的实现）。

常见的 Ingress Controller

1. Nginx Ingress Controller（最常用）
2. Traefik
3. HAProxy
4. Istio Ingress Gateway（Service Mesh 场景）

---

三、Ingress Controller 和 Ingress 资源的协同工作流程

1. 用户访问外部域名

• 用户访问 https://example.com（假设配置了 HTTPS）。
• 请求首先到达 Ingress Controller 的负载均衡器（如 LoadBalancer 或 NodePort）。

2. Ingress Controller 解析 Ingress 规则

• Ingress Controller 检查所有 Ingress 资源，找到匹配 host: example.com 的规则。
• 根据 path（如 /）将请求路由到对应的 Service（如 my-service）。

3. Ingress Controller 将流量转发到 Service

• Ingress Controller 将请求转发到 my-service（ClusterIP 类型）。
• Service 再将流量负载均衡到后端的 Pod。

4. Pod 处理请求并返回响应

• Pod 处理请求并返回响应。
• Ingress Controller 将响应返回给用户。

协同工作流程图

---

四、关键点总结

组件	作用	是否处理流量
Ingress 资源	定义路由规则（基于域名、路径）	❌ 不处理流量
Ingress Controller	实际处理流量（路由、负载均衡、SSL/TLS）	✅ 处理流量

协同工作的核心逻辑

1. Ingress 资源：存储路由规则（类似 Nginx 的配置文件）。
2. Ingress Controller：监听 Ingress 资源的变化，并动态更新路由规则。
3. 流量处理：
   • 用户请求 → Ingress Controller → 根据 Ingress 规则 → Service → Pod。

---

五、常见问题

1. 如果没有 Ingress Controller，Ingress 资源能工作吗？

• 不能。Ingress 资源只是规则定义，必须依赖 Ingress Controller 才能生效。

2. 如何选择 Ingress Controller？

• Nginx Ingress Controller：功能丰富，社区支持好，适合大多数场景。
• Traefik：轻量级，适合简单场景。
• Istio Ingress Gateway：适合 Service Mesh 架构。

3. 如何调试 Ingress 和 Ingress Controller？

• 检查 Ingress 资源是否正确：

  kubectl get ingress
  kubectl describe ingress <ingress名>
  

• 检查 Ingress Controller 是否运行：

  kubectl get pods -n ingress-nginx  # 以 Nginx Ingress Controller 为例
  

• 查看 Ingress Controller 日志：

  kubectl logs -n ingress-nginx <ingress-controller-pod名>
  

---

六、总结

• Ingress 资源：定义路由规则（类似 Nginx 的配置）。
• Ingress Controller：实际处理流量（路由、负载均衡、SSL/TLS）。
• 协同工作：
  1. 用户访问外部域名 → Ingress Controller 接收请求。
  2. Ingress Controller 根据 Ingress 规则路由到 Service。
  3. Service 将流量分发到 Pod。
  4. Pod 处理请求并返回响应。

最终效果：

• 外部用户可以通过域名（如 example.com）访问集群内的服务。
• Ingress Controller 自动管理路由规则，无需手动配置 Nginx/Apache 等传统反向代理。

(三) Ingress 支持的高级路由规则和注解

Kubernetes Ingress（尤其是基于 Nginx Ingress Controller 的实现）支持多种高级路由规则和注解，可以实现复杂的流量管理、安全控制、性能优化等功能。以下是常见的 高级路由规则 和 关键注解 分类整理：

---

一、高级路由规则

1. 基于路径的路由（Path-based Routing）

• 功能：根据 URL 路径将请求路由到不同的 Service。
• 示例：

  apiVersion: networking.k8s.io/v1
  kind: Ingress
  metadata:
    name: path-based-ingress
  spec:
    rules:
    - host: example.com
      http:
        paths:
        - path: /app       # 匹配 /app 开头的路径
          pathType: Prefix
          backend:
            service:
              name: app-service
              port:
                number: 80
        - path: /api        # 匹配 /api 开头的路径
          pathType: Prefix
          backend:
            service:
              name: api-service
              port:
                number: 80
  

• 关键点：
  • pathType 可选值：
    • Exact：精确匹配（如 /exact 只匹配 /exact）。
    • Prefix：前缀匹配（如 /prefix 匹配 /prefix、/prefix/sub）。
    • ImplementationSpecific：由 Ingress Controller 决定（默认）。

---

2. 基于主机名的路由（Host-based Routing）

• 功能：根据域名将请求路由到不同的 Service（支持多域名）。
• 示例：

  apiVersion: networking.k8s.io/v1
  kind: Ingress
  metadata:
    name: host-based-ingress
  spec:
    rules:
    - host: app.example.com  # 匹配 app.example.com
      http:
        paths:
        - path: /
          pathType: Prefix
          backend:
            service:
              name: app-service
              port:
                number: 80
    - host: api.example.com  # 匹配 api.example.com
      http:
        paths:
        - path: /
          pathType: Prefix
          backend:
            service:
              name: api-service
              port:
                number: 80
  

---

3. 基于 HTTP 方法的路由（Method-based Routing）

• 功能：根据 HTTP 方法（GET/POST/PUT 等）路由请求（需 Ingress Controller 支持）。
• 示例（Nginx Ingress Controller）：

  annotations:
    nginx.ingress.kubernetes.io/server-snippet: |
      if ($request_method = POST) {
        return 403;
      }
  

• 说明：
  • 可以通过 server-snippet 或 location-snippet 注入自定义 Nginx 规则实现方法过滤。

---

4. 基于 Header 的路由（Header-based Routing）

• 功能：根据请求头（如 User-Agent、X-Request-ID）路由请求（需 Ingress Controller 支持）。
• 示例（Nginx Ingress Controller）：

  annotations:
    nginx.ingress.kubernetes.io/configuration-snippet: |
      if ($http_user_agent ~* "bot") {
        return 403;
      }
  

• 说明：
  • 可以通过 configuration-snippet 注入自定义 Nginx 规则实现 Header 匹配。

---

5. 基于 Query 参数的路由（Query Parameter-based Routing）

• 功能：根据 URL 查询参数（如 ?id=123）路由请求（需 Ingress Controller 支持）。
• 示例（Nginx Ingress Controller）：

  annotations:
    nginx.ingress.kubernetes.io/configuration-snippet: |
      if ($arg_id = "123") {
        return 200 "Special ID";
      }
  

• 说明：
  • $arg_<参数名> 是 Nginx 变量，用于匹配查询参数。

---

二、关键注解（Annotations）

1. 自定义错误页面

• 功能：配置自定义的 HTTP 错误页面（如 404、500）。
• 示例：

  annotations:
    nginx.ingress.kubernetes.io/custom-http-errors: "404,500"
    nginx.ingress.kubernetes.io/server-snippet: |
      error_page 404 /custom_404.html;
      error_page 500 /custom_500.html;
      location = /custom_404.html { root /usr/share/nginx/html; internal; }
      location = /custom_500.html { root /usr/share/nginx/html; internal; }
  

---

2. SSL/TLS 配置

• 功能：启用 HTTPS 并配置 TLS 证书。
• 示例：

  annotations:
    nginx.ingress.kubernetes.io/ssl-redirect: "true"  # 强制 HTTPS
  spec:
    tls:
    - hosts:
      - example.com
      secretName: my-tls-secret  # TLS 证书 Secret 名称
  

---

3. 路径重写（Path Rewriting）

• 功能：修改请求的 URL 路径（如 /api → /）。
• 示例：

  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /  # 将 /api 重写为 /
  spec:
    rules:
    - host: example.com
      http:
        paths:
        - path: /api
          pathType: Prefix
          backend:
            service:
              name: api-service
              port:
                number: 80
  

---

4. 速率限制（Rate Limiting）

• 功能：限制请求速率（防刷、DDoS 防护）。
• 示例：

  annotations:
    nginx.ingress.kubernetes.io/limit-connections: "10"  # 最大连接数
    nginx.ingress.kubernetes.io/limit-rps: "5"           # 每秒最大请求数
  

---

5. WebSocket 支持

• 功能：启用 WebSocket 代理（需 Ingress Controller 支持）。
• 示例：

  annotations:
    nginx.ingress.kubernetes.io/websocket-services: "websocket-service"
  

---

6. 自定义 Nginx 配置

• 功能：注入自定义 Nginx 配置（灵活控制流量行为）。
• 示例：

  annotations:
    nginx.ingress.kubernetes.io/server-snippet: |
      add_header X-Custom-Header "Hello";
      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    nginx.ingress.kubernetes.io/location-snippet: |
      proxy_pass http://backend-service;
  

---

7. 负载均衡策略

• 功能：配置负载均衡算法（如轮询、IP Hash）。
• 示例：

  annotations:
    nginx.ingress.kubernetes.io/upstream-hash-by: "$remote_addr"  # IP Hash
  

---

8. 健康检查

• 功能：配置后端服务的健康检查（需 Ingress Controller 支持）。
• 示例：

  annotations:
    nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"  # 后端协议
    nginx.ingress.kubernetes.io/proxy-next-upstream: "error timeout invalid_header"  # 错误时重试
  

---

三、不同 Ingress Controller 的注解差异

Ingress Controller	关键注解示例
Nginx Ingress Controller	nginx.ingress.kubernetes.io/rewrite-target、nginx.ingress.kubernetes.io/server-snippet
Traefik	traefik.ingress.kubernetes.io/rule-type、traefik.ingress.kubernetes.io/service.serversscheme
HAProxy	haproxy.org/load-balance、haproxy.org/forwardfor

注意：不同 Ingress Controller 的注解可能不同，需参考其官方文档。

---

四、总结

类别	功能	示例注解
路由规则	路径、主机、方法、Header、Query 参数路由	nginx.ingress.kubernetes.io/server-snippet
SSL/TLS	HTTPS 加密、证书管理	nginx.ingress.kubernetes.io/ssl-redirect
高级功能	错误页面、路径重写、速率限制、WebSocket	nginx.ingress.kubernetes.io/custom-http-errors
负载均衡	负载均衡策略、健康检查	nginx.ingress.kubernetes.io/upstream-hash-by

核心逻辑：

1. Ingress 资源：定义路由规则（类似 Nginx 的配置）。
2. Ingress Controller：通过注解动态调整流量行为（如重写、限速、WebSocket）。
3. 协同工作：Ingress Controller 解析 Ingress 资源和注解，生成最终的路由逻辑。

适用场景：

• 需要复杂路由（如多域名、路径重写）。
• 需要安全控制（如速率限制、Header 过滤）。
• 需要高级功能（如 WebSocket、自定义错误页面）。

(四) 如何为 Kubernetes Ingress 配置自定义错误页面

在 Kubernetes 中，Ingress 本身不直接支持自定义错误页面（如 404、500 等），但可以通过 Ingress Controller（如 Nginx Ingress Controller）的注解（Annotations）实现。以下是具体配置方法：

---

一、适用场景

• 当访问不存在的路径时返回自定义 404 页面。
• 当服务返回 500 错误时返回自定义错误页面。
• 其他 HTTP 错误码（如 403、502 等）的自定义处理。

---

二、配置方法（以 Nginx Ingress Controller 为例）

1. 准备自定义错误页面

首先需要准备自定义的错误页面文件（如 404.html、500.html），并上传到 Kubernetes 集群中：

# 创建 ConfigMap 存储错误页面（以 404.html 为例）
kubectl create configmap custom-error-pages --from-file=404.html=./404.html

# 查看 ConfigMap
kubectl get configmap custom-error-pages -o yaml

说明：

• 404.html 是自定义的错误页面文件（需提前准备好）。
• 可以同时上传多个错误页面（如 500.html、403.html 等）。

---

2. 在 Ingress 中引用错误页面

在 Ingress 的 YAML 文件中，使用 nginx.ingress.kubernetes.io/custom-http-errors 注解指定需要自定义的错误码，并通过 nginx.ingress.kubernetes.io/server-snippet 注入 Nginx 配置：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-ingress
  annotations:
    # 指定需要自定义的错误码（如 404、500）
    nginx.ingress.kubernetes.io/custom-http-errors: "404,500"
    # 注入 Nginx 配置，将错误页面指向 ConfigMap 中的文件
    nginx.ingress.kubernetes.io/server-snippet: |
      error_page 404 /custom_404.html;
      error_page 500 /custom_500.html;
      location = /custom_404.html {
        root /usr/share/nginx/html;
        internal;
      }
      location = /custom_500.html {
        root /usr/share/nginx/html;
        internal;
      }
spec:
  rules:
  - host: example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: my-service
            port:
              number: 80

关键点：

• nginx.ingress.kubernetes.io/custom-http-errors：指定需要自定义的错误码（逗号分隔）。
• nginx.ingress.kubernetes.io/server-snippet：注入 Nginx 配置，将错误页面指向 ConfigMap 中的文件。

---

3. 将 ConfigMap 挂载到 Ingress Controller 的 Pod 中

由于错误页面需要被 Ingress Controller 的 Nginx 进程访问，需要将 ConfigMap 挂载到 Ingress Controller 的 Pod 中：

# 编辑 Ingress Controller 的 Deployment（以 Nginx Ingress Controller 为例）
kubectl edit deployment -n ingress-nginx ingress-nginx-controller

# 在 spec.template.spec.containers 中添加 volumeMount 和 volume
spec:
  template:
    spec:
      containers:
      - name: nginx-ingress-controller
        volumeMounts:
        - name: custom-error-pages
          mountPath: /usr/share/nginx/html
          readOnly: true
      volumes:
      - name: custom-error-pages
        configMap:
          name: custom-error-pages
          items:
          - key: 404.html
            path: custom_404.html
          - key: 500.html
            path: custom_500.html

说明：

• mountPath: /usr/share/nginx/html：将 ConfigMap 挂载到 Nginx 的默认 HTML 目录。
• items：将 ConfigMap 中的文件映射到 Nginx 的路径（custom_404.html 和 custom_500.html）。

---

4. 验证配置

1. 重新部署 Ingress Controller（如果修改了 Deployment）：

   kubectl rollout restart deployment -n ingress-nginx ingress-nginx-controller
   

2. 访问不存在的路径（如 http://example.com/nonexistent），应该返回自定义的 404 页面。
3. 访问触发 500 错误的服务，应该返回自定义的 500 页面。

---

三、其他 Ingress Controller 的配置方式

不同 Ingress Controller 的配置方式可能不同：

1. Traefik：
   • 使用 traefik.ingress.kubernetes.io/custom-error-pages 注解。
   • 需要准备错误页面文件并挂载到 Traefik 的 Pod 中。
2. HAProxy：
   • 使用 haproxy.org/custom-error-pages 注解。
   • 需要准备错误页面文件并挂载到 HAProxy 的 Pod 中。

建议：

• 如果使用 Nginx Ingress Controller，推荐使用 nginx.ingress.kubernetes.io/custom-http-errors + nginx.ingress.kubernetes.io/server-snippet 的方式。
• 其他 Ingress Controller 可以参考其官方文档。

---

四、常见问题

1. 自定义错误页面不生效？

• 检查 ConfigMap 是否正确挂载到 Ingress Controller 的 Pod 中：

  kubectl exec -it <ingress-controller-pod> -- ls /usr/share/nginx/html
  

  应该能看到 custom_404.html 和 custom_500.html。
• 检查 Ingress 的注解是否正确：

  kubectl get ingress <ingress名> -o yaml
  

  确保 nginx.ingress.kubernetes.io/custom-http-errors 和 nginx.ingress.kubernetes.io/server-snippet 正确配置。

2. 如何支持更多错误码？

在 nginx.ingress.kubernetes.io/custom-http-errors 中添加更多错误码（如 403,502），并在 nginx.ingress.kubernetes.io/server-snippet 中添加对应的 error_page 配置：

annotations:
  nginx.ingress.kubernetes.io/custom-http-errors: "404,500,403,502"
  nginx.ingress.kubernetes.io/server-snippet: |
    error_page 404 /custom_404.html;
    error_page 500 /custom_500.html;
    error_page 403 /custom_403.html;
    error_page 502 /custom_502.html;
    location = /custom_404.html { root /usr/share/nginx/html; internal; }
    location = /custom_500.html { root /usr/share/nginx/html; internal; }
    location = /custom_403.html { root /usr/share/nginx/html; internal; }
    location = /custom_502.html { root /usr/share/nginx/html; internal; }

---

五、总结

步骤	操作
1. 准备错误页面	创建 404.html、500.html 等文件，并上传到 ConfigMap
2. 配置 Ingress	使用 nginx.ingress.kubernetes.io/custom-http-errors 和 nginx.ingress.kubernetes.io/server-snippet 注解
3. 挂载 ConfigMap	将 ConfigMap 挂载到 Ingress Controller 的 Pod 中
4. 验证	访问触发错误的路径，检查是否返回自定义页面

最终效果：

• 访问不存在的路径 → 返回自定义 404 页面。
• 访问触发 500 错误的服务 → 返回自定义 500 页面。
• 其他错误码（如 403、502）也可以类似配置。