kgateway 模块化 Deployer（EP-11376）设计解析：打造可复用的网关 Helm 渲染与部署框架-育师

API网关
云原生
微服务

【免费下载链接】kgateway

The Cloud-Native API Gateway and AI Gateway

项目地址：https://gitcode.com/gh_mirrors/kg/kgateway

作为云原生 API 网关与 AI 网关，kgateway 的核心能力之一是根据用户声明的Gateway、GatewayClass与GatewayParameters资源，自动渲染并下发一组代理工作负载（Envoy Deployment、Service、ServiceAccount、ConfigMap 等）到 Kubernetes 集群。负责这一能力的组件被称为Deployer。本文围绕设计文档 design/11376-modular-deployer.md（EP-11376）展开，剖析 kgateway 如何将 Deployer 从"与网关 Helm 渲染实现深度耦合的内部包"重构为"可公开复用、可扩展的公共子模块"。读完本文，你将理解 Deployer 的现状耦合点、HelmValuesGenerator/HelmConfig等核心抽象的引入动机与使用方式、GatewayParameters 合并逻辑的可复用设计，以及渲染到集群落地的完整调用链。

一、背景：Deployer 承担了什么职责

在 kgateway 中，Deployer 负责自动化部署两类工作负载：

Gateway（网关）：为每个Gateway渲染并部署 Envoy 代理实例；
Inference Pool（推理池）：为 AI/LLM 推理工作负载（如 vLLM）渲染并部署 endpoint picker 等辅助组件。

设计文档明确指出，改造前的 Deployer 实现与其内部表示形式深度耦合：它强依赖网关（Gateway）、网关参数（GatewayParameters）、关联 Helm chart values 的内部表示，而 inference pool 扩展则被当作一种"特例"处理——但其实现仍然大量借用了最初为网关开发的那套抽象。

这种耦合带来的直接后果是：

渲染网关/推理池 chart 的逻辑被硬编码在 Deployer 内部，无法被其他组件（或外部项目）复用；
生成的 helm values 存放在包内不可见的helmConfig中，无法在包外访问或二次处理；
只要想部署一种新的组件类型，就必须修改 Deployer 本身，而不是以插件式方式扩展。

从当前仓库的源码布局可以印证这一改造的结果：设计落地后，公共可复用部分位于 pkg/deployer 目录，而网关专属的实现则收敛到 pkg/kgateway/deployer 目录，二者通过接口解耦。

二、设计目标与非目标

EP-11376 明确列出了本次改造的四个目标：

将 Deployer 与网关/推理池 Helm chart 渲染的实现细节解耦——渲染逻辑不再硬编码在 Deployer 内；
将 Deployer 变成公共子模块以便复用——从internal/deployer提升为公开的pkg/deployer；
支持任意的 GatewayParameters 扩展——第三方可以通过自定义HelmValuesGenerator注入自己的渲染逻辑；
让 GatewayParameters 合并逻辑可供复用——将深度合并（deep merge）算法从内部实现提炼为公开函数。

同时，设计也划定了明确的非目标（Non-Goals）：

不复用 kgateway controller 与 inference extensions controller：本次只改造 Deployer 本身，不试图统一两套控制器；
不支持单个 Deployer 实例管理多个 chart：一个 Deployer 实例仍然只对应一个 Helm chart；
不做 Helm chart 渲染的优化：渲染性能优化不在本次范围内。

这些边界保证了改动范围可控，也说明模块化关注的是"职责拆分与接口开放"，而非功能扩展。

三、改造前：Deployer 的现状与耦合点

设计文档用一张架构图（design/resources/deployer-current-implementation.png）刻画了改造前的实现结构：

改造前 kgateway Deployer 的实现结构与耦合点

图中六个要素说明了当时的职责划分：

Deployer：对外暴露一组渲染函数（GetObjsToDeploy、GetEndpointPickerObjs）和部署函数（DeployObjs）。它通过硬编码逻辑和配置（第 4 点的 Inputs）来自动决定自己是部署网关还是推理池；两类组件的 values 渲染与 chart 渲染都是internal/deployer包内的实现细节，包外不可见；
helmConfig：存放GetObjsToDeploy与GetEndpointPickerObjs调用过程中生成的 helm values，仅限包内访问；
Chart：对 Helm chart（helm 模块）的引用；
Inputs：一组用于配置 Deployer 的选项，包括控制面 xDS 配置、inference extension 配置、镜像仓库配置等，渲染 chart 时使用； 5、6.Controllers：通过 Deployer 渲染 kgateway chart 与 inference extension chart，然后把变更同步到 Kubernetes 集群。

可以看到，"渲染什么 chart、生成什么 values"和"如何部署对象"全部挤在同一个包里，任何新组件类型的引入都会迫使修改 Deployer 本体。

四、改造后：模块化的公共 Deployer 子模块

改造后的架构见设计文档的另一张图（design/resources/deployer-proposed-changes.png）：

改造后模块化 Deployer 的架构设计

Deployer 移入pkg/deployer包，接口收敛为两个核心方法：GetObjsToDeploy（渲染 chart）与DeployObjs（同步对象到集群）；
Inputs 移入pkg/deployer包：它是 Deployer 的直接依赖，创建 Deployer 实例必须提供；
Chart 的加载职责转移：chart 不再在 Deployer 工厂函数内加载，而是由controllerBuilder负责；
HelmValuesGenerator 成为通用接口：负责为 chart 生成 helm values。网关参数（第 7 点）与 inference extension（第 8 点）的实现在internal/deployer包中（落地到当前仓库后位于 pkg/kgateway/deployer）；
HelmConfig 变为公共结构体：用于存放网关与推理扩展 chart 的 helm values，以支持网关参数 helm values 生成的复用；
pkg/deployer/GatewayParameters模块：让 kgateway 的默认配置参数可供复用； 7、8.Helm values renderer：由controllerBuilder实例化并注入 Deployer 实例； 9、10.Controllers：继续通过 Deployer 渲染两类 chart 并同步到集群。

对比改造前后的图可以清楚看到：渲染相关的一切细节（values 怎么算、chart 是什么）都从 Deployer 内部"抽出来"，变成由外部注入的依赖。Deployer 本身只保留"用给定 values 渲染 chart → 得到对象 → 下发到集群"这条通用流水线。

五、核心抽象一：HelmValuesGenerator——渲染职责的注入点

HelmValuesGenerator是本次改造最关键的新抽象，定义在 pkg/deployer/helm_values_generator.go：

type HelmValuesGenerator interface { // GetValues 返回用于渲染动态供给资源（如 Gateway）的 helm values。 // 如果返回 nil，说明该对象是自管理的（self-managed），不应供给任何资源。 GetValues(ctx context.Context, obj client.Object) (map[string]any, error) // GetCacheSyncHandlers 返回 HelmValuesGenerator 控制器的缓存同步处理器 GetCacheSyncHandlers() []cache.InformerSynced }

两个方法的语义非常明确：

GetValues：对某个client.Object（目前可以是Gateway）执行查找、合并等操作，得出最终 helm values。返回 nil 是一个关键约定——它表示对象是自管理的，Deployer 不应为其供给任何资源。这一约定直接支持了GatewayParameters.Spec.SelfManaged语义：当用户声明selfManaged: {}时，kgateway 不会自动部署代理（见 pkg/kgateway/deployer/gateway_parameters.go 中kgatewayParameters.GetValues的实现）；
GetCacheSyncHandlers：Deployer 侧控制器启动时需要等待这些 informer 同步完成，保证渲染时拿到的 GatewayParameters、GatewayClass 是新鲜的。

同一文件还定义了可选的扩展接口ObjectPostProcessor：

type ObjectPostProcessor interface { // PostProcessObjects 在 helm 渲染之后、部署之前对渲染出的对象做后处理。 // 返回值可能包含新增对象（如 PodDisruptionBudget、HorizontalPodAutoscaler）。 PostProcessObjects(ctx context.Context, obj client.Object, rendered []client.Object) ([]client.Object, error) }

这正是设计目标 3"支持任意的 GatewayParameters 扩展"的实现落点：网关专属的GatewayParameters生成器实现了该接口，在渲染完成后把GatewayParametersOverlays以**战略合并补丁（strategic merge patch）**的形式叠加到 Deployment、Service、ServiceAccount 等对象上（实现见 pkg/deployer/strategicpatch/strategicpatch.go，可叠加 PDB/HPA/VPA 并追加新对象）。

为了让第三方能彻底替换渲染逻辑，网关侧的GatewayParameters生成器还提供了WithHelmValuesGeneratorOverride(generator)方法：一旦设置了 override，Deployer 就会完全委托给它，包括缓存同步与后处理（见 pkg/kgateway/deployer/gateway_parameters.go）。这意味着社区或企业用户完全可以写一个自己的HelmValuesGenerator，注入到 Deployer 中，从而实现"任意 GatewayParameters 扩展"。

六、核心抽象二：HelmConfig 与 Inputs 的公共化

6.1 HelmConfig：渲染 values 的公共数据结构

改造后HelmConfig成为pkg/deployer的公共结构体（pkg/deployer/values.go）：

type HelmConfig struct { Gateway *HelmGateway `json:"gateway,omitempty"` }

HelmGateway则是 Gateway 渲染所需全部 values 的容器，字段覆盖了 Helm chart 模板需要的所有维度，按用途可分为几组：

命名与归属：name、gatewayName、gatewayNamespace、gatewayClassName、gatewayAnnotations、gatewayLabels、nameOverride、fullnameOverride；
部署与服务：replicaCount、ports、service、strategy；
ServiceAccount：serviceAccount；
Pod 模板：extraPodAnnotations、extraPodLabels、imagePullSecrets、podSecurityContext、nodeSelector、affinity、tolerations、startupProbe、readinessProbe、livenessProbe、extraVolumes、gracefulShutdown、terminationGracePeriodSeconds、topologySpreadConstraints、priorityClassName；
容器配置：sdsContainer（SDS 边车）、istioContainer（istio-proxy 边车）、istio（Istio 集成开关）；
Envoy 容器：logFormat、logLevel、componentLogLevel、image、resources、securityContext、extraArgs、env、extraVolumeMounts；
bootstrap：dnsResolver、enableReadinessProbeProxyProtocol；
xDS 与统计：xds（host/port/TLS）、stats（含基于 Envoy StringMatcher 的inclusionList/exclusionList统计匹配器）。

这些字段与 Helm chart 模板一一对应。以 pkg/kgateway/helm/envoy/templates/deployment.yaml 为例，模板中直接消费$gateway.replicaCount、$gateway.strategy、$gateway.extraPodAnnotations、$gateway.ports、$gateway.gracefulShutdown、$gateway.istio.enabled等值。HelmConfig公共化之后，任何需要生成这些 values 的代码都可以直接构造并复用，这也是"网关参数 helm values 生成可复用"目标的数据基础。

6.2 Inputs：创建 Deployer 的环境信息

Inputs在 pkg/deployer/gateway_parameters.go 中定义：

type Inputs struct { Dev bool IstioAutoMtlsEnabled bool ControlPlane ControlPlaneInfo ImageInfo *ImageInfo CommonCollections *collections.CommonCollections GatewayClassName string WaypointGatewayClassName string }

其中ControlPlaneInfo携带XdsHost、XdsPort、XdsTLS、XdsTlsCaPath——代理启动时连接控制面 xDS 的地址与 TLS 信息；ImageInfo携带Registry、Tag、PullPolicy，用于渲染镜像。从源码结构可以推断，Inputs是 Deployer 与其依赖环境之间的"上下文对象"，将 xDS 配置、镜像配置、Istio 自动 mTLS 开关等集中传递，避免每个渲染器各自去查。

值得注意的是，pkg/deployer/gateway_parameters.go还沉淀了默认网关参数的完整定义（defaultGatewayParameters），这相当于把"kgateway 默认值"作为公共资产暴露出来。从源码可以看到一组有代表性的默认值：

Service 类型为LoadBalancer；
TerminationGracePeriodSeconds: 60，且默认开启优雅停机（GracefulShutdown，sleep 10s）；
readiness/startup 探针指向/ready端口 8082；
Envoy 容器LogLevel: info，DNS resolverUdpMaxQueries: 100；
安全的容器 SecurityContext：RunAsNonRoot: true、RunAsUser: 10101、AllowPrivilegeEscalation: false、ReadOnlyRootFilesystem: true，并Drop: ["ALL"]；
Stats 默认启用，RoutePrefixRewrite: "/stats/prometheus?usedonly"；
Istio 集成（istio-proxy）镜像固定为docker.io/istio/proxyv2，默认 tag 为DefaultIstioProxyImageTag = "1.31.0"。

此外，GetInMemoryGatewayParameters提供了内置参数的优先级判定：当ClassName等于WaypointClassName时返回 waypoint 专属参数（ClusterIP Service、追加 mesh port、io.istio.dataplane-mode: ambient标签、关闭 zTunnel DNS 解析等），否则返回默认网关参数。这个优先级行为有对应的单元测试覆盖（pkg/deployer/gateway_parameters_test.go），测试用例明确验证了"waypoint class 优先、默认参数兜底"的四种组合。

七、GatewayParameters 合并逻辑：merge.go 的复用能力

设计目标 4 要求"GatewayParameters 合并逻辑可供复用"。这一目标落地为 pkg/deployer/merge.go 中的公开合并函数族，核心入口是：

func DeepMergeGatewayParameters(dst, src *kgateway.GatewayParameters)

合并规则在设计上非常讲究，体现了"默认值 + 用户覆盖"的语义：

SelfManaged 短路：若src.Spec.SelfManaged != nil，直接将 dst 置为 self-managed 并清空Kube字段，跳过所有 kube 字段的合并（因为自管理网关下这些字段无意义）；
nil 即保留：src为 nil 或src.Spec.Kube == nil时直接使用 dst，不做任何修改；
逐维度深合并：Deployment、EnvoyContainer、SdsContainer、PodTemplate、Service、ServiceAccount、Istio、Stats、OmitDefaultSecurityContext各自有专门的深合并函数；
指针/标量用覆盖：MergePointers与MergeComparable遵循"src 非 nil/非零则取 src，否则保留 dst"；
Map 用并集：DeepMergeMaps将 src 的所有条目并入 dst（ExtraLabels、ExtraAnnotations、NodeSelector 等）；
Slice 用追加：DeepMergeSlices对 nil src 保留 dst、对空 src 清空、否则追加——但需要按键唯一的列表（如 sysctls）使用按键合并（deepMergeSysctls按名称索引，src 同名值覆盖 dst，避免 Kubernetes 拒绝重复的 sysctl 名）；
存在语义冲突的字段用专用策略：例如 probe 的 Handler 只保留 src 的一个 Action（Exec/HTTPGet/TCPSocket/GRPC 互斥），image的tag与digest联动（指定其一而未指定另一时清空继承值，形成repo:tag或repo@digest的干净语义）。

这一整套合并语义由 pkg/deployer/merge_test.go（约 942 行测试）系统验证，覆盖了"src 覆盖 dst 副本数""src nil 不覆盖""selfManaged 清空 kube"等大量组合场景。

在网关渲染管线中，这套逻辑被kgatewayParameters这样使用（pkg/kgateway/deployer/gateway_parameters.go）：

优先查找Gateway.Spec.Infrastructure.ParametersRef指向的GatewayParameters（须与 Gateway 同 namespace，且 group/kind 必须合法）；
否则回退到GatewayClass.Spec.ParametersRef；
若都未配置，则调用GetInMemoryGatewayParameters生成内存默认参数；
最终执行deployer.DeepMergeGatewayParameters(defaultGwp, gwp)，把用户覆盖叠加到默认值之上，保证镜像 registry/tag 等默认值在未显式覆盖时始终存在。

也就是说，"默认值兜底 + 用户参数覆盖"这套核心语义现在由pkg/deployer公共提供，任何模块（无论是 kgateway 自身的其他控制器，还是第三方复用者）都可以直接调用，无需复制粘贴内部实现。

八、从渲染到落地的完整链路

模块化之后，Deployer 的核心职责收敛为一条清晰的流水线，实现在 pkg/deployer/deployer.go。结合 pkg/kgateway/controller/gw_controller.go 中gatewayReconciler.Reconcile的调用顺序，完整链路如下：

第一步：GetObjsToDeploy——渲染 chart 为对象

func (d *Deployer) GetObjsToDeploy(ctx context.Context, obj client.Object) ([]client.Object, error) { vals, err := d.helmValues.GetValues(ctx, obj) // ① 由注入的 HelmValuesGenerator 计算 values ... objs, err := d.RenderToObjects(rns, rname, vals) // ② 用 values 渲染 chart ... if postProcessor, ok := d.helmValues.(ObjectPostProcessor); ok { objs, err = postProcessor.PostProcessObjects(ctx, obj, objs) // ③ 可选后处理（overlays） } return objs, nil }

①处vals == nil表示自管理对象，直接返回 nil 不供给资源；②处实际调用RenderManifest，其内部使用 Helm 库以ClientOnly模式执行install.Run（pkg/deployer/deployer.go 的RenderManifest）：只做模板渲染、不触碰集群，从根本上避免渲染过程阻塞控制器，并保证函数能快速终止。

第二步：SetNamespaceAndOwnerWithGVK——设置命名空间与属主

对每个渲染出的对象，若是 namespace 作用域资源则补齐 namespace 并设置 controller ownerRef（指向 Gateway 的 GVK），若是集群作用域资源则清空 namespace。设计文档中的"使用 ownerGVK 而非硬编码值"的细节在这里体现为：ownerRef 的 APIVersion/Kind 来自调用方传入的 GVK，避免依赖 client-go 在 List 后丢失 TypeMeta 的问题。

第三步：DeployObjsWithSource——幂等下发

该方法先按资源类型优先级排序（SortByKindPriority：Namespace → ServiceAccount → Secret/ConfigMap → Role/ClusterRole → RoleBinding/ClusterRoleBinding → Service → 其他），确保 RBAC、ServiceAccount、ConfigMap 等基础设施先于 Deployment 等工作负载应用，避免 Pod 在 RBAC 就绪前启动的竞态。

随后对每个对象执行 SSA（Server-Side Apply）补丁逻辑（applyPatchType，force=true，fieldManager 为 controllerName），中间还做了关键的幂等优化：

从缓存读取现有对象并深拷贝，先清空 API Server 会改写的字段（resourceVersion、generation、UID、creationTimestamp、managedFields、status）；
用equality.Semantic.DeepEqual比较新旧对象，完全一致则跳过补丁，减少无效写请求；
特别地，对Service对象做属主校验（validateExistingServiceOwnership）：如果现存的 Service 既没有指向来源对象的 controller ownerRef，也没有匹配的managed-by标签与 gateway-class/gateway-name 标签，则拒绝覆盖，防止误动其他系统创建的 Service。

第四步：PruneRemovedResources——清理过期的 PDB/HPA/VPA

配置变更导致 PodDisruptionBudget、HorizontalPodAutoscaler、VerticalPodAutoscaler 不再出现在期望集合中时，该方法通过gateway.networking.k8s.io/gateway-name标签（并使用SafeGatewayLabelValue截断处理超过 63 字符的 Gateway 名）列出并删除"已不再期望"的资源，避免陈旧资源残留。相关行为有独立测试 pkg/deployer/prune_test.go 覆盖。

最后，gatewayReconciler还会根据渲染出的 Service 回填 Gateway 的status.addresses，并依据渲染结果设置Accepted条件（渲染失败时置InvalidParameters，恢复后回置Accepted）。

九、控制器侧如何注入与编排

控制器侧的装配逻辑在 pkg/kgateway/controller/controller.go 的watchGw中体现得最为直观：

inputs := &deployer.Inputs{ Dev: cfg.Dev, IstioAutoMtlsEnabled: cfg.IstioAutoMtlsEnabled, ControlPlane: cfg.ControlPlane, ImageInfo: cfg.ImageInfo, CommonCollections: cfg.CommonCollections, GatewayClassName: cfg.GatewayClassName, WaypointGatewayClassName: cfg.WaypointGatewayClassName, } gwParams := internaldeployer.NewGatewayParameters(cfg.Client, inputs) if helmValuesGeneratorOverride != nil { gwParams.WithHelmValuesGeneratorOverride(helmValuesGeneratorOverride(inputs)) } d, err := internaldeployer.NewGatewayDeployer( cfg.ControllerName, cfg.Mgr.GetScheme(), cfg.Client, gwParams, deployer.WithManagedBy(wellknown.DefaultManagedByValue), )

关键点在于NewGatewayDeployer（pkg/kgateway/deployer/deployer_factory.go）：

func NewGatewayDeployer(controllerName string, scheme *runtime.Scheme, client apiclient.Client, gwParams *GatewayParameters, opts ...deployer.Option) (*deployer.Deployer, error) { envoyChart, err := LoadEnvoyChart() // chart 加载职责在工厂函数中完成 ... return deployer.NewDeployer( controllerName, scheme, client, envoyChart, gwParams, GatewayReleaseNameAndNamespace, opts...), nil }

这正是设计文档第 3 点"chart 不再在 Deployer 工厂函数内加载，而是成为 controllerBuilder 的职责"的落地形态：LoadEnvoyChart从内嵌的 pkg/kgateway/helm/envoy chart 加载为*chart.Chart，然后作为参数传给通用的deployer.NewDeployer。而GatewayReleaseNameAndNamespace由于 Helm release 只用于模板生成、从不真正安装，返回硬编码的占位名称"release-name-placeholder"。

在gatewayReconciler（pkg/kgateway/controller/gw_controller.go）中，除了上述渲染→下发→剪枝→状态回填流程，还注册了一系列事件处理器：Gateway 的增删改、GatewayClass 变更（联动触发同 class 下所有 Gateway 重排）、GatewayParameters 变更（分别经parametersRef索引与 class 索引找到受影响 Gateway）、以及渲染产物（Deployment/Service/ServiceAccount/ConfigMap）的 owner 反查重排。这些编排逻辑与 Deployer 的渲染细节完全解耦——controller 只面向deployer.Deployer的公开接口编程。

十、测试与验证

模块化的公共接口与合并逻辑都有充分的测试支撑：

pkg/deployer/deployer_test.go（约 2939 行）：覆盖从 Gateway 渲染出 Deployment/ServiceAccount 等对象、helm values 注入、对象属主与命名空间设置、幂等跳过、overlay 应用等核心行为；
pkg/deployer/merge_test.go（约 942 行）：系统验证DeepMergeGatewayParameters及各字段的合并/覆盖/保留语义；
pkg/deployer/gateway_parameters_test.go：验证 waypoint 与默认参数的优先级与端口差异；
pkg/deployer/prune_test.go：验证 PDB/HPA/VPA 的剪枝行为；
集成层面还有 test/deployer/deployer_helm.go 与 test/deployer/internal_helm_test.go，将渲染产物与真实 Helm 模板输出做对比断言。

设计文档同时提到，PoC 实现在PR #11377中完成（文档内给出了对应的 diff 链接）。从当前仓库的代码布局看，该设计已完全落地：公共抽象的接口签名、HelmConfig/Inputs的公共化、WithHelmValuesGeneratorOverride的扩展点，均与文档中的规划一一对应。

十一、设计取舍与后续演进

设计文档的 Alternatives 一节提出了进一步的拆分方向：Deployer 还可以继续拆分为 Applier（应用者）与 Rendered（渲染结果）两组接口及各自的默认实现。从当前源码看，这一方向尚未实施，属于可选的后继演进。

从更宏观的角度看，EP-11376 的模块化带来三个直接收益：

复用性：任何需要"用 Helm chart 渲染资源并下发到 Kubernetes"的组件（包括未来的第三方扩展、新的数据面类型），都可以直接使用pkg/deployer，只需实现HelmValuesGenerator；
可测试性：渲染与部署被接口切分后，可以用内存 chart、fake client 对流水线做细粒度测试，而不必起真实集群；
演进空间：ObjectPostProcessor与WithHelmValuesGeneratorOverride提供了两个不同层级的扩展点——前者做渲染后的对象改写（overlay），后者则允许完全替换 values 生成逻辑，为"任意 GatewayParameters 扩展"留下了清晰的挂钩。

结语

EP-11376 的本质是一次职责边界的重新划分：把"生成 values + 加载 chart + 渲染 + 下发 + 清理"这条通用流水线留在公共的pkg/deployer，把"网关/推理池专属的 values 怎么算"推向由controllerBuilder注入的HelmValuesGenerator实现。正是这种解耦，让 kgateway 的 Deployer 从一个"内部特化工具"进化为"可复用的公共子模块"——对于希望基于 kgateway 构建自定义代理部署逻辑的开发者，理解HelmValuesGenerator、HelmConfig、Inputs与merge.go的合并语义，是接入这套框架的起点。