运维 Operator 部署
本指南覆盖 SemanticRouter 资源的日常运维。安装和首次部署见使用 Kubernetes Operator 部署。
读取协调状态
kubectl get semanticrouter <name> -o wide
kubectl describe semanticrouter <name>
kubectl get semanticrouter <name> -o jsonpath='{.status.conditions}'
将 metadata.generation、status.observedGeneration、状态条件和就绪副本一起查看。控制器在运行,并不表示最新的自定义资源 generation 已成功应用。
协调刷新的每个条件都会在它自己的 observedGeneration 中记录自定义资源的 generation。它标识的是该条件所报告的 generation;Deployment 的滚动更新和就绪副本需要单独检查。
协调停滞时,检查其拥有的工作负载:
kubectl get deployment,pod,service,configmap,pvc \
-l app.kubernetes.io/instance=<name>
kubectl logs -n semantic-router-operator-system \
deployment/semantic-router-operator-controller-manager
启用的启动探针和就绪探针取决于模式:
- Standalone 使用 HTTP
/ready。 - 明文
extproc使用端口50051上的 gRPC 健康检查,它会等待生效的服务配置;存活探针仍是 TCP 检查。 spec.args中启用--secure的extproc保留 TCP 探针,因为受支持的 Kubernetes 探针 API 无法检查 TLS gRPC 监听器。这些检查只确认连通性,不代表已可提供服务。
安全更新
- 导出当前自定义资源,并记录已部署的镜像引用。
- 审阅 CRD 和发行说明中的 schema 变更。
- 在非生产环境应用新的自定义资源或 Operator 版本。
- 等待 observed generation 和就绪副本收敛。
- 通过每个重要入口发送真实请求。
- 若就绪状态或路由回退,回滚自定义资源或镜像引用。
固定镜像标签或 digest。除非这些变更有意耦合并已一起测试,不要在一次上线中同时更改 Operator、Router 镜像、路由策略、模型池和存储后端。
扩缩容与可用性
通过 spec.replicas 设置固定副本,或启用 HPA adapter:
spec:
autoscaling:
enabled: true
minReplicas: 2
maxReplicas: 10
targetCPUUtilizationPercentage: 70
使用节点亲和性、容忍、拓扑打散或反亲和,以及单独管理的 PodDisruptionBudget,以匹配可用性目标。学习或其他副本本地可变状态可能需要额外设计;不要假定增加副本就能让每个有状态路由功能保持一致。
指标与追踪
Router 在已配置的 metrics Service 端口(默认 9190)暴露 Prometheus 指标:
kubectl port-forward service/<name> 9190:9190
curl -sS http://localhost:9190/metrics | head
用部署所用的标签配置 ServiceMonitor 或等效采集器。通过 spec.config.observability 启用 OpenTelemetry,并将追踪发送到 Router 命名空间可达的 collector。保持追踪采样和采集属性与请求数据的敏感度匹配。
常见故障
后端发现失败
对于 service 后端,验证 Service 名称、命名空间、端口、端点和网络策略。对于 KServe,验证 InferenceService 已就绪且其 predictor Service 存在。对于 Llama Stack,检查候选 Service 上的标签。
kubectl get service,endpoints -n <backend-namespace>
kubectl describe inferenceservice <name> -n <backend-namespace>
Gateway 模式没有路由
Operator 不会创建 HTTPRoute。需要的路由取决于模式:
- **普通 Gateway HTTP 转发。**省略
spec.gateway.existingRef,将/v1直接路由到 standalone Router Service 的http-8801端口 8801;不会创建 Envoy sidecar。检查 Gateway 允许来自 Router 命名空间的路由,且路由报告Accepted=True和ResolvedRefs=True。 - **ExtProc。**若设置了
spec.gateway.existingRef,Router 改为提供 ExtProc。检查网关特定的 ExtProc 策略指向 Router Service 的 gRPC 端口(默认 50051),且其模型路由指向真实的后端 Service。
Router api 端口(默认 8080)是管理端点,不能服务推理 completions。见两条现有 Gateway 部署路径。
kubectl get gateway -A
kubectl get httproute -A
Pod 处于 ImagePullBackOff
检查 pod 事件,确认镜像存在,并在仓库需要认证时提供 imagePullSecret。
kubectl describe pod <pod-name>
仓库镜像和集群出口指引见受限网络环境。
PVC 一直处于 pending
检查集群中是否存在所请求的 StorageClass 和访问模式,以及 provisioner 能否满足所请求的容量:
kubectl get storageclass
kubectl describe pvc <pvc-name>
更改存储设置可能影响现有数据。替换 claim 前,先备份持久状态,并遵循存储提供方的迁移流程。