Envoy Gateway
插件简介
Envoy Gateway是基于Envoy构建的开源Kubernetes API网关，完全遵循Gateway API标准，提供标准化、高性能、可扩展的南北向流量接入与路由管理能力，可替代Ingress作为Kubernetes集群统一流量入口，支撑业务发布、流量治理、安全防护等核心场景。
工作原理
Envoy Gateway采用控制面‑数据面分离架构：
- 控制面：负责解析Gateway API资源，生成并下发Envoy配置，但不直接参与业务流量的转发。
- 数据面：由高性能代理Envoy承载实际业务流量，负责流量接入、TLS 卸载、路由转发、负载均衡等能力。
约束与限制
- 使用Envoy Gateway插件时需要同时确保CoreDNS插件运行正常。
- Envoy Gateway插件安装后将自动创建一个名为enovy-gateway的GatewayClass，卸载后会保留，请不要手动删除。卸载后若需清理GatewayClass，必须在无关联Gateway的前提下手动清除其finalizers再删除，否则重装插件后可能会导致资源消失或功能异常。
- 删除自定义GatewayClass前，需要删除该GatewayClass关联的Gateway。
- 卸载插件不会删除已创建的Gateway资源及该Gateway的相关资源（涉及Deployment、Service、ConfigMap、ServiceAccount），建议在卸载插件前手动清理插件管理的Gateway资源。插件卸载后，删除Gateway时是否同时删除相关资源会由Envoy Gateway的数据面部署模式决定，在插件默认配置下，删除Gateway会同时删除其关联资源。
- 在CCE Standard集群中，Envoy Gateway插件对接独享型ELB时，插件控制器Pod（和Gateway同命名空间且同名）所在节点以及该节点上的其他容器无法使用ELB的私网地址访问路由。
- 插件配置完成后，其关联的ELB配置将持久化在插件的ConfigMap中。随后，插件实例通过内置的监听机制（Watch）实时捕获ConfigMap的变更，并自动将最新配置同步至插件内部。因此，插件更新负载均衡配置后，通常需要数十秒后生效。
- 在IPv4/IPv6双栈集群中，更新插件时如果将插件配置从IPv4协议版本+共享型ELB变更为IPv4/IPv6双栈协议+独享型ELB，会导致现有的存量Gateway更新失败。 请在操作前确认当前无正在运行的存量Gateway。
注意事项
Envoy Gateway是CCE服务基于开源社区软件适配集成的精选插件，暂未纳入云服务SLA保障范围，建议您评估业务风险后按需使用。如使用中遇到问题，可通过社区或工单获取支持。
安装插件
- 登录CCE控制台，单击集群名称进入集群。
- 在左侧导航栏中选择“插件中心”，在右侧找到Envoy Gateway插件，单击“安装”。
- 在安装插件页面，根据需求选择“规格配置”，调整插件实例数和资源配额。
实例数为1时插件不具备高可用能力，当插件实例所在节点异常时可能导致插件功能无法正常使用，请谨慎选择。
- 设置插件支持的“参数配置”。
- 插件安装的命名空间：选择Envoy Gateway组件运行的命名空间。
- 协议版本：选择协议版本，仅IPv4/IPv6双栈集群支持。
- 负载均衡配置：插件默认不会自动创建负载均衡器，后续创建Gateway对象时将使用以下配置自动创建负载均衡器。自动创建的负载均衡实例按需计费。
负载均衡配置如下：
表1 ELB配置 ELB类型
配置
独享型ELB配置
独享型ELB支持网络型（TCP/UDP/TLS）、网络型（TCP/UDP/TLS）&应用型类型（HTTP/HTTPS）。
- 弹性规格：适用于业务用量波动较大的场景，按实际使用量收取每小时使用的容量费用。v1.21.10-r10、v1.23.8-r10、v1.25.3-r10及以上版本集群支持使用弹性规格。
- 可用区：可以选择在多个可用区创建负载均衡实例，提高服务的可用性。如果业务需要考虑容灾能力，建议选择多个可用区。
- 实例名称：请填写ELB名称。
- 企业项目：该参数仅对开通企业项目的企业客户账号显示。企业项目是一种云资源管理方式，企业项目管理服务提供统一的云资源按项目管理，以及项目内的资源管理、成员管理。
- 资源标签：通过为资源添加标签，可以对资源进行自定义标记，实现资源的分类。您可以在TMS中创建“预定义标签”，预定义标签对所有支持标签功能的服务资源可见，通过使用预定义标签可以提升标签创建和迁移效率。
网络配置
- 前端子网：用于分配ELB实例对外服务的IP地址。
- 后端子网：用于与后端服务建立连接的IP地址。
- 弹性公网IP：选择“自动创建”时，可配置公网带宽的计费方式及带宽大小。
共享型ELB配置
- 实例名称：请填写ELB名称。
- 企业项目：该参数仅对开通企业项目的企业客户账号显示。企业项目是一种云资源管理方式，企业项目管理服务提供统一的云资源按项目管理，以及项目内的资源管理、成员管理。
- 资源标签：通过为资源添加标签，可以对资源进行自定义标记，实现资源的分类。您可以在TMS中创建“预定义标签”，预定义标签对所有支持标签功能的服务资源可见，通过使用预定义标签可以提升标签创建和迁移效率。
网络配置
弹性公网IP：选择“自动创建”时，可配置公网带宽的计费方式及带宽大小。
- AI推理网关：开启后，将额外部署Envoy AI Gateway组件，支持大语言模型（LLM）的智能路由、协议转换及多后端模型统一接入。
- 全局限流功能：该功能依赖一个Redis服务作为全局存储，且Redis服务需要高可用，并保证插件与Redis网络连接畅通，您可以采用自建Redis服务或者选用云数据库。
开启后，支持集群级全局限流与缓存共享，实现流量精准控制并减轻后端负载；但会引入网络通信延时，且Redis宕机可能导致网关请求异常或限流功能失效。
- 设置插件实例的部署策略。
设置多可用区部署或节点亲和策略时，需保证集群中存在满足调度策略的节点且拥有足够的资源，否则插件实例将无法运行。
表2 插件调度配置 参数
参数说明
多可用区部署
- 优先模式：优先将插件的Deployment实例调度到不同可用区的节点上，如集群下节点不满足多可用区，插件实例将调度到单可用区下的不同节点。
- 均分模式：插件Deployment实例均匀调度到当前集群下各可用区，增加新的可用区后建议扩容插件实例以实现跨可用区高可用部署；均分模式限制不同可用区间插件实例数相差不超过1，单个可用区资源不足会导致后续其他实例无法调度。
- 强制模式：插件Deployment实例强制调度到不同可用区的节点上，每个可用区下最多运行一个实例。如集群下节点不满足多可用区，插件实例将无法全部运行。节点故障后，插件实例存在无法迁移风险。
节点亲和
容忍策略
容忍策略与节点的污点能力配合使用，允许（不强制）插件的 Deployment 实例调度到带有与之匹配的污点的节点上，也可用于控制插件的 Deployment 实例所在的节点被标记污点后插件的 Deployment 实例的驱逐策略。
插件会对实例添加针对node.kubernetes.io/not-ready和node.kubernetes.io/unreachable污点的默认容忍策略，容忍时间窗为60s。
详情请参见设置容忍策略。
- 完成以上配置后，单击“安装”。
组件说明
| 容器组件 | 说明 | 资源类型 |
|---|---|---|
| envoy | 高性能代理Envoy承载实际流量转发。该组件安装插件时不会部署，而是在创建Gateway后生成。 | Deployment |
| envoy-gateway | 负责解析Gateway API资源、生成并下发Envoy配置。 | Deployment |
| ai-gateway-controller | 使用AI推理网关功能时创建。 一个处理AI流量网关的中心控制器，用于向网关注入AI流量分发的处理逻辑。 | Deployment |
| cceaddon-envoy-gateway-service-mutating-webhook | 一个Kubernetes Mutating Admission Webhook，用于在Service创建/更新时，自动按照预设规则转换annotations。 | Deployment |
| envoy-ratelimit | 使用全局限流功能时，在envoy-gateway组件部署完成后自动创建。 一个基于Redis的高性能、分布式速率限制服务，专门用于在网关层为API请求提供灵活的全局流量控制与过载保护。 | Deployment |
envoy和envoy-ratelimit组件不在插件安装时一次性部署，不继承插件安装时的亲和策略，且严禁手动修改以防功能异常。
自定义Envoy Gateway的数据面部署模式
您可以控制Envoy Gateway的数据面部署模式，选择Envoy Proxy数据面资源（Deployment/Service/SA）的部署命名空间。
修改方式如下：
- 登录CCE控制台，单击集群名称进入集群。
- 单击左侧导航栏的“插件中心”，在右侧找到Envoy Gateway插件，单击“编辑”。
- 单击插件名称上方的“编辑YAML”，修改插件参数custom.config.envoyGateway.provider.kubernetes.deploy.type配置。
- GatewayNamespace（插件默认配置）：Gateway创建后，插件会在Gateway所在命名空间下创建LoadBalancer类型的Service和Envoy Deployment。插件卸载后，删除Gateway也会删除关联的Service和Deployment。
- ControllerNamespace：Gateway创建后，会在插件安装的命名空间创建LoadBalancer类型的Service和Envoy Deployment（命名规则 envoy-Gateway命名空间-Gateway名称-hash字符串）。插件卸载或实例异常的情况下，删除Gateway不会删除关联的Service和Deployment，需要手动清理。
- 单击“提交”。
请不要在Gateway已存在的情况下修改该参数，修改后不会清理已创建的资源，而是会在新的命名空间重新创建资源。
- ELB开启获取客户端IP功能
- 独享型ELB：默认开启获取客户端IP。
- 共享型ELB：需要手动添加注解开启获取客户端IP。
- 登录CCE控制台，单击集群名称进入集群。
- 单击左侧导航栏的“插件中心”，在右侧找到Envoy Gateway插件，单击“编辑”。
- 单击插件名称上方的“编辑YAML”，修改插件参数custom.envoyService.annotations，添加注解 kubernetes.io/elb.transparent-client-ip: 'true'。
共享型ELB开启获取客户端IP后，如果需要关闭，请参考以下步骤：
- 修改插件参数custom.envoyService.annotations中的注解为：kubernetes.io/elb.transparent-client-ip: 'false'。
- 编辑插件后存量Gateway不生效，需要手动修改Gateway关联的Service中的注解：kubernetes.io/elb.transparent-client-ip: 'false'
其中Gateway关联的Service名称命名规则默认与Gateway同名，如果修改了Envoy Gateway的数据面部署模式，则命名规则为“envoy-Gateway命名空间-Gateway名称-hash字符串”。
- 设置服务亲和模式为“节点级别”。
- 登录CCE控制台，单击集群名称进入集群。
- 单击左侧导航栏的“插件中心”，在右侧找到Envoy Gateway插件，单击“编辑”。
- 单击插件名称上方的“编辑YAML”，修改插件参数custom.envoyService.externalTrafficPolicy，配置为Local。
在CCE Turbo集群中，共享型ELB不支持开启获取客户端IP功能，建议使用独享型ELB，外部访问可不经过转发直通容器。
独享型ELB默认开启源地址透传，只需要在安装Envoy Gateway插件时选择独享型ELB，即可获取客户端IP。
相关文档
- 安装插件后，您可以创建网关API为应用提供外部访问，使用更多高级配置，详情请参见通过Envoy Gateway提供服务访问。
- 如果您原先使用NGINX Ingress，可以选择迁移至Envoy Gateway，详情请参见NGINX Ingress迁移至Envoy Gateway。
