KServe 中自定义本地网关配置的实践指南

问题背景

在使用 KServe 进行模型服务部署时，很多团队会遇到需要自定义本地网关（Local Gateway）的场景。本文将以一个实际案例为基础，详细介绍在 KServe 中配置非默认本地网关时可能遇到的问题及其解决方案。

典型症状

当 KServe 与自定义网关配置不匹配时，通常会表现出以下症状：

1. 通过推理服务 URL 访问时出现 504 网关超时错误
2. 直接访问服务私有端点可以正常工作
3. 日志中显示 activator 请求超时
4. 网关日志中出现路由未找到的错误

根本原因分析

出现这些问题的主要原因在于 KServe 的多层配置需要协调一致：

1. Knative Serving 配置中需要正确定义本地网关
2. KServe 的配置需要与 Knative 配置保持一致
3. Istio 网关需要正确配置主机路由规则

完整解决方案

1. Knative Serving 配置

在 KnativeServing 自定义资源中，需要正确配置本地网关信息：

apiVersion: operator.knative.dev/v1beta1
kind: KnativeServing
metadata:
  name: knative-serving
  namespace: knative-serving
spec:
  config:
    istio:
      local-gateways: |
        - name: custom-local-gateway
          namespace: istio-system
          service: custom-local-gateway.istio-system.svc.cluster.local
  ingress:
    istio:
      enabled: true
      knative-local-gateway:
        selector:
          app: custom-local-gateway
          istio: custom-local-gateway

2. KServe 配置

在 KServe 的 inferenceservice-config ConfigMap 中，需要同步更新网关配置：

apiVersion: v1
kind: ConfigMap
metadata:
  name: inferenceservice-config
  namespace: kserve
data:
  ingress: |-
    {
        "ingressGateway": "knative-serving/knative-ingress-gateway",
        "localGateway": "istio-system/custom-local-gateway",
        "localGatewayService": "custom-local-gateway.istio-system.svc.cluster.local",
        "ingressClassName": "istio"
    }

3. Istio 网关配置

确保 Istio 网关包含了必要的域名匹配规则：

apiVersion: networking.istio.io/v1beta1
kind: Gateway
metadata:
  name: custom-local-gateway
  namespace: istio-system
spec:
  selector:
    app: custom-local-gateway
  servers:
  - hosts:
    - "*.online-serving"
    - "*.online-serving.svc"
    - "*.online-serving.svc.cluster.local"
    port:
      name: http
      number: 80
      protocol: HTTP

验证步骤

配置完成后，可以通过以下方式验证：

1. 检查 Knative Serving 和 KServe 的配置是否同步
2. 检查 Istio 网关日志是否有错误
3. 使用 curl 从集群内部测试推理服务端点
4. 检查 activator 组件的日志是否有健康检查失败

最佳实践建议

1. 命名一致性：保持网关名称在所有配置中的一致性
2. 域名覆盖：确保网关配置覆盖了所有可能的服务域名格式
3. 逐步验证：先验证直接访问服务端点，再验证通过网关访问
4. 日志监控：建立对 activator 和网关日志的监控，及时发现配置问题

总结

在 KServe 中使用自定义本地网关需要多层配置的协调配合。通过本文介绍的配置方法和验证步骤，可以有效地解决网关超时和路由找不到的问题，确保推理服务的正常访问。关键是要理解 KServe、Knative 和 Istio 三者之间的交互关系，并在配置时保持一致性。