Kubernetes ingress：NGINX Ingress与annotations

理解 Ingress、IngressClass 与 NGINX Ingress Controller

Ingress 资源本质上是 Kubernetes 集群对外暴露 HTTP/HTTPS 服务的声明式路由规则集合，它本身并不具备网络转发能力。真正监听流量、解析规则并执行反向代理的是 Ingress Controller（如 NGINX Ingress Controller）。在路由模型中，host 定义域名匹配，path 与 pathType（如 Prefix 或 Exact）决定 URI 匹配策略，backend 指向具体的 Service，而 tls 负责证书卸载。现代 Kubernetes 强烈推荐使用 spec.ingressClassName 字段将 Ingress 与特定的控制器绑定，例如 ingressClassName: nginx。这与早期通过 metadata.annotations 添加 kubernetes.io/ingress.class: nginx 的做法有本质区别：前者是原生 API 字段，具备明确的控制器发现机制与生命周期管理；后者仅为注解，已被官方标记为废弃。明确这一边界，是避免多控制器冲突、保证路由精准投递的第一步。

编写一个可用的 NGINX Ingress：从 YAML 到路由

一个符合 networking.k8s.io/v1 规范的 NGINX Ingress YAML 需包含核心路由要素。示例如下：apiVersion: networking.k8s.io/v1

kind: Ingress

metadata:

name: web-ingress

namespace: default

spec:

ingressClassName: nginx

tls:

- hosts: ["app.example.com"]

secretName: app-tls-secret

rules:

- host: app.example.com

http:

paths:

- path: /api

pathType: Prefix

backend:

service:

name: api-svc

port:

number: 80

- path: /

pathType: Prefix

backend:

service:

name: web-svc

port:

number: 8080

该配置中，ingressClassName 指定由 NGINX 控制器处理；tls 声明 HTTPS 终止及证书引用；rules 按域名划分路由；path 配合 pathType: Prefix 实现 /api 前缀匹配，未匹配的 / 请求将转发至 web-svc。backend 明确指定目标 Service 名称与端口号，控制器会据此解析 Endpoints 并生成对应的 upstream 配置。字段间的层级关系直接决定了请求的匹配优先级与转发目标。

掌握 annotations：用 NGINX 注解改变请求行为

Annotations 是附加在 Ingress 元数据中的键值对，NGINX Ingress Controller 会扫描特定前缀（如 nginx.ingress.kubernetes.io/）的注解，并将其转换为底层 NGINX 配置指令。这些注解本质上是字符串，其具体语义完全依赖控制器的实现版本。常见场景包括：使用 nginx.ingress.kubernetes.io/rewrite-target: /$2 配合正则路径实现 URL 重写；通过 nginx.ingress.kubernetes.io/permanent-redirect 执行 301 跳转；利用 nginx.ingress.kubernetes.io/proxy-body-size: 50m 放宽上传限制；或通过 nginx.ingress.kubernetes.io/proxy-read-timeout: 60 调整超时阈值。需注意，注解并非 Kubernetes 标准 API 的一部分，不同控制器对同一注解的解析逻辑可能截然不同。在实际编写时，应严格对照 NGINX Ingress 官方文档的注解列表，避免拼写错误或传入非预期格式的值，否则控制器将忽略该配置或记录解析警告。

验证路由并排查常见问题

路由生效需建立完整的验证链路。首先执行 kubectl get ingressclass 确认控制器存在且状态正常；接着 kubectl get ingress 查看 ADDRESS 列是否已分配外部 IP 或主机名。若地址为空，通常意味着控制器未就绪或未正确匹配 ingressClassName。随后检查 kubectl get svc -n ingress-nginx 及对应 Pod 日志，确认无启动报错。使用 curl -H "Host: app.example.com" http://<INGRESS_IP>/api 模拟请求，观察返回状态码。若返回 404，需核对 pathType 与 Service 的 Endpoints 是否就绪；若 Service 端口与 backend.port.number 不一致，将导致 502 或连接拒绝。对于注解不生效的情况，可通过 kubectl describe ingress 查看 Events 中的警告信息，或检查控制器日志中是否出现 ignoring annotation 提示。HTTPS 验证需确保 tls.secretName 引用的 Secret 包含合法的 tls.crt 与 tls.key，且域名与证书 SAN 匹配。

annotations 使用边界与迁移避坑

Annotations 虽灵活，但存在显著的控制器绑定风险。将 NGINX 专有注解视为 Kubernetes 通用能力会导致迁移成本剧增。例如，旧版 kubernetes.io/ingress.class 注解在多控制器共存时易引发路由抢占；部分正则匹配注解（如 use-regex: true）会全局影响同一 Ingress 下的所有路径，可能引发性能损耗或意外匹配。此外，Kubernetes 社区已明确冻结 Ingress API 的演进，且 NGINX Ingress Controller 项目已宣布于 2026 年进入退役维护阶段。这意味着后续将不再提供核心功能更新与安全补丁。对于新建项目或架构升级，强烈建议同步评估 Kubernetes Gateway API。Gateway API 采用更清晰的资源分层模型（Gateway、HTTPRoute、ReferenceGrant），原生支持多租户、细粒度策略与跨命名空间路由，且已成为 CNCF 标准。在过渡期，应逐步剥离对 NGINX 特定注解的强依赖，优先使用标准 Ingress 字段或转向支持 Gateway API 的控制器，以保障长期的可维护性与生态兼容性。