# Envoy Gateway #### 插件简介 [Envoy Gateway](https://gateway.envoyproxy.io/)是基于[Envoy](https://www.envoyproxy.io/)构建的开源Kubernetes API网关，完全遵循[Gateway API](https://gateway-api.sigs.k8s.io/)标准，提供标准化、高性能、可扩展的南北向流量接入与路由管理能力，可替代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保障范围，建议您评估业务风险后按需使用。如使用中遇到问题，可通过社区或工单获取支持。 #### 安装插件 1. 登录[CCE控制台](https://console.huaweicloud.com/cce2.0/?#/cce/cluster/list)，单击集群名称进入集群。 2. 在左侧导航栏中选择"插件中心"，在右侧找到**Envoy Gateway**插件，单击"安装"。 3. 在安装插件页面，根据需求选择"规格配置"，调整插件实例数和资源配额。 实例数为1时插件不具备高可用能力，当插件实例所在节点异常时可能导致插件功能无法正常使用，请谨慎选择。 4. 设置插件支持的"参数配置"。 - **插件安装的命名空间**：选择Envoy Gateway组件运行的命名空间。 - **协议版本**：选择协议版本，仅IPv4/IPv6双栈集群支持。 - **负载均衡配置** ：插件默认不会自动创建负载均衡器，后续创建Gateway对象时将使用以下配置自动创建负载均衡器。自动创建的负载均衡实例**按需计费** 。 负载均衡配置如下： 表1ELB配置 | 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：选择"自动创建"时，可配置公网带宽的计费方式及带宽大小。v1.30.14-r100、v1.31.14-r60、v1.32.13-r30、v1.33.12-r10、v1.34.8-r10、v1.35.5-r10、v1.36.2-r0及以上版本支持加入已有的共享带宽。 | | 共享型ELB配置 | - 实例名称：请填写ELB名称。 - 企业项目：该参数仅对开通企业项目的企业客户账号显示。企业项目是一种云资源管理方式，企业项目管理服务提供统一的云资源按项目管理，以及项目内的资源管理、成员管理。 - 资源标签：通过为资源添加标签，可以对资源进行自定义标记，实现资源的分类。您可以在TMS中创建"预定义标签"，预定义标签对所有支持标签功能的服务资源可见，通过使用预定义标签可以提升标签创建和迁移效率。 **网络配置** 弹性公网IP：选择"自动创建"时，可配置公网带宽的计费方式及带宽大小。v1.30.14-r100、v1.31.14-r60、v1.32.13-r30、v1.33.12-r10、v1.34.8-r10、v1.35.5-r10、v1.36.2-r0及以上版本支持加入已有的共享带宽。 | - **AI推理网关**：开启后，将额外部署Envoy AI Gateway组件，支持大语言模型（LLM）的智能路由、协议转换及多后端模型统一接入。 - **全局限流功能** ：该功能依赖一个Redis服务作为全局存储，且Redis服务需要高可用，并保证插件与Redis网络连接畅通，您可以采用自建Redis服务或者选用云数据库。 开启后，支持集群级全局限流与缓存共享，实现流量精准控制并减轻后端负载；但会引入网络通信延时，且Redis宕机可能导致网关请求异常或限流功能失效。 5. 设置插件实例的部署策略。 ![](https://support.huaweicloud.com/usermanual-cce/public_sys-resources/note_3.0-zh-cn.png) 设置多可用区部署或节点亲和策略时，需保证集群中存在满足调度策略的节点且拥有足够的资源，否则插件实例将无法运行。 表2插件调度配置 | 参数 | 参数说明 | |:---|:---| | 多可用区部署 | - 优先模式：优先将插件的Deployment实例调度到不同可用区的节点上，如集群下节点不满足多可用区，插件实例将调度到单可用区下的不同节点。 - 均分模式：插件Deployment实例均匀调度到当前集群下各可用区，增加新的可用区后建议扩容插件实例以实现跨可用区高可用部署；均分模式限制不同可用区间插件实例数相差不超过1，单个可用区资源不足会导致后续其他实例无法调度。 - 强制模式：插件Deployment实例强制调度到不同可用区的节点上，每个可用区下最多运行一个实例。如集群下节点不满足多可用区，插件实例将无法全部运行。节点故障后，插件实例存在无法迁移风险。 | | 节点亲和 | - 不配置：插件实例不指定节点亲和调度。 - 指定节点调度：指定插件实例部署的节点。若不指定，将根据集群默认调度策略进行随机调度。 - 指定节点池调度：指定插件实例部署的节点池。若不指定，将根据集群默认调度策略进行随机调度。 - 自定义亲和策略：填写期望插件部署的节点标签实现更灵活的调度策略，若不填写将根据集群默认调度策略进行随机调度。 同时设置多条自定义亲和策略时，需要保证集群中存在同时满足所有亲和策略的节点，否则插件实例将无法运行。 | | 容忍策略 | 容忍策略与节点的污点能力配合使用，允许（不强制）插件的 Deployment 实例调度到带有与之匹配的污点的节点上，也可用于控制插件的 Deployment 实例所在的节点被标记污点后插件的 Deployment 实例的驱逐策略。 插件会对实例添加针对**node.kubernetes.io/not-ready** 和**node.kubernetes.io/unreachable**污点的默认容忍策略，容忍时间窗为60s。 详情请参见[设置容忍策略](https://support.huaweicloud.com/usermanual-cce/cce_10_0728.html)。 | 6. 完成以上配置后，单击"安装"。 #### 组件说明 表3Envoy Gateway组件 | 容器组件 | 说明 | 资源类型 | |:---|:---|:---| | 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 | ![](https://support.huaweicloud.com/usermanual-cce/public_sys-resources/caution_3.0-zh-cn.png) envoy和envoy-ratelimit组件不在插件安装时一次性部署，**不继承** 插件安装时的亲和策略，且**严禁手动修改**以防功能异常。 #### 自定义Envoy Gateway的数据面部署模式 您可以控制Envoy Gateway的数据面部署模式，选择Envoy Proxy数据面资源（Deployment/Service/SA）的部署命名空间。 修改方式如下： 1. 登录[CCE控制台](https://console.huaweicloud.com/cce2.0/?#/cce/cluster/list)，单击集群名称进入集群。 2. 单击左侧导航栏的"插件中心"，在右侧找到**Envoy Gateway**插件，单击"编辑"。 3. 单击插件名称上方的"编辑YAML"，修改插件参数custom.config.envoyGateway.provider.kubernetes.deploy.type配置。 ![](https://support.huaweicloud.com/usermanual-cce/zh-cn_image_0000002585773824.png "点击放大") - **GatewayNamespace（插件默认配置）**：Gateway创建后，插件会在Gateway所在命名空间下创建LoadBalancer类型的Service和Envoy Deployment。插件卸载后，删除Gateway也会删除关联的Service和Deployment。 - **ControllerNamespace** ：Gateway创建后，会在插件安装的命名空间创建LoadBalancer类型的Service和Envoy Deployment（命名规则 envoy-Gateway命名空间-Gateway名称-hash字符串）。插件卸载或实例异常的情况下，删除Gateway不会删除关联的Service和Deployment，**需要手动清理**。 4. 单击"提交"。 ![](https://support.huaweicloud.com/usermanual-cce/public_sys-resources/caution_3.0-zh-cn.png) 请不要在Gateway已存在的情况下修改该参数，修改后不会清理已创建的资源，而是会在新的命名空间重新创建资源。 #### Envoy Gateway开启获取客户端IP功能 ![](https://support.huaweicloud.com/usermanual-cce/public_sys-resources/caution_3.0-zh-cn.png) ELB在开启/关闭"获取客户端IP"的过程中访问监听器的流量会中断，请谨慎操作。 - [VPC、容器隧道网络模型（CCE Standard集群）] - [云原生网络2.0模型（CCE Turbo集群）] 1. ELB开启获取客户端IP功能 - 独享型ELB：默认开启获取客户端IP。 - 共享型ELB：需要手动添加注解开启获取客户端IP。 1. 登录[CCE控制台](https://console.huaweicloud.com/cce2.0/?#/cce/cluster/list)，单击集群名称进入集群。 2. 单击左侧导航栏的"插件中心"，在右侧找到**Envoy Gateway**插件，单击"编辑"。 3. 单击插件名称上方的"编辑YAML"，修改插件参数custom.envoyService.annotations，添加注解 *kubernetes.io/elb.transparent-client-ip: 'true'* 。 ![](https://support.huaweicloud.com/usermanual-cce/zh-cn_image_0000002661082611.png "点击放大") ![](https://support.huaweicloud.com/usermanual-cce/public_sys-resources/note_3.0-zh-cn.png) 共享型ELB开启获取客户端IP后，如果需要关闭，请参考以下步骤： 1. 修改插件参数custom.envoyService.annotations中的注解为：*kubernetes.io/elb.transparent-client-ip: 'false'*。 2. 插件为1.0.37以下版本时，编辑插件后存量Gateway不生效，还需要手动修改Gateway关联的Service中的注解：*kubernetes.io/elb.transparent-client-ip: 'false'* 。插件为1.0.37及以上版本时，关闭源IP后存量Gateway会自动生效，无需执行此步骤。 ![](https://support.huaweicloud.com/usermanual-cce/zh-cn_image_0000002634277996.png "点击放大") 其中Gateway关联的Service名称命名规则默认与Gateway同名，如果修改了[Envoy Gateway的数据面部署模式]，则命名规则为"envoy-Gateway命名空间-Gateway名称-hash字符串"。 2. 设置服务亲和模式为"节点级别"。 1. 登录[CCE控制台](https://console.huaweicloud.com/cce2.0/?#/cce/cluster/list)，单击集群名称进入集群。 2. 单击左侧导航栏的"插件中心"，在右侧找到**Envoy Gateway**插件，单击"编辑"。 3. 单击插件名称上方的"编辑YAML"，修改插件参数custom.envoyService.externalTrafficPolicy，配置为Local。 ![](https://support.huaweicloud.com/usermanual-cce/zh-cn_image_0000002661242553.png "点击放大") 在CCE Turbo集群中，共享型ELB不支持开启获取客户端IP功能，建议使用独享型ELB，外部访问可不经过转发直通容器。 独享型ELB默认开启源地址透传，只需要在[安装Envoy Gateway插件]时选择独享型ELB，即可获取客户端IP。 #### 相关文档 - 安装插件后，您可以创建网关API为应用提供外部访问，使用更多高级配置，详情请参见[通过Envoy Gateway提供服务访问](https://support.huaweicloud.com/usermanual-cce/cce_10_1147.html)。 - 如果您原先使用NGINX Ingress，可以选择迁移至Envoy Gateway，详情请参见[NGINX Ingress迁移至Envoy Gateway](https://support.huaweicloud.com/usermanual-cce/cce_10_1149.html)。 #### 版本记录 表4Envoy Gateway插件版本记录 | 插件版本 | 支持的集群版本 | 更新特性 | 社区版本 | |:---|:---|:---|:---| | 1.0.35 | v1.30 v1.31 v1.32 v1.33 v1.34 v1.35 | 升级Envoy Gateway版本为v1.7.4 | [1.7.4](https://github.com/envoyproxy/gateway/releases/tag/v1.7.4) | | 1.0.9 | v1.30 v1.31 v1.32 v1.33 v1.34 v1.35 | 新增Envoy Gateway插件 | [1.7.2](https://github.com/envoyproxy/gateway/releases/tag/v1.7.2) |