kgateway：云原生 API 网关与 AI 网关实践指南

项目概览

kgateway 是一款基于 Envoy 代理和 Kubernetes Gateway API 构建的云原生 API 网关解决方案，专注于提供高性能、灵活的流量管理能力。作为 Kubernetes 原生的入口控制器，它支持传统应用、微服务及无服务器架构的统一接入，特别优化了函数级路由和多协议处理能力。该项目采用 Go 语言开发，深度集成 Envoy 数据平面，为混合云环境下的服务治理提供标准化解决方案。

核心价值定位

• 统一流量入口：整合南北向流量管理，支持 HTTP/HTTPS、gRPC 等多协议
• 云原生设计：完全基于 Kubernetes API 规范，支持声明式配置和动态更新
• AI 工作负载优化：提供针对 AI 服务的专用路由和流量控制能力
• 可扩展架构：通过插件化设计支持功能扩展，适配不同业务场景需求

核心特性

1. 多维度流量管理

kgateway 提供细粒度的流量控制能力，包括：

• 动态路由：基于 Kubernetes Gateway API 实现 HTTPRoute、GRPCRoute 资源的动态配置
• 流量分流：支持权重路由、条件路由等高级流量分发策略
• 协议转换：内置 HTTP/JSON 与 gRPC 之间的协议转换能力
• 请求转换：支持请求头/体修改、URL 重写等请求转换功能

图 1：kgateway AI 请求处理流程示意图，展示控制平面资源与数据平面组件的交互关系

2. 企业级安全防护

• 认证授权：支持 JWT、OAuth2、API Key 等多种认证机制
• TLS 终结：提供完整的 TLS termination 和双向 TLS 支持
• 请求限流：基于速率、并发数的多层次限流策略
• WAF 集成：内置基础 Web 应用防火墙能力，防护常见攻击

3. 可观测性与监控

• 指标收集：暴露 Prometheus 兼容指标，覆盖流量、延迟、错误率等关键维度
• 分布式追踪：集成 OpenTracing，支持 Jaeger、Zipkin 等追踪系统
• 访问日志：可定制化日志格式，支持输出到标准输出或外部日志系统
• 健康检查：内置探针支持，监控网关及后端服务健康状态

核心技术选型

Envoy vs 传统代理

特性	Envoy 代理	传统代理（如 Nginx）
架构	异步非阻塞事件驱动	多进程/多线程模型
可扩展性	动态配置，热更新	需重启或重载配置
协议支持	HTTP/2, gRPC, WebSocket 原生支持	需模块扩展
可观测性	丰富的统计指标和追踪能力	基础指标，需额外配置
性能	高并发低延迟，C++ 实现	高性能但配置复杂

与 Kubernetes Gateway API 的深度集成

kgateway 完全遵循 Kubernetes Gateway API v1 规范，实现了：

• GatewayClass 资源作为集群级配置模板
• Gateway 资源定义流量入口点
• HTTPRoute/GRPCRoute 定义路由规则
• ReferenceGrant 实现跨命名空间资源引用控制

部署指南

环境检查

在部署 kgateway 前，请确保环境满足以下要求：

# 检查 Kubernetes 集群版本（需 1.24+）
kubectl version --short

# 检查 kubectl 配置
kubectl config current-context

# 验证集群网络插件（确保支持 LoadBalancer 类型服务）
kubectl get pods -n kube-system | grep -E 'calico|flannel|cilium'

安装步骤

1. 获取项目代码

git clone https://gitcode.com/gh_mirrors/kg/kgateway
cd kgateway

2. 创建命名空间

kubectl apply -f install/namespace.yaml
# 验证命名空间创建
kubectl get ns kgateway-system

3. 部署 CRDs

# 应用自定义资源定义
kubectl apply -f install/crds.yaml

# 验证 CRD 安装
kubectl get crds | grep gateway.kgateway.dev

4. 部署控制器

# 应用控制器部署清单
kubectl apply -f install/kgateway.yaml

# 检查控制器状态
kubectl get deployment -n kgateway-system kgateway-controller

5. 验证部署

# 检查所有组件状态
kubectl get pods -n kgateway-system

# 检查服务状态
kubectl get svc -n kgateway-system kgateway-controller

基础配置示例

创建基本的 Gateway 和 HTTPRoute 资源：

# gateway.yaml
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: kgateway-example
  namespace: default
spec:
  gatewayClassName: kgateway
  listeners:
  - name: http
    protocol: HTTP
    port: 80
    allowedRoutes:
      namespaces:
        from: All
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: example-route
  namespace: default
spec:
  parentRefs:
  - name: kgateway-example
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /echo
    backendRefs:
    - name: echo-service
      port: 8080

应用配置：

kubectl apply -f gateway.yaml

验证与调试

状态检查

# 检查 Gateway 状态
kubectl get gateway kgateway-example -o yaml

# 检查 HTTPRoute 状态
kubectl get httproutes example-route -o yaml

日志查看

# 查看控制器日志
kubectl logs -n kgateway-system deployment/kgateway-controller -f

# 查看数据平面代理日志
kubectl logs -n kgateway-system -l app=envoy -f

常见问题处理

问题 1：Gateway 状态一直处于 Pending

可能原因：

• 缺少 GatewayClass 配置
• 权限不足
• 网络插件不支持 LoadBalancer

解决方法：

# 检查 GatewayClass
kubectl get gatewayclasses

# 检查事件
kubectl describe gateway kgateway-example

问题 2：路由规则不生效

可能原因：

• 路由规则与 Gateway 不匹配
• 后端服务不可用
• 命名空间权限限制

解决方法：

# 检查路由与 Gateway 的关联
kubectl get httproutes example-route -o jsonpath='{.spec.parentRefs}'

# 验证后端服务
kubectl get svc echo-service

架构解析

kgateway 采用控制平面与数据平面分离的架构设计：

• 控制平面：由 kgateway-controller 实现，负责处理 Kubernetes 资源事件，生成 Envoy 配置
• 数据平面：基于 Envoy 代理，负责实际流量转发和策略执行

图 2：kgateway 部署器当前实现架构图，展示控制平面组件交互流程

控制平面核心组件包括：

• Deployer：负责生成和管理 Envoy 部署资源
• gw_controller：处理 Gateway 资源事件
• inference_pool_controller：管理 AI 推理工作负载

总结

kgateway 作为一款云原生 API 网关，通过深度整合 Envoy 代理和 Kubernetes Gateway API，为现代应用架构提供了统一的流量管理解决方案。其灵活的扩展机制和对 AI 工作负载的优化支持，使其成为混合云环境下服务治理的理想选择。通过遵循本文档的部署和配置指南，开发者和运维人员可以快速构建安全、高效的 API 网关基础设施。

如需进一步扩展 kgateway 功能，可参考以下资源：

• 自定义插件开发：pkg/plugins/
• 高级流量策略配置：examples/traffic-policy/
• 性能优化指南：devel/performance/