4. Gateway 资源模型：spec 字段、listeners 配置、gatewayClassName 绑定、addresses 与 ports

Gateway 是 Gateway API 的核心资源，它定义了流量进入集群的入口点。一个 Gateway 资源描述了某个负载均衡器或代理的期望状态，包括它应该监听哪些端口、处理哪些协议、绑定到哪个 GatewayClass，以及是否指定静态地址。本章将深入解析 Gateway 资源模型的四个关键组成部分。

4.1 Gateway 资源整体结构

Gateway 的 spec 字段是声明式配置的核心，它包含以下主要子字段：

4.2 gatewayClassName 绑定

gatewayClassName 是 Gateway 与 GatewayClass 之间的绑定纽带。它指定了该 Gateway 应该由哪个控制器实现。一个有效的 Gateway 必须引用一个已存在的 GatewayClass 资源。

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: my-gateway
  namespace: default
spec:
  gatewayClassName: example-class
  listeners:
  - name: http
    protocol: HTTP
    port: 80

绑定关系决定了 Gateway 的行为特征：

• 实现选择： 控制器根据 gatewayClassName 找到对应的 GatewayClass，并读取其 controllerName 字段。
• 参数传递： GatewayClass 的 parametersRef 可以引用一个自定义参数资源，为 Gateway 提供实现特定的配置。
• 准入控制： 如果引用的 GatewayClass 不存在或已被删除，Gateway 将无法被正常处理。

4.3 listeners 配置详解

listeners 是 Gateway 最核心的配置字段，它是一个数组，每个元素定义了一个独立的监听端点。每个 listener 包含以下关键属性：

4.3.1 协议与端口组合规则

不同的协议对端口有特定的约束：

• HTTP： 通常使用 80 端口，但也可以使用其他端口。
• HTTPS： 通常使用 443 端口，必须配置 TLS。
• TLS： 用于 TLS 透传，必须配置 TLS。
• TCP/UDP： 用于四层负载均衡，不涉及 TLS。

4.3.2 hostname 过滤机制

hostname 字段允许 listener 仅接受特定主机名的流量。当多个 listener 共享同一个端口时，hostname 用于区分流量应该由哪个 listener 处理。

listeners:
- name: foo-http
  protocol: HTTP
  port: 80
  hostname: "foo.example.com"
- name: bar-http
  protocol: HTTP
  port: 80
  hostname: "bar.example.com"

在这个例子中，两个 listener 都监听 80 端口，但通过 hostname 区分：foo.example.com 的请求由 foo-http 处理，bar.example.com 的请求由 bar-http 处理。

4.4 addresses 与 ports 字段

addresses 字段允许用户请求特定的 IP 地址或主机名作为 Gateway 的入口点。这是一个可选字段，如果未指定，则由控制器自动分配。

spec:
  addresses:
  - type: IPAddress
    value: "192.168.1.100"
  - type: Hostname
    value: "gateway.example.com"

addresses 的类型支持：

ports 字段在 Gateway 的 spec 中并不直接存在。端口信息是通过 listeners 数组中的每个 listener 的 port 字段定义的。因此，Gateway 的端口集合是由所有 listener 的端口组合而成的。

4.5 Gateway 资源模型关系图

下面的 SVG 图展示了 Gateway 资源模型的核心组件及其关系：

4.6 完整 Gateway 配置示例

以下是一个包含所有主要字段的完整 Gateway 配置示例：

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: production-gateway
  namespace: infrastructure
spec:
  gatewayClassName: istio-gateway-class
  addresses:
  - type: IPAddress
    value: "10.0.0.100"
  listeners:
  - name: http
    protocol: HTTP
    port: 80
    hostname: "*.example.com"
    allowedRoutes:
      namespaces:
        from: Selector
        selector:
          matchLabels:
            environment: production
  - name: https
    protocol: HTTPS
    port: 443
    hostname: "*.example.com"
    tls:
      mode: Terminate
      certificateRefs:
      - name: example-com-tls
        kind: Secret
    allowedRoutes:
      namespaces:
        from: All
  - name: tcp-passthrough
    protocol: TLS
    port: 8443
    tls:
      mode: Passthrough
    allowedRoutes:
      namespaces:
        from: Same

4.7 Gateway 状态与条件

Gateway 的 status 字段反映了控制器的处理结果，其中 conditions 数组提供了关键的状态信息：

通过检查这些条件，可以快速诊断 Gateway 配置问题。例如，如果 ResolvedRefs 为 False，通常意味着 TLS 证书引用了一个不存在的 Secret。