4、核心资源定义：Gateway 资源对象的 YAML 结构、监听器（Listener）配置、主机名与端口绑定

在 Gateway API 资源配额模型中，Gateway 资源是流量入口的核心抽象。它定义了网络端点（如负载均衡器、Ingress Controller）的行为规范，包括监听协议、端口、主机名绑定以及 TLS 终止策略。本章将深入解析 Gateway 资源的 YAML 结构、监听器配置细节以及主机名与端口的绑定机制。

4.1 Gateway 资源 YAML 结构全景

一个标准的 Gateway 资源由 spec.gatewayClassName、spec.listeners 和 spec.addresses 三大部分组成。以下是一个典型的四层/七层混合网关定义：

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: prod-gateway
  namespace: infra
spec:
  gatewayClassName: acme-lb
  listeners:
  - name: https-app
    protocol: HTTPS
    port: 443
    hostname: "*.example.com"
    tls:
      mode: Terminate
      certificateRefs:
      - name: wildcard-example-tls
    allowedRoutes:
      namespaces:
        from: Selector
        selector:
          matchLabels:
            tier: frontend
  - name: http-api
    protocol: HTTP
    port: 80
    hostname: "api.example.com"
    allowedRoutes:
      namespaces:
        from: All
  addresses:
  - type: IPAddress
    value: 192.168.1.100

4.2 监听器（Listener）配置详解

监听器是 Gateway 资源中最关键的配置单元。每个监听器代表一个独立的网络端点，支持以下核心属性：

4.3 主机名与端口绑定机制

主机名与端口的绑定决定了流量如何被路由到后端服务。Gateway API 采用 监听器级主机名过滤 与 路由级主机名匹配 两层模型：

1. 监听器级过滤：监听器通过 hostname 字段声明其接受的主机名范围。例如 *.example.com 表示该监听器只处理子域名请求。
2. 路由级匹配：HTTPRoute 或 TLSRoute 中的 spec.hostnames 字段进一步精确匹配。路由的主机名必须属于监听器声明的范围。
3. 端口唯一性：同一 Gateway 内，port + protocol 组合必须唯一。不同监听器可以共享同一端口（如 TCP 和 UDP 分别监听 53）。

4.4 监听器配置实战：多协议混合网关

在实际生产环境中，一个 Gateway 通常需要同时暴露 HTTP 和 HTTPS 服务。以下是一个多协议混合网关的配置示例：

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: hybrid-gateway
  namespace: default
spec:
  gatewayClassName: envoy
  listeners:
  - name: http
    protocol: HTTP
    port: 80
    hostname: "*.example.com"
    allowedRoutes:
      namespaces:
        from: All
  - name: https
    protocol: HTTPS
    port: 443
    hostname: "*.example.com"
    tls:
      mode: Terminate
      certificateRefs:
      - name: example-tls
    allowedRoutes:
      namespaces:
        from: Selector
        selector:
          matchLabels:
            tier: web
  - name: tls-passthrough
    protocol: TLS
    port: 8443
    hostname: "secure.example.com"
    tls:
      mode: Passthrough
    allowedRoutes:
      namespaces:
        from: Same

4.5 监听器冲突与优先级规则

当多个监听器存在潜在冲突时，Gateway API 定义了明确的优先级规则：

4.6 监听器状态与健康度

Gateway 资源的 status.listeners 字段提供了每个监听器的运行时状态，用于调试和监控：

status:
  listeners:
  - name: https-app
    supportedKinds:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
    - group: gateway.networking.k8s.io
      kind: GRPCRoute
    conditions:
    - type: Ready
      status: "True"
      reason: Ready
      message: "Listener is ready"
    attachedRoutes: 5
  - name: http-api
    supportedKinds:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
    conditions:
    - type: Ready
      status: "False"
      reason: PortUnavailable
      message: "Port 80 is already in use"

4.7 最佳实践与避坑指南

• 主机名规划：使用通配符 * 时注意层级，*.example.com 匹配 app.example.com 但不匹配 example.com（无子域名）。
• 端口复用：避免在同一 Gateway 中为同一端口配置多个监听器，除非协议不同（如 TCP/UDP）。
• TLS 模式选择：七层路由优先使用 Terminate 模式；四层透传或 mTLS 场景使用 Passthrough。
• 命名空间隔离：通过 allowedRoutes.namespaces.from: Selector 限制路由来源，防止跨命名空间越权访问。
• 状态监控：定期检查 status.listeners[].conditions，确保所有监听器处于 Ready 状态。