kgateway 作为 Istio Ambient Waypoint 代理的落地实践：部署、策略与源码原理

• API网关
• 云原生
• 微服务

kgateway 与 Istio service mesh 完全兼容：在 Ambient 模式下，东西向（east-west）流量的 L7 处理由独立的代理组件 waypoint 完成，kgateway 可提供 Istio 自带 waypoint 代理的 drop-in（即插即用）替代方案。本文以仓库 examples/waypoint 下的完整演示为例，讲解如何让 kgateway waypoint 接管网格内服务流量、如何通过 HTTPRoute 与 Istio AuthorizationPolicy 对服务实施精细策略，并结合 waypoint 插件源码 解释其工作原理，读完即可在自己的 Ambient 网格中复现这套方案。

背景：Ambient Mesh 与 Waypoint 代理

Istio Ambient Mesh 将数据平面分为两层：

• ztunnel：负责每个节点的 L4 能力（加密、负载均衡等），以 DaemonSet 形式运行，按命名空间维度捕获流量；
• waypoint：按需部署的 L7 代理，负责 HTTP 处理、策略执行、流量管控等七层能力。

在默认的 Istio 实现中，waypoint 由 Istio 自带的 waypoint 控制器提供。kgateway 则通过自己的 GatewayClass 与控制器，实现了一个功能等价的 waypoint 代理：ztunnel 捕获流量后，会把七层请求交给 kgateway waypoint 处理。因为 kgateway 本身就是基于 Envoy 构建的网关，天然具备完整、可扩展的 L7 能力，因此可以无缝替换 Istio 自带的 waypoint。

这套能力在仓库中有明确的默认值定义：

• GatewayClass 默认名为kgateway-waypoint，定义于 pkg/kgateway/wellknown/controller.go；
• waypoint listener 使用专属协议istio.io/PROXY与端口 15088，常量IstioPROXYProtocol定义于 waypoint_translator.go；
• 端口 15008 为 Istio 保留端口，用于让 sidecar 将 waypoint 纳入可能的通信目标（实际并不承载流量），见 pkg/kgateway/wellknown/deployer.go。

前置条件

在开始部署演示之前，需要满足：

1. Istio 1.24 或更新版本，且已启用 Ambient 模式（dataplane 已切换到 ambient）；
2. 已安装 kgateway（含负责翻译kgateway-waypointGatewayClass 的控制器组件）。

安装并验证 Waypoint 演示

仓库 examples/waypoint 目录下提供了完整的演示资源，下面按步骤执行。

第 1 步：部署测试命名空间

kubectl apply -f examples/waypoint/httpbin-mesh.yaml

该文件（httpbin-mesh.yaml）创建了httpbin命名空间、httpbin 服务与其 Deployment、以及一个用于发送流量的curl客户端 Pod。关键在命名空间上的两个标签：

# ztunnel 将捕获该命名空间下所有服务的流量 istio.io/dataplane-mode: ambient # ztunnel 将把捕获到的流量发送到名为 httpbin-waypoint 的 waypoint istio.io/use-waypoint: httpbin-waypoint

这两个标签是 Ambient 模式的核心接线机制：istio.io/dataplane-mode: ambient让 ztunnel 接管该命名空间的 L4 流量，istio.io/use-waypoint则指名该命名空间使用的 waypoint 代理名称。

第 2 步：部署 kgateway-waypoint Gateway 资源

kubectl apply -f examples/waypoint/waypoint-gw.yaml

该 Gateway 使用 GatewayClasskgateway-waypoint（waypoint-gw.yaml）：

kind: Gateway apiVersion: gateway.networking.k8s.io/v1 metadata: name: httpbin-waypoint namespace: httpbin spec: gatewayClassName: kgateway-waypoint listeners: - protocol: istio.io/PROXY port: 15088 name: mesh allowedRoutes: namespaces: from: Same

该 Gateway 专为处理网格东西向流量而设计：

• gatewayClassName: kgateway-waypoint会触发 kgateway 中专门的 waypoint 翻译器，而非常规的南北向网关翻译流程；
• listener 协议必须为istio.io/PROXY。从源码看，waypoint_translator.go 在buildInboundListener中只识别该协议的 listener：若 Gateway 中没有该协议的 listener，Gateway 会以ListenersNotValid原因拒绝（GatewayConditionAccepted=false）；若存在其他协议的 listener，则该 listener 会被标记为Invalid；
• 端口 15088 是 waypoint 接收 ztunnel 转发流量的约定端口。

第 3 步：对 Service 应用策略

kubectl apply -f examples/waypoint/waypoint-http-route.yaml

这条 HTTPRoute 与常规的网关路由略有不同——它的parentRef指向的是一个Service，而不是Gateway（waypoint-http-route.yaml）：

apiVersion: gateway.networking.k8s.io/v1 kind: HTTPRoute metadata: name: waypoint-add-header namespace: httpbin spec: parentRefs: - name: httpbin group: "" kind: Service rules: - backendRefs: - name: httpbin port: 8000 filters: - type: ResponseHeaderModifier responseHeaderModifier: add: - name: "Traversed-Waypoint" value: "httpbin-waypoint"

这种「以 Service 为 parentRef」的路由挂载方式，是 Gateway API Mesh 工作组的规范（GAMMA Initiative）所定义的，用于实现对网格内流量的细粒度策略挂载。HTTPRoute 挂到某个 Service 上后，所有途经 waypoint 发往该 Service 的请求都会执行这条路由的规则——本例是为响应添加Traversed-Waypoint: httpbin-waypoint头，用于证明 waypoint 已处于数据路径上。

从翻译器源码可以看到，waypoint 的 HTTP 虚拟主机正是通过该机制组合生成的：buildServiceChains 先取出所有挂到该 waypoint 上的 Service（istio.io/use-waypoint），再为每个 Service 拉取其专属 HTTPRoute（GetHTTPRoutesForService），与 Gateway 级路由合并后构建一个以Hostname: "*"匹配所有请求的虚拟主机。

第 4 步：发送流量并验证

CLIENT=$(kubectl get po -n httpbin -l app=curl -ojsonpath='{.items[0].metadata.name}') kubectl -n httpbin exec $CLIENT -- curl -sS -v httpbin:8000/get

如果响应中出现了Traversed-Waypoint响应头，说明 waypoint 已经成功接管了httpbin命名空间内所有服务的七层流量：

HTTP/1.1 200 OK ... traversed-waypoint: httpbin-waypoint server: envoy

无路由时的默认行为

如果某个 Service 被 waypoint 接管、但并未挂载任何 HTTPRoute，流量依然不会中断。源码中的buildDefaultToPortVirtualHost（waypoint_translator.go）会为每个 Service 端口生成一个「前缀匹配/的默认路由」，将流量原样转发到该 Service 的对应端口。也就是说：waypoint 的引入在默认情况下对业务透明，只有显式挂载路由或策略时才改变转发行为。

Istio Authorization Rules 演示

Waypoint 的核心价值之一是集中执行网格内的访问控制。Istio 的 AuthorizationPolicy 可以作用于所有被配置使用 waypoint 的工作负载，本节演示如何应用并测试一条简单的授权规则。

第 1 步：应用拒绝 GET 的授权策略

kubectl apply -f examples/waypoint/httpbin-authz.yaml

该策略（httpbin-authz.yaml）以 Service 为targetRefs目标，拒绝所有到 httpbin 的 GET 请求：

apiVersion: security.istio.io/v1 kind: AuthorizationPolicy metadata: name: httpbin-authz-svc namespace: httpbin spec: action: DENY rules: - to: - operation: methods: ["GET"] ports: ["8000"] targetRefs: - group: "" kind: Service name: httpbin

第 2 步：验证流量走向

先获取客户端 Pod 名：

CLIENT=$(kubectl get po -n httpbin -l app=curl -ojsonpath='{.items[0].metadata.name}')

测试被规则阻止的GET：

kubectl -n httpbin exec $CLIENT -- curl -si httpbin:8000/get

请求被 waypoint 拦截并拒绝：

HTTP/1.1 403 Forbidden traversed-waypoint: httpbin-waypoint content-length: 19 content-type: text/plain date: <...omitted...> server: envoy RBAC: access denied

测试被放行的POST：

kubectl -n httpbin exec $CLIENT -- curl -sI -XPOST httpbin:8000/post

输出显示请求成功完成：

HTTP/1.1 200 OK access-control-allow-credentials: true access-control-allow-origin: * content-type: application/json; charset=utf-8 date: <...omitted...> content-length: 639 x-envoy-upstream-service-time: 2 traversed-waypoint: httpbin-waypoint server: envoy

授权规则的底层实现

AuthorizationPolicy 在 waypoint 上的执行并非 Istio 组件代劳，而是 kgateway 的 rbac.go 直接把策略翻译成 Envoy RBAC 过滤器注入 waypoint 代理：

• BuildRBAC使用 Istio 提供的pilot/pkg/security/authz/builder构建 TCP 与 HTTP 两套 RBAC 过滤器，并通过filters.FilterStage_AuthZStage指定插入到认证之后的过滤阶段（rbac.go）；
• 授权策略先按ALLOW/DENY/AUDIT/CUSTOM四种 action 去重归类（separateAndDeduplicatePolicies）。其中CUSTOM动作依赖 ext_authz 提供方，当前尚不支持，会被记录日志并忽略（rbac.go）；
• HTTP RBAC 过滤器被挂到 HTTP 过滤器链、TCP RBAC 过滤器被挂到 TCP 网络过滤器链上，因此无论服务端口是 HTTP 还是 TCP，都能执行访问控制（waypoint_translator.go）。

将 Waypoint 部署到自己的服务

如果要让自己的业务服务也走 waypoint，只需为其所在的命名空间启用 ambient 流量捕获：

kubectl label namespace httpbin istio.io/dataplane-mode: ambient

随后为该命名空间创建对应的kgateway-waypointGateway（参照 waypoint-gw.yaml），并按需挂载 HTTPRoute 或 AuthorizationPolicy 即可。若只希望个别服务（而非整个命名空间）走 waypoint，可在 Service 上直接添加istio.io/use-waypoint: <waypoint-name>标签——源码GetWaypointServices正是通过解析这类标签确定某个 waypoint 代理管辖的 Service 集合（waypoint_query.go）。

Waypoint 的流量类型与配置项

支持接管三种流量范围

waypoint 通过 Gateway 上的istio.io/waypoint-for标签声明自己处理哪类流量，取值及含义定义于 waypoint_model.go：

源码GetWaypointFor解析该标签：未设置时默认service，非法值则两种模式都不生效（waypoint_model.go）。本文演示的httpbin-waypoint未设置该标签，因此按默认的service模式工作。

全局设置中的 Waypoint 相关项

waypoint 行为的若干全局开关定义在 api/settings/settings.go，可通过 Settings CR 调整：

其中，IstioNamespace对应 waypoint 插件设计文档 中的决策：waypoint 的全局授权策略默认应放在istio-system命名空间，以便与 Istio 原实现保持一致，同时该命名空间可通过 Settings 修改，避免多命名空间下授权策略重复冲突。WaypointLocalBinding直接影响翻译器选用的监听地址（见 waypoint_translator.go）：默认绑定0.0.0.0，开启后绑定127.0.0.1。

以 GatewayClass 为目标挂载全局授权策略

除了把 AuthorizationPolicy 挂到具体 Service，还可以让一条策略作用于整个kgateway-waypointGatewayClass 下所有 waypoint 覆盖的服务。仓库的测试用例给出了完整示例（authz-gatewayclass-ref.yaml）：

apiVersion: security.istio.io/v1 kind: AuthorizationPolicy metadata: name: authz-gatewayclass-ref namespace: istio-system spec: action: DENY rules: - to: - operation: methods: ["GET"] ports: ["8080"] targetRefs: - group: gateway.networking.k8s.io kind: GatewayClass name: kgateway-waypoint

将targetRefs.kind设为GatewayClass、并放在根命名空间istio-system中，即可作为「命名空间级」策略作用于该 waypoint 管辖的全部服务。翻译器在buildServiceChains中会先拉取 Gateway/GatewayClass 级策略（GetAuthorizationPoliciesForGateway），再与每个 Service 专属策略合并，一并编译进 RBAC 过滤器（waypoint_translator.go）。这一点对从 Istio 迁移到 kgateway 的用户尤其友好：已有的istio-system全局授权策略无需改动即可继续生效。

结语

通过本文的四个步骤，可以看到 kgateway 作为 Istio Ambient 模式下的 waypoint 替代实现，具备三个关键特征：

1. 接入成本低：只需要创建使用kgateway-waypointGatewayClass 的 Gateway，并在命名空间打上istio.io/dataplane-mode: ambient与istio.io/use-waypoint两个标签，ztunnel 就会自动把七层流量交到 kgateway waypoint；
2. 策略能力强：既支持 Gateway API 标准的「以 Service 为 parentRef」的 HTTPRoute 挂载（GAMMA 规范），也原生翻译 Istio AuthorizationPolicy（含 ALLOW/DENY/AUDIT），并支持以 GatewayClass 为目标的全局策略；
3. 行为透明可控：没有路由时默认透传，挂载路由与策略后才改变流量行为，便于渐进式地在网格中引入七层管控。

如需深入源码，可继续阅读 waypoint 插件目录 下的 plugin.go（插件注册与 ingress-use-waypoint 集群覆盖）、waypoint_translator.go（监听器与过滤器链构建）以及对应测试用例 plugin_test.go、rbac_test.go。

• API网关
• 云原生
• 微服务