Ingress、Gateway API 与外部流量入口

这一节继续解决一个实际问题：

外部用户访问 https://shop.example.com 时，请求如何进入 Kubernetes 集群，并最终到达对应的后端 Pod？

例如，一个集群运行着三个应用：

• shop.example.com：商城前端
• api.example.com：后端 API
• admin.example.com：管理后台

我们希望使用统一的外部入口，根据域名、路径和 HTTPS 配置，把请求转发到不同的应用。

这就涉及三种核心资源：

• Service：提供集群内的服务访问入口。
• Ingress：声明 HTTP/HTTPS 路由规则。
• Gateway API：提供更丰富、职责划分更清晰的流量管理模型。

一、外部请求如何进入 Kubernetes？#

先看一个典型架构：

flowchart TB
    N0["外部用户 / 浏览器<br/>https://shop.example.com"]
    N1["DNS + 外部负载均衡器<br/>域名解析、网络流量进入集群"]
    N2["Ingress Controller / Gateway<br/>处理 HTTP 路由、TLS 和流量转发"]
    N3["Service<br/>选择并访问后端服务端点"]
    N4["后端 Pod<br/>运行真正的业务应用"]
    N0 --> N1
    N1 --> N2
    N2 --> N3
    N3 --> N4

这张图展示的是一种常见部署方式，而不是所有集群的唯一流量路径。

例如，云厂商可能直接使用外部负载均衡器对接 Gateway；某些网关也可能直接转发到端点。具体链路取决于集群部署方式和网络实现。

这里要明确一个重要区别：

Ingress 和 Gateway API 是路由配置 API，不是自动就能运行的代理程序。 要让配置真正生效，需要部署兼容的 Ingress Controller 或 Gateway 实现。

二、Ingress：通过域名和路径路由请求#

Ingress 是 Kubernetes 的一种 API 资源，用于声明 HTTP/HTTPS 路由规则。

例如：

flowchart LR
    N0["shop.example.com/"]
    N1["frontend Service"]
    N2["shop.example.com/api"]
    N3["backend Service"]
    N4["admin.example.com/"]
    N5["admin Service"]
    N0 --> N1
    N2 --> N3
    N4 --> N5

这样，多个应用可以共用一个外部入口，而不必每个应用都独立暴露一个公网 IP。

1. Ingress 的工作原理#

Ingress 本身只描述规则。以 NGINX Ingress Controller 为例：

1. 你创建 Ingress 资源。
2. Controller 监听 Ingress、Service、Secret 等资源变化。
3. Controller 根据配置生成或更新代理规则。
4. 外部请求到达代理后，根据域名和路径选择后端。
5. 请求转发给对应的 Service 或后端端点。

flowchart TB
    N0["外部 HTTP 请求<br/>Host: shop.example.com<br/>Path: /api/orders"]
    N1["Ingress Controller<br/>匹配域名与路径规则"]
    N2["backend Service<br/>转发到可用后端端点"]
    N3["后端 Pod<br/>处理订单请求"]
    N0 --> N1
    N1 --> N2
    N2 --> N3

2. 创建一个 Ingress#

假设你已经有一个名为 frontend 的 Service，端口为 80。

下面的配置将 shop.example.com/ 路由到这个 Service。

1
apiVersion: networking.k8s.io/v1
2
kind: Ingress
3
metadata:
4
  name: shop-ingress
5
spec:
6
  ingressClassName: nginx
7
  rules:
8
    - host: shop.example.com
9
      http:
10
        paths:
11
          - path: /
12
            pathType: Prefix
13
            backend:
14
              service:
15
                name: frontend
16
                port:
17
                  number: 80

关键字段：

注意：nginx 只是示例 IngressClass 名称。你的集群需要安装对应的 Controller，并确保 IngressClass 名称与实际配置一致。

3. PathType 的三种匹配方式#

特别注意：Prefix 不是简单的字符串前缀。例如，/api 不会因为字符串前缀相同就匹配 /apix。

4. 一个入口路由多个应用#

你可以在同一个 Ingress 中配置多个域名或路径：

1
apiVersion: networking.k8s.io/v1
2
kind: Ingress
3
metadata:
4
  name: multi-app
5
spec:
6
  ingressClassName: nginx
7
  rules:
8
    - host: shop.example.com
9
      http:
10
        paths:
11
          - path: /
12
            pathType: Prefix
13
            backend:
14
              service:
15
                name: frontend
16
                port:
17
                  number: 80
18
          - path: /api
19
            pathType: Prefix
20
            backend:
21
              service:
22
                name: backend
23
                port:
24
                  number: 8080
25
    - host: admin.example.com
26
      http:
27
        paths:
28
          - path: /
29
            pathType: Prefix
30
            backend:
31
              service:
32
                name: admin
33
                port:
34
                  number: 80

这个配置表达了路由意图，但是否能正确处理特定请求，还取决于 Controller 的行为及应用本身的路径设计。例如，Ingress 的标准规则不会自动保证 /api 前缀被移除。

三、Ingress Controller：谁真正处理流量？#

这是一个高频考点。

Ingress 是配置对象，Ingress Controller 才是落实规则的组件。

常见实现包括：

• NGINX Ingress Controller
• Traefik
• HAProxy Kubernetes Ingress Controller
• Kong 等网关实现

不同实现支持的功能、注解、流量处理能力及部署方式并不相同。

查看集群是否已经部署相关组件：

1
kubectl get ingressclass
2
kubectl get ingress -A
3
kubectl get pods -A
4
kubectl get svc -A

如果创建了 Ingress，但没有兼容的 Controller 处理它，规则可能不会产生预期效果。

生产环境注意： Kubernetes 社区维护的 ingress-nginx 项目与 F5 NGINX Ingress Controller 是不同项目，不要把它们的部署方式和生命周期混为一谈。选型时应确认项目的维护状态、版本兼容性和安全支持。

四、HTTPS：TLS 证书如何配置？#

生产环境通常不能只提供 HTTP，还需要 HTTPS。

常见架构是由 Ingress Controller 在外部入口终止 TLS，再把请求转发给后端 Service。

flowchart TB
    N0["浏览器<br/>HTTPS 请求"]
    N1["Ingress Controller<br/>验证证书并终止 TLS"]
    N2["Service"]
    N3["Pod"]
    N0 --> N1
    N1 --> N2
    N2 -->|"通常为 HTTP；也可按需求配置后端 TLS"| N3

这里需要区分两段链路：

• 客户端到 Ingress Controller：可以使用 HTTPS。
• Ingress Controller 到后端：可以使用 HTTP，也可以根据安全需求配置 TLS。

如果后端使用 HTTP，客户端与网关之间的流量虽然加密了，但网关到后端的链路并没有因此自动加密。

1. 创建 TLS Secret#

假设你已经拥有证书文件 tls.crt 和私钥文件 tls.key：

1
kubectl create secret tls shop-tls \
2
  --cert=tls.crt \
3
  --key=tls.key

这个 Secret 必须与引用它的 Ingress 位于同一个 Namespace。

2. 配置 Ingress TLS#

1
apiVersion: networking.k8s.io/v1
2
kind: Ingress
3
metadata:
4
  name: shop-ingress
5
spec:
6
  ingressClassName: nginx
7
  tls:
8
    - hosts:
9
        - shop.example.com
10
      secretName: shop-tls
11
  rules:
12
    - host: shop.example.com
13
      http:
14
        paths:
15
          - path: /
16
            pathType: Prefix
17
            backend:
18
              service:
19
                name: frontend
20
                port:
21
                  number: 80

这表示对 shop.example.com 使用 shop-tls 证书。

但配置了 TLS 资源并不代表外部 HTTPS 一定可以访问。你还需要确保：

• 域名解析到正确的入口地址。
• 外部负载均衡器或节点端口可以到达 Controller。
• 证书有效且域名匹配。
• Controller 已加载证书。
• 防火墙允许相关端口。

五、Gateway API：比 Ingress 更丰富的流量管理模型#

Ingress 对常见 HTTP 路由非常实用，但在复杂流量管理场景中，可能需要更多能力，例如：

• 不同团队分别管理基础设施与应用路由。
• 更明确地控制哪些路由可以绑定到哪些网关。
• 管理 HTTP、HTTPS 以及其他协议的流量。
• 实现更细致的路由匹配和流量管理。

Gateway API 是 Kubernetes 面向流量管理的扩展 API 体系。

它的核心对象包括：

• GatewayClass：定义由哪类网关控制器实现。
• Gateway：定义网关监听器、端口、协议等入口配置。
• HTTPRoute：定义 HTTP 请求的匹配和转发规则。

1. 理解 Gateway API 的架构#

flowchart TB
    N0["GatewayClass<br/>指定网关实现"]
    N1["Gateway<br/>配置入口地址、监听端口和协议"]
    N2["HTTPRoute<br/>匹配 Host、Path 等条件"]
    N3["Service / 后端端点<br/>将流量送到业务应用"]
    N0 --> N1
    N1 --> N2
    N2 --> N3

它的一个设计重点是职责分离：

• 平台团队可以管理 GatewayClass 和 Gateway。
• 应用团队可以管理 HTTPRoute。
• 通过路由绑定策略控制不同团队可以使用哪些入口。

这对多团队、多租户集群尤其有价值。

2. HTTPRoute 示例#

以下是一个典型的 Gateway API 路由示例：

1
apiVersion: gateway.networking.k8s.io/v1
2
kind: HTTPRoute
3
metadata:
4
  name: shop-route
5
spec:
6
  parentRefs:
7
    - name: public-gateway
8
  hostnames:
9
    - shop.example.com
10
  rules:
11
    - matches:
12
        - path:
13
            type: PathPrefix
14
            value: /
15
      backendRefs:
16
        - name: frontend
17
          port: 80

这个配置将 shop.example.com/ 的请求路由到 frontend Service。

需要注意：

1. 集群必须安装 Gateway API 所需的 CRD。
2. 必须有兼容的 Gateway Controller。
3. public-gateway 必须存在，并允许该 HTTPRoute 绑定。
4. frontend Service 的端口必须正确。

可以检查：

1
kubectl get gatewayclass
2
kubectl get gateway -A
3
kubectl get httproute -A

Gateway API 是 API 规范和资源体系，不是一个独立代理程序。具体功能支持程度取决于所使用的 Controller 和版本。

六、Ingress 与 Gateway API 如何选择？#

Kubernetes 的 Ingress API 仍然可以用于已有系统，但其功能开发已相对稳定；需要更丰富、可扩展的流量管理能力时，可以评估 Gateway API。

不要为了追求新技术而机械迁移。应结合已有 Controller、运维成本、团队能力及实际功能需求做选择。

七、Ingress 配置正确却无法访问的排查#

建议从外到内排查：

1
# 1. 检查 DNS 解析
2
nslookup shop.example.com
3

4
# 2. 检查 Ingress 规则
5
kubectl get ingress -A
6
kubectl describe ingress shop-ingress
7

8
# 3. 检查 Controller
9
kubectl get pods -A
10
kubectl logs -n <controller-namespace> <controller-pod>
11

12
# 4. 检查后端 Service
13
kubectl get svc frontend
14
kubectl get endpointslices \
15
  -l kubernetes.io/service-name=frontend
16

17
# 5. 检查后端 Pod
18
kubectl get pods -o wide
19
kubectl logs <backend-pod>

常见问题：

排障时，优先确认请求停在哪一层，不要一遇到 404 就修改 CNI，也不要一遇到 502 就直接重启整个集群。