4. Ingress 资源对象详解：Annotations、TLS、路由规则与后端服务映射

Ingress 是 Kubernetes 中管理外部访问集群服务的 API 对象，它本质上是七层负载均衡的路由规则集合。本章深入拆解 Ingress 资源的四个核心组成部分：Annotations（注解）、TLS（传输层安全）、路由规则与后端服务映射。理解这些要素是进行故障还原与配额模型分析的基础。

4.1 Ingress 资源对象结构总览

一个标准的 Ingress YAML 清单包含以下顶层字段，其中 spec 是核心逻辑所在：

4.2 Annotations：控制器行为调优入口

Annotations 是 Ingress 资源中最重要的扩展机制。不同的 Ingress Controller 会识别不同的 annotation 键名，用于覆盖默认行为。以下以 nginx-ingress 为例，列出故障排查中最高频的几类注解：

4.3 TLS 配置：证书绑定与 HTTPS 终止

TLS 段负责将 Secret 中存储的证书与域名绑定，实现 HTTPS 卸载。其结构如下：

spec:
  tls:
  - hosts:
      - api.example.com
    secretName: api-tls-secret
  - hosts:
      - www.example.com
    secretName: www-tls-secret

关键规则：

• Secret 必须与 Ingress 在同一命名空间，且类型为 kubernetes.io/tls，包含 tls.crt 和 tls.key 两个数据项。
• hosts 列表必须与 rules 中的 host 匹配，否则证书无法正确生效。
• 如果未配置 TLS 段，但 rules 中指定了 host，Ingress Controller 默认只监听 80 端口。
• 支持配置多个 TLS 块，每个块绑定不同的域名与证书。

4.4 路由规则与后端服务映射

路由规则是 Ingress 的核心逻辑，它定义了“哪个域名 + 哪个路径 → 哪个 Service + 哪个端口”的映射关系。以下是一个包含多规则、多路径的完整示例：

spec:
  rules:
  - host: api.example.com
    http:
      paths:
      - path: /v1/users
        pathType: Prefix
        backend:
          service:
            name: user-service
            port:
              number: 8080
      - path: /v1/orders
        pathType: Prefix
        backend:
          service:
            name: order-service
            port:
              number: 8080
  - host: web.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: web-frontend
            port:
              number: 80

4.4.1 pathType 匹配模式

4.4.2 后端服务映射规则

• service.name：必须指向同一命名空间下的 Service 资源。
• port.number：指定 Service 的端口号，也可以使用 port.name 引用命名端口。
• 多路径优先级：当多个路径匹配同一请求时，最长匹配优先。例如 /v1/users/detail 优先匹配 /v1/users/detail（Exact）而非 /v1/users（Prefix）。

4.5 核心映射关系 SVG 图

下图展示了 Ingress 资源从外部请求到后端 Pod 的完整映射链路：

4.6 多路径与权重分配（高级场景）

在云原生网关中，Ingress 支持通过 多个 paths 条目 实现同一域名下的流量拆分。虽然原生 Ingress 不直接支持权重，但可以通过以下方式实现类似效果：

• 路径粒度拆分：将不同业务模块映射到不同 Service，如 /api/v1 → service-a，/api/v2 → service-b。
• 通过 Ingress Controller 注解实现灰度：例如 nginx-ingress 的 nginx.ingress.kubernetes.io/canary 系列注解，支持基于 Header、Cookie 或权重的流量分发。
• 多 Ingress 资源共存：同一 host 下可以创建多个 Ingress 资源，由 Controller 合并规则，但需注意规则冲突时的行为（通常后创建者覆盖）。

4.7 常见故障模式速查表