Istio 如何启用 Gateway API Inference Extension 并用 InferencePool 动态路由推理流量

Istio 如何启用 Gateway API Inference Extension 并用 InferencePool 动态路由推理流量

【免费下载链接】istioConnect, secure, control, and observe services.项目地址: https://gitcode.com/GitHub_Trending/is/istio

在已经安装 Istio 的 Kubernetes 集群里，如果你想让推理流量经过 Gateway 时不再做静态负载均衡，而是由外部端点选择服务（EPP）按模型可用性、负载等条件为每个请求挑选后端 Pod，需要启用 Istio 对 Gateway API Inference Extension（GIE）的支持：在 istiod 打开特性开关，安装 GIE 的 CRD，然后用InferencePool加HTTPRoute把推理负载接进 Gateway。完成后的结果是：InferencePool引用的模型服务 Pod 池会被 Envoy 通过 ext_proc 过滤交给 EPP 决策，请求最终路由到 EPP 选定的pod:port。

工作原理与关键组件

• InferencePool：来自inference.networking.k8s.io/v1API group 的 Kubernetes CRD，代表一组推理模型服务端点。关键字段：
  • selector：标识池内模型服务 Pod 的标签选择器；
  • targetPorts：模型服务暴露的端口列表（自 GIE v1.1.0 起支持多端口）；
  • endpointPickerRef：指向提供端点选择逻辑的外部服务（EPP）。
• EPP（Endpoint Picker Protocol）：外部 gRPC 服务，借助 Envoy 的 ext_proc 过滤拦截请求，接收请求头并通过x-endpoint头返回选定的端点，格式为<pod-ip>:<port>。
• Shadow Service：Istio 为每个InferencePool自动创建一个内部 headless Service（ClusterIP: None），命名模式为<pool-name>-ip-<hash>（例如test-pool-ip-a1b2c3d4），并携带 EPP 配置标签：
  • istio.io/inferencepool-name：池名称；
  • istio.io/inferencepool-extension-service：EPP 服务名；
  • istio.io/inferencepool-extension-port：EPP 服务端口；
  • istio.io/inferencepool-extension-failure-mode：失败模式（FailOpen/FailClose）。

整体流程（见 架构文档）：HTTPRoute的backendRefs引用InferencePool→ Gateway controller 检测到后创建 shadow Service → 路由转换时挂上携带 EPP 信息的 ext_proc 过滤 → 运行时 Envoy 通过 ext_proc 向 EPP 查询端点 → 请求路由到选定的pod:port。

前置条件

架构文档列出集成测试（也是本文操作路径的参照）要求：

1. 已安装 Istio 的 Kubernetes 集群；
2. Gateway API CRD 已安装；
3. Gateway API Inference Extension CRD 已安装。

本仓库的集成测试使用的 CRD 清单在 gateway-api-crd.yaml 和 gateway-api-inference-extension-crd.yaml，可以对照安装到集群。两点环境说明来自测试框架实现 crd/gateway.go：

• 集群版本低于 1.31 时测试会跳过（isIP()CEL 函数需要 1.31，对应 gateway-api v1.5.0），因此该路径在 1.31 及以上集群上验证；
• OpenShift 4.19（K8s 1.32）起 Gateway API 已预装，不应重复部署 Gateway API CRD，但 Gateway API Inference Extension 的 CRD 仍需部署。

此外你需要准备一个 EPP 服务（实现 ext_proc 的 gRPC 服务），它的服务名和端口会填进InferencePool的endpointPickerRef。

第一步：在 istiod 上启用 GIE

Gateway API Inference Extension 默认关闭（见 release note：off by default，通过ENABLE_GATEWAY_API_INFERENCE_EXTENSION环境变量开启；在 experimental.go 中该开关注册默认值为false）。启用需要两个条件：

1. 确保PILOT_ENABLE_GATEWAY_API=true（架构文档列为必需前提；当前源码中该开关注册默认值已是true，见 experimental.go，正常安装下无需改动，显式写出也无妨）；
2. 在 istiod 上设置ENABLE_GATEWAY_API_INFERENCE_EXTENSION=true。

架构文档给出的 IstioOperator 覆盖文件示例：

apiVersion: install.istio.io/v1alpha1 kind: IstioOperator spec: values: pilot: env: PILOT_ENABLE_GATEWAY_API: "true" ENABLE_GATEWAY_API_INFERENCE_EXTENSION: "true"

将以上内容存为gie-enable.yaml。按 Operator 文档说明，operator 目前是客户端 CLI 工具，profile 可通过 overlay 文件或--set参数定制：

# 仅渲染生成结果，确认 pilot 环境变量已写入 istioctl manifest generate -f gie-enable.yaml # 生成并按依赖顺序应用到集群 istioctl install -f gie-enable.yaml

集成测试的 测试入口以同样的方式在 istiod 上注入ENABLE_GATEWAY_API_INFERENCE_EXTENSION: "true"，可作对照。

第二步：部署 InferencePool、Gateway 与 HTTPRoute

三个资源都放在同一个命名空间（下文命令中的<namespace>替换为你的目标命名空间，例如承载推理负载的 namespace）。

创建 InferencePool

使用架构文档的示例结构：selector匹配模型服务 Pod 的标签，targetPorts列出模型服务端口，endpointPickerRef指向 EPP 服务：

apiVersion: inference.networking.k8s.io/v1 kind: InferencePool metadata: name: my-inference-pool spec: targetPorts: - number: 8000 - number: 8001 selector: matchLabels: app: inference-workload endpointPickerRef: name: endpoint-picker-service port: number: 9002

要点：池内每个模型服务 Pod 必须带selector指定的标签（示例中为app: inference-workload）；endpoint-picker-service:9002替换为你实际 EPP 服务的服务名与 gRPC 端口；多targetPorts需要 GIE v1.1.0 及以上。

创建 Gateway 与 HTTPRoute

以下清单取自 集成测试，其中gatewayClassName需替换为你集群中实际的 GatewayClass 名称，hostnames替换为你自己的域名：

apiVersion: gateway.networking.k8s.io/v1 kind: Gateway metadata: name: inference-gateway namespace: <namespace> spec: gatewayClassName: istio # 替换为集群中实际的 GatewayClass 名称 listeners: - name: http port: 80 protocol: HTTP allowedRoutes: namespaces: from: Same --- apiVersion: gateway.networking.k8s.io/v1 kind: HTTPRoute metadata: name: inference-route namespace: <namespace> spec: parentRefs: - name: inference-gateway hostnames: - "inference.example.com" rules: - backendRefs: - group: inference.networking.k8s.io kind: InferencePool name: my-inference-pool port: 80

backendRefs中group/kind/name指向 InferencePool，port必须填写（路由转换对 backendRef 要求 port 必填）。需要排查 EPP 交互细节时，测试里在 Gateway 上加了调试日志注解，可选：

annotations: sidecar.istio.io/componentLogLevel: "ext_proc:debug,connection:debug,filter:debug,router:debug"

验证结果

检查 shadow Service

InferencePool应用后，istiod 应自动创建 shadow Service。按集成测试的检查逻辑（inferencepool_test.go），按池名标签列出：

kubectl get svc -n <namespace> -l istio.io/inferencepool-name=my-inference-pool -o yaml

成功条件与测试断言一致：

• 存在名为my-inference-pool-ip-<hash>的 Service，且spec.clusterIP为None（headless）；
• 标签包含istio.io/inferencepool-extension-service（应为你的 EPP 服务名）和istio.io/inferencepool-extension-port（应为 EPP 端口）；
• 标签还包含istio.io/inferencepool-extension-failure-mode（FailOpen/FailClose）。

多个targetPorts的池只创建一个shadow service；路由转换实现中该服务的首个端口为 54321，其对应 cluster 会包含所有 target ports 的端点，交由 EPP 在它们之间做负载均衡（见 conversion.go 注释与测试注释）。

检查 Gateway 状态

kubectl get gateway inference-gateway -n <namespace> -o yaml

在status.conditions中确认Accepted: True与Programmed: True两个条件同时成立——集成测试就是等待这两个条件后才继续发流量（inferencepool_test.go）。

验证流量走向 EPP 选定的端点

通过 Gateway 发送 HTTP 请求（Host 头匹配HTTPRoute的hostnames）。按架构文档描述，Envoy 经 ext_proc 把请求交给 EPP，按 EPP 返回的x-endpoint（<pod-ip>:<port>）转发到对应模型服务端口。集成测试的端到端做法是：对 8000/8001/8002 三个目标端口逐一发起请求，以响应返回 200（check.OK）且响应中的端口字段等于目标端口作为通过标准（inferencepool_test.go）。如果你的模型服务不是 echo 测试程序，则判断标准是：请求能通过 Gateway 到达 EPP 选定的那台 Pod 的对应端口。

可选：运行仓库自带的 GIE 集成测试

如果在本仓库开发环境下做完整回归，架构文档给出的命令是：

go test -tags=integ ./tests/integration/pilot/gie/... -v

该测试会自动部署 Gateway API CRD 与 GIE CRD（低版本集群跳过）、部署监听 8000/8001/8002 的推理负载与 mock EPP（EndpointPicker: true的 gRPC 服务，服务名mock-epp，端口 9002），再执行上文全部验证步骤，覆盖TestInferencePoolMultipleTargetPorts场景：多 targetPorts 只生成一个带正确标签的 headless shadow service，且各端口的 EPP 选路都生效。

排查与限制

• 特性未开启时的报错：istiod 路由转换会返回InferencePool is not enabled. To enable, set ENABLE_GATEWAY_API_INFERENCE_EXTENSION to true in istiod（conversion.go）。若 HTTPRoute 无法解析 InferencePool backend，先确认 istiod Pod 的环境变量是否已注入并重启生效。
• backendRef 名称：name必须写 InferencePool 名称而不能带域名点号，否则报错InferencePool.Name invalid; the name of the InferencePool must be used, not the hostname.
• shadow Service 标签缺失：如果池对应的 Service 缺少 extensionRef 标签（EPP 服务、端口、失败模式任一为空），路由转换报InferencePool service invalid, extensionRef labels not found（conversion.go）。
• 多 targetPorts 的版本边界：多端口支持自 GIE v1.1.0 起，低于该版本的 GIE 实现只按单端口处理。
• CRD 与集群版本：集成路径在 K8s 1.31+ 验证；OpenShift 4.19 起不要重复安装 Gateway API CRD，但 GIE CRD 必须安装。
• EPP 依赖：整条路径依赖外部 EPP 服务可用（ext_proc gRPC），EPP 不可达时的行为由 shadow Service 上的istio.io/inferencepool-extension-failure-mode标签（FailOpen/FailClose）决定。

【免费下载链接】istioConnect, secure, control, and observe services.项目地址: https://gitcode.com/GitHub_Trending/is/istio