Skip to content

约 4 分钟阅读

Ingress 与 Gateway API ​

Ingress 描述 HTTP/HTTPS 请求如何按域名和路径转发到 Service。Ingress API 已冻结:它仍是稳定 API,Kubernetes 没有移除计划,但不会继续增加能力。新平台或复杂多团队入口应同时评估 Gateway API;现有 Ingress 不需要仅因“API 冻结”立即迁移。

资源和实现必须同时存在 ​

创建 Ingress 只是在 API 中保存路由意图。集群还必须安装 Ingress Controller,并通过 IngressClass 选择实现。不同 Controller 的注解、证书、流量策略和状态行为并不通用。

截至 2026-10-20,社区项目 kubernetes/ingress-nginx 已进入 2026 年 3 月停止维护后的阶段,不再提供后续漏洞修复。它与 Ingress API、NGINX 软件和其他厂商的 NGINX Controller 是不同对象。存量部署要评估迁移,新建入口应选择仍维护且满足所需能力的实现。

下面假设已安装并配置一个仍维护的 Controller,且现有 IngressClass 名为 public-ingress;需要提前准备 orders namespace、order-api:80 Service 和同命名空间的 orders-tls Secret。Class 名是集群对象名,不是可凭名称自动安装的产品。

yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: order-api
  namespace: orders
spec:
  ingressClassName: public-ingress
  tls:
    - hosts: [orders.example.com]
      secretName: orders-tls
  rules:
    - host: orders.example.com
      http:
        paths:
          - path: /api
            pathType: Prefix
            backend:
              service:
                name: order-api
                port:
                  number: 80

pathType 必须明确:Exact 精确匹配,Prefix 按路径段前缀匹配,ImplementationSpecific 交给 Controller 解释。依赖实现私有正则和注解时,要把兼容性写进升级与迁移计划。

例如 /api 的 Prefix 匹配 /api 和 /api/orders,不匹配 /apix;它也不会自动把 /api 从上游请求里删除。后端若只处理 /health,请求 /api/health 是否要改写,必须由应用路由或实现支持的配置明确决定。

请求链路 ​

Ingress 配置关系与真实请求转发路径

DNS 把域名解析到入口地址,请求到达负载均衡器或代理后按已下发的 host/path 规则选择后端。Ingress rule 和 EndpointSlice 都是配置;请求不会进入这些 API 对象。代理可能经 Service VIP,也可能直接连接端点,具体路径由实现决定。

Ingress 显示地址不代表后端可用。TLS、路由、Service selector、目标端口、EndpointSlice Ready 和应用监听都要独立验证。

bash
kubectl get ingressclass
kubectl get ingress order-api -n orders -o yaml
kubectl describe ingress order-api -n orders
kubectl get svc,endpointslice -n orders
controller_namespace=替换为控制器命名空间
controller_pod=替换为控制器Pod名称
kubectl logs -n "$controller_namespace" "$controller_pod"
entry_ip=替换为入口IP
curl --fail --show-error --max-time 10 -v \
  --resolve "orders.example.com:443:$entry_ip" https://orders.example.com/api/health

--resolve 保留真实 Host 和 TLS SNI,只覆盖连接地址,便于 DNS 切换前测试。使用内部 CA 时通过 --cacert 提供受信任证书链,不把跳过证书校验当作入口验收。

TLS 边界 ​

spec.tls.secretName 引用同 Namespace 的 kubernetes.io/tls Secret。Ingress 只声明使用哪个证书,签发、续期和私钥保护通常由证书控制器或外部密钥系统负责。

检查顺序:

  1. Secret 是否存在,类型和证书链是否正确。
  2. Controller 是否允许读取该 Secret。
  3. 证书域名、有效期和监听器状态是否匹配。
  4. TLS 在入口终止后,后端使用 HTTP、HTTPS 还是 mTLS。

不要把私钥直接写进 Git;Base64 也不提供保密性。

Gateway API 为什么不同 ​

Gateway API 把职责拆成多个对象:

对象主要职责
GatewayClass选择控制器实现和基础设施类型
Gateway地址、监听器、证书和允许挂接的路由范围
HTTPRoute/GRPCRoute应用域名、匹配、后端和流量策略
ReferenceGrant在被引用对象的命名空间授权跨命名空间后端或证书引用

这种角色模型更适合平台团队管理共享入口、应用团队管理自己的路由。Gateway API 仍需要具体 Controller;不同实现支持的标准/实验资源和 conformance profile 必须单独核对。

例如平台在 gateway-system 管入口,应用在 orders 管路由。前提是已经安装匹配版本的 Gateway API CRD、Controller 和 public-gateway-class,并在 gateway-system 准备有效的 orders-tls Secret。下列监听器只接受 orders 命名空间的路由:

yaml
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: public-gateway
  namespace: gateway-system
spec:
  gatewayClassName: public-gateway-class
  listeners:
    - name: https
      hostname: orders.example.com
      protocol: HTTPS
      port: 443
      tls:
        mode: Terminate
        certificateRefs:
          - name: orders-tls
      allowedRoutes:
        namespaces:
          from: Selector
          selector:
            matchLabels:
              kubernetes.io/metadata.name: orders
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: order-api
  namespace: orders
spec:
  parentRefs:
    - name: public-gateway
      namespace: gateway-system
      sectionName: https
  hostnames: [orders.example.com]
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /api
      backendRefs:
        - name: order-api
          port: 80

这里跨命名空间的 Route → Gateway 挂接依靠 parentRefs 与 listener 的 allowedRoutes 双向同意,不需要 ReferenceGrant。同命名空间的 Route → Service 也不需要它;若 Route 改为引用 data 命名空间的 Service,才由 data 的所有者创建 ReferenceGrant 授权。Route 后端端口是 Service 的 port 80,不能误填 Pod 的 8080。

检查 Gateway/listener 的 Accepted、Programmed 以及 Route 各 parent 的 Accepted、ResolvedRefs,并对齐 observedGeneration。状态接受后还要验证证书、请求和业务指标,不能只看 API 创建成功。

迁移而不是重写 ​

从 Ingress 迁移时:

  1. 盘点 IngressClass、注解、TLS、正则、重写、鉴权和流量策略。
  2. 把标准语义映射到 Gateway/HTTPRoute,列出无法直接迁移的私有功能。
  3. 在同一后端上双跑新旧入口,比较状态、证书、路由和真实流量。
  4. 用 DNS 或负载均衡权重小流量切换,设置错误率和延迟停止条件。
  5. 保留旧入口到观察窗口结束,再删除旧规则和私有注解。

常见故障 ​

现象优先检查
Ingress 无地址IngressClass、Controller、云负载均衡器 Events
404host/path/pathType、Controller 默认后端、请求 Host
502/503Service 端口、EndpointSlice、Pod Ready、后端协议
TLS 证书错误Secret、SNI、证书域名、续期控制器
一种 Controller 正常、换实现失败私有注解和 ImplementationSpecific 语义

更完整的组件选型和迁移边界见 云原生扩展生态。

别急,先让缓存热一下。