4. Ingress 资源基础：API 版本、YAML 结构、路由规则与默认后端

Ingress 是 Kubernetes 中管理集群外部访问集群内服务的 API 对象，它通过定义路由规则将 HTTP/HTTPS 流量转发到对应的 Service。理解 Ingress 资源的 API 版本演进、YAML 结构以及核心的路由规则配置，是掌握 Ingress 控制器的前提。

4.1 Ingress API 版本演进

Kubernetes Ingress API 经历了多个版本的迭代，不同版本支持的字段和功能有所差异。当前主流版本为 networking.k8s.io/v1，该版本在结构上更加严格，废弃了早期版本中的一些模糊字段。

4.2 Ingress YAML 结构解析

一个标准的 Ingress 资源 YAML 包含四个核心部分：apiVersion、kind、metadata 和 spec。其中 spec 内部又分为 ingressClassName、rules 和 defaultBackend 三个主要字段。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-ingress
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
spec:
  ingressClassName: nginx
  rules:
  - host: app.example.com
    http:
      paths:
      - path: /api
        pathType: Prefix
        backend:
          service:
            name: api-service
            port:
              number: 80
  defaultBackend:
    service:
      name: default-service
      port:
        number: 80

4.3 host 与 path 规则详解

路由规则由 host（域名）和 path（路径）两部分组成。Ingress 控制器根据请求的 Host 头部和请求路径，匹配最合适的规则并将流量转发到对应的后端 Service。

4.3.1 host 规则

• 精确匹配： 指定完整域名，如 app.example.com，仅匹配该域名的请求。
• 通配符匹配： 使用 * 作为前缀，如 *.example.com，匹配所有子域名（如 foo.example.com、bar.example.com）。
• 空 host： 不指定 host 字段，匹配所有域名（包括 IP 直接访问）。

4.3.2 path 规则与 pathType

pathType 决定了路径的匹配方式，在 networking.k8s.io/v1 中为必填字段。

4.4 默认后端配置

默认后端（defaultBackend） 是 Ingress 资源的兜底策略。当请求的 Host 或 Path 与所有 rules 都不匹配时，流量会被转发到 defaultBackend 指定的 Service。如果未配置 defaultBackend，则 Ingress 控制器通常会返回 404 状态码。

4.4.1 配置示例

spec:
  defaultBackend:
    service:
      name: default-backend-svc
      port:
        number: 80

4.4.2 典型使用场景

• 自定义 404 页面： 部署一个返回友好 404 页面的 Service，提升用户体验。
• 流量兜底： 将未匹配的流量转发到统一的网关或维护页面。
• 灰度/蓝绿部署辅助： 在迁移期间，将未明确路由的流量指向旧版本服务。

4.5 多规则与多路径配置示例

以下示例展示了一个包含多个 host 和多个 path 的完整 Ingress 配置，适用于微服务架构下的统一入口场景。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: multi-route-ingress
spec:
  ingressClassName: nginx
  rules:
  - host: shop.example.com
    http:
      paths:
      - path: /products
        pathType: Prefix
        backend:
          service:
            name: product-service
            port:
              number: 8080
      - path: /orders
        pathType: Prefix
        backend:
          service:
            name: order-service
            port:
              number: 8080
  - host: admin.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: admin-service
            port:
              number: 80
  defaultBackend:
    service:
      name: fallback-service
      port:
        number: 80

4.6 常见配置陷阱与避坑指南