配置 GatewayAPI Gateway

概述

本文档说明在 Envoy Gateway operator 和 EnvoyGatewayCtl 准备就绪后，如何配置 Gateway。
Gateway 定义流量如何进入网关，而配套的 EnvoyProxy 控制底层 Envoy 数据平面的部署方式。

在推荐的工作流程中，本文档位于 Envoy Gateway Operator 之后，Configure GatewayAPI Route 之前。

前提条件

请确保在继续之前已完成以下操作：

阅读 Envoy Gateway Operator，了解基本概念和资源关系
安装 Envoy Gateway operator 并创建 EnvoyGatewayCtl

NOTE

本文档先介绍主要的 Gateway 概念，然后展示如何创建 Gateway。如果您已经熟悉这些概念，可以直接跳转到创建 Gateway 部分。

Gateway 基础知识

什么是 Gateway

Gateway 是流量进入集群的入口点。它定义了外部请求如何被接收并路由到后端服务。Gateway 主要定义：

Listeners：定义网关监听的端口、协议和主机名
GatewayClass：选择哪个 gateway controller 管理该 Gateway
基础设施引用：引用一个 EnvoyProxy，控制底层 Envoy 数据平面的部署方式

Gateway 暴露方式（Service Type）

Service Type 配置网关通过底层 Envoy Service 的暴露方式。共有三种模式：LoadBalancer、NodePort 和 ClusterIP。

在 YAML 中，该设置配置在配套的 EnvoyProxy 资源的
.spec.provider.kubernetes.envoyService.type 字段。

LoadBalancer（推荐）

优点是易用且具备高可用负载均衡能力。
使用 LoadBalancer 需要集群支持 LoadBalancer，可以通过 MetalLB 启用。

使用 MetalLB 时，可以通过服务注解指定静态虚拟 IP。在 Web 控制台中，使用 Service Annotation 字段：

metallb.universe.tf/address-pool: ADDRESS_POOL_NAME
# 或直接指定具体 IP
metallb.universe.tf/loadBalancerIPs: VIP_IP

详情请参见如何在使用 MetalLB 时指定 VIP。

NodePort

优点是不依赖任何外部组件。

但使用 NodePort 有以下缺点：

Kubernetes 会为 NodePort 分配与服务端口不同的端口号，访问时必须使用 NodePort 端口号，而非服务端口
服务可通过集群中任意节点 IP 访问，存在潜在安全风险

如何获取 NodePort 正确端口

在 Gateway 详情页，当 Service Type 为 NodePort 时，监听器列表会显示 NodePort 列，展示分配的端口号。也可以使用如下命令获取：

kubectl get svc -n ${ENVOYGATEWAYCTL_NS} -l gateway.envoyproxy.io/owning-gateway-name=${GATEWAY_NAME} -o=jsonpath="{.items[0].spec.ports[?(@.port==${PORT})].nodePort}"

输出即为 NodePort 端口号。

ClusterIP

如果不需要外部暴露，非常方便。

Listener 配置

Listener 定义网关监听的端口和协议。在 HTTP 或 HTTPS 协议下，不同主机名可视为不同监听器。

不能创建端口、协议或主机名冲突的监听器。

Gateway 中必须至少创建一个监听器。

端口和协议

每个监听器配置端口号和协议。支持的协议有：HTTP、HTTPS、TCP、UDP、TLS。

AllowRouteNS

默认情况下，Routes 只能附加到 Same 命名空间下的 Gateway。若需跨命名空间路由，使用 Allowed Routes Namespace 字段：

Same：允许同命名空间的 Routes 附加到该监听器
All：允许任意命名空间的 Routes 附加到该监听器
Selector：允许符合选择器匹配的命名空间中的 Routes 附加到该监听器

在 ACP 中，项目通过命名空间上的标签标识，例如 cpaas.io/project: <project-name>。如果希望监听器仅被特定项目的 Routes 使用，选择 Selector 并匹配目标命名空间的项目标签。

监听器的 Allowed Routes Namespace 设置与协议共同决定了在路由 Web 控制台发布路由到监听器时可用的监听器列表，详见附加到其他命名空间创建的 gateway。

TLS 配置

对于 HTTPS 和 TLS 协议，需要配置 TLS 设置。

TLS 模式：

TLS 模式	描述	是否需要证书
Terminate	Envoy 终止 TLS，解密流量后转发到后端服务	是，必须选择 TLS 证书
Passthrough	Envoy 直接透传加密的 TLS 流量到后端服务，不解密	否

NOTE

HTTPS 协议仅支持 Terminate 模式
TLS 协议支持 Terminate 和 Passthrough 两种模式
TLS 监听器中，Passthrough 模式支持 TLSRoute
TLS 监听器中，Terminate 模式支持 TCPRoute

证书要求：

默认只能使用同命名空间下创建的 Secret
Secret 类型必须为 kubernetes.io/tls，且包含 tls.crt 和 tls.key 键
跨命名空间使用 Secret，详见使用其他命名空间创建的 Secret

EnvoyProxy（部署配置）

Envoy Gateway 使用 EnvoyProxy 资源控制网关的部署配置。建议为每个 Gateway 创建专用的 EnvoyProxy 资源，并通过 Gateway 的 .spec.infrastructure.parametersRef 字段引用。

通过 Web 控制台使用 EnvoyGatewayCtl 创建的 GatewayClass 创建 Gateway 时，控制台会自动创建同名同命名空间的配套 EnvoyProxy 资源。

通过 YAML 应用创建 Gateway 时，需自行确保 Gateway 的 .spec.infrastructure.parametersRef 与引用的 EnvoyProxy 资源保持一致。

此一对一映射方式提供更好的隔离性和更细粒度的部署配置控制，例如：

副本数
资源限制和请求
节点选择器
服务类型和注解
镜像仓库

镜像仓库

镜像仓库已为您的集群预配置默认值，除非必要，请勿修改。

其他部署配置方式，详见 deployment-mode。

创建 Gateway

通过 Web 控制台

进入 Alauda Container Platform -> Networking -> Gateway -> Gateways
点击 Create Gateway 按钮
在 Create Gateway 页面，选择由您的 EnvoyGatewayCtl 创建的 GatewayClass。在 Envoy Gateway Operator 推荐的默认示例中，该值为 envoy-gateway-operator-cpaas-default。

页面显示以下配置选项：

字段	说明	YAML 路径
Name	Gateway 名称	gateway: `.metadata.name` envoyproxy: `.metadata.name`
GatewayClass	使用哪个 GatewayClass	gateway: `.spec.gatewayClassName`
Service Type	Service Type	envoyproxy: `.spec.provider.kubernetes.envoyService.type`
Service Annotation	服务注解	envoyproxy: `.spec.provider.kubernetes.envoyService.annotations`
Resource Limits	部署资源限制	envoyproxy: `.spec.provider.kubernetes.envoyDeployment.container.resources`
Replicas	部署副本数	envoyproxy: `.spec.provider.kubernetes.envoyDeployment.replicas`
Node Labels	部署节点选择器	envoyproxy: `.spec.provider.kubernetes.envoyDeployment.nodeSelector`
Listener	Listener	gateway: `.spec.listeners`

WARNING

Web 控制台表单仅支持 EnvoyGatewayCtl 创建的 GatewayClasses。其他 GatewayClasses 请使用 YAML 编辑器。

NOTE

使用 EnvoyGatewayCtl 创建的 GatewayClass 时，Web 控制台会自动创建与 Gateway 同名同命名空间的配套 EnvoyProxy 资源。

Listener 配置

创建或编辑监听器时，可以配置以下内容：

字段	说明	YAML 路径
Name	监听器名称	`.spec.listeners[].name`
Port	监听端口号	`.spec.listeners[].port`
Protocol	监听协议。选项：HTTP、HTTPS、TCP、UDP、TLS	`.spec.listeners[].protocol`
Hostname	可选。监听器的主机名	`.spec.listeners[].hostname`
Allowed Routes Namespace	控制哪些命名空间的路由可以附加到该监听器	`.spec.listeners[].allowedRoutes.namespaces.from`

HTTPS 协议配置

选择 HTTPS 协议时：

字段	说明	YAML 路径
Certificates	必填。选择包含 TLS 证书的 Kubernetes Secret	`.spec.listeners[].tls.certificateRefs`

NOTE

HTTPS 协议仅支持 Terminate 模式
HTTPS 监听器必须选择证书
默认只能使用同命名空间创建的 Secret

TLS 协议配置

选择 TLS 协议时：

配置字段

字段	说明	YAML 路径
TLS Mode	选择 TLS 模式。选项：Terminate、Passthrough。默认：Terminate	`.spec.listeners[].tls.mode`
TLS Certificate	仅在 TLS Mode 为 Terminate 时必填。选择包含 TLS 证书的 Secret	`.spec.listeners[].tls.certificateRefs`

TLS 模式详情，见 TLS 配置。

通过 YAML

如果未使用推荐的默认示例，请将 envoy-gateway-operator-cpaas-default 替换为您自己的 GatewayClass。

以下最小示例创建一个 HTTP Gateway 和一个专用的 EnvoyProxy。

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: demo
  namespace: demo
spec:
  infrastructure:
    parametersRef:
      group: gateway.envoyproxy.io
      kind: EnvoyProxy
      name: demo
  gatewayClassName: envoy-gateway-operator-cpaas-default
  listeners:
    - name: http
      port: 80
      protocol: HTTP
      allowedRoutes:
        namespaces:
          from: Same
---
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: EnvoyProxy
metadata:
  name: demo
  namespace: demo
spec:
  provider:
    kubernetes:
      envoyService:
        type: ClusterIP
      envoyDeployment:
        replicas: 1
        container:
          imageRepository: registry.alauda.cn:60080/acp/envoyproxy/envoy
          resources:
            limits:
              cpu: '1'
              memory: 1Gi
            requests:
              cpu: '1'
              memory: 1Gi
    type: Kubernetes

多种监听器类型的完整示例

如果需要更多监听器类型，可使用以下完整示例：

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: demo
  namespace: demo
spec:
  infrastructure:
    parametersRef:
      group: gateway.envoyproxy.io
      kind: EnvoyProxy
      name: demo
  gatewayClassName: envoy-gateway-operator-cpaas-default
  listeners:
    - name: http
      port: 80
      hostname: a.com
      protocol: HTTP
      allowedRoutes:
        namespaces:
          from: Same
    - name: https
      port: 443
      hostname: a.com
      protocol: HTTPS
      allowedRoutes:
        namespaces:
          from: Same
      tls:
        mode: Terminate
        certificateRefs:
          - name: demo-tls
    - name: tls-passthrough
      port: 8443
      hostname: tls.example.com
      protocol: TLS
      allowedRoutes:
        namespaces:
          from: Same
      tls:
        mode: Passthrough
    - name: tls-terminate
      port: 9443
      hostname: secure.example.com
      protocol: TLS
      allowedRoutes:
        namespaces:
          from: Same
      tls:
        mode: Terminate
        certificateRefs:
          - name: demo-tls
    - name: tcp
      port: 8080
      protocol: TCP
      allowedRoutes:
        namespaces:
          from: Same
    - name: udp
      port: 8081
      protocol: UDP
      allowedRoutes:
        namespaces:
          from: Same
---
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: EnvoyProxy
metadata:
  name: demo
  namespace: demo
spec:
  provider:
    kubernetes:
      envoyService:
        type: ClusterIP
      envoyDeployment:
        replicas: 1
        container:
          imageRepository: registry.alauda.cn:60080/acp/envoyproxy/envoy
          resources:
            limits:
              cpu: '1'
              memory: 1Gi
            requests:
              cpu: '1'
              memory: 1Gi
    type: Kubernetes

参考 EnvoyProxy 资源进行部署配置
如有需要，替换 envoy-gateway-operator-cpaas-default 为您自己的 GatewayClass
listeners 定义流量如何进入网关
hostname 影响基于主机名的路由匹配监听器
protocol 决定可附加的路由类型
allowedRoutes 控制允许附加路由的命名空间
tls 配置 HTTPS 和 TLS 监听器的 TLS 终止或透传
EnvoyProxy 名称必须与 .spec.infrastructure.parametersRef.name 匹配
envoyService.type 控制网关暴露方式
除非必要，保持 imageRepository 不变
resources 配置 Envoy 数据平面资源限制和请求
保持 provider.type 为 Kubernetes

查看 Gateway 详情

在 Gateway 详情页，监听器列表显示以下信息：

列名	说明
Name	监听器名称
Protocol	监听器协议（HTTP、HTTPS、TCP、UDP、TLS）
Port	配置的端口号
NodePort	当 Service Type 为 NodePort 时显示，展示访问监听器的分配 NodePort 端口号。

NOTE

当 Gateway Service Type 为 NodePort 时，监听器列表会显示额外的 NodePort 列。访问网关时请使用 NodePort 端口号，而非服务端口。详情见如何获取 NodePort 正确端口。

监听器与路由参考

附加 Route 资源到 Gateway 时，请遵循以下规则。

主机名

监听器中的主机名是同协议监听器的唯一标识。不能在 Gateway 中添加或更新冲突的监听器。

主机名交集规则

请求到达时，会匹配监听器主机名与路由主机名的交集。只有交集中的主机名用于路由流量。

监听器主机名	路由主机名	交集结果	示例
无主机名	无主机名	匹配所有主机	接受任意传入的 Host 头
无主机名	有主机名（如 `api.example.com`）	所有路由主机名	仅匹配 `api.example.com` 的请求
有主机名（如 `api.example.com`）	无主机名	所有监听器主机名	仅匹配 `api.example.com` 的请求
有主机名（如 `api.example.com`）	有完全匹配的主机名	完全匹配的主机名	仅匹配 `api.example.com` 的请求
有通配符（如 `*.example.com`）	有匹配的主机名	匹配具体主机名	匹配 `api.example.com` 或 `web.example.com` 的请求
有主机名（如 `api.example.com`）	有不匹配的主机名	无交集 - 路由状态异常	路由无法处理流量

NOTE

通配符（*）表示后缀匹配。例如，*.example.com 匹配 foo.example.com 和 bar.example.com，但不匹配 example.com。

WARNING

无交集意味着路由状态异常，流量无法处理。

支持的路由类型

每个监听器根据其协议支持不同的路由类型：

监听器协议	支持的路由类型
HTTP	HTTPRoute, GRPCRoute
HTTPS	HTTPRoute, GRPCRoute
TLS（Passthrough 模式）	TLSRoute
TLS（Terminate 模式）	TCPRoute
TCP	TCPRoute
UDP	UDPRoute

配置路由时，确保路由类型与附加的监听器协议匹配。例如，不能将 HTTPRoute 附加到 TCP 监听器。

下一步

Gateway 准备就绪后，继续进行配置 GatewayAPI Route。
如果在路由附加后需要高级流量控制，继续进行配置 GatewayAPI Policy。

#配置 GatewayAPI Gateway

#目录

#概述

#前提条件

#Gateway 基础知识

#什么是 Gateway

#Gateway 暴露方式（Service Type）

#LoadBalancer（推荐）

#NodePort

#如何获取 NodePort 正确端口

#ClusterIP

#Listener 配置

#端口和协议

#AllowRouteNS

#TLS 配置

#EnvoyProxy（部署配置）

#镜像仓库

#创建 Gateway

#通过 Web 控制台

#Listener 配置

#HTTPS 协议配置

#TLS 协议配置

#通过 YAML

#多种监听器类型的完整示例

#查看 Gateway 详情

#监听器与路由参考

#主机名

#主机名交集规则

#支持的路由类型

#下一步

配置 GatewayAPI Gateway

目录

概述

前提条件

Gateway 基础知识

什么是 Gateway

Gateway 暴露方式（Service Type）

LoadBalancer（推荐）

NodePort

如何获取 NodePort 正确端口

ClusterIP

Listener 配置

端口和协议

AllowRouteNS

TLS 配置

EnvoyProxy（部署配置）

镜像仓库

创建 Gateway

通过 Web 控制台

Listener 配置

HTTPS 协议配置

TLS 协议配置

通过 YAML

多种监听器类型的完整示例

查看 Gateway 详情

监听器与路由参考

主机名

主机名交集规则

支持的路由类型

下一步