Kubernetes Operations Runbook

这份 runbook 用来处理 OAH 在 Kubernetes 上最常见的几类运行异常。

配套文档：

• K8S 路线图
• 部署文档
• Kubernetes Rollout Checklist
• Helm Chart README

建议排障时优先确认：

• 当前 release 名称
• 当前 namespace
• 当前使用的是哪套 values
• 最近一次 chart 升级或镜像变更时间

1. Controller 无 Leader

现象：

• oah_controller_leader 持续为 0
• OAHControllerNoLeader 告警触发
• /snapshot 中所有 controller 实例都显示 leader=false

优先检查：

• controller Pod 是否都 ready
• workers.controller.leader_election.kubernetes.* 是否正确
• controller RBAC 是否具备 leases get/create/patch
• ServiceAccount 是否挂载了 in-cluster token

建议命令：

kubectl -n <namespace> get pods -l app.kubernetes.io/component=controller
kubectl -n <namespace> logs deploy/<controller-deployment> --tail=200
kubectl -n <namespace> get lease
kubectl -n <namespace> describe lease <lease-name>
kubectl -n <namespace> auth can-i get leases --as=system:serviceaccount:<namespace>:<service-account>
kubectl -n <namespace> auth can-i patch leases --as=system:serviceaccount:<namespace>:<service-account>

常见原因：

• Lease namespace / name 配置错
• controller RBAC 不足
• Pod 无法访问 Kubernetes API
• strict egress 打开后，没有放行 Kubernetes API

恢复动作：

• 先修正 RBAC 或 egress 到 Kubernetes API 的放行
• 再重启 controller Deployment
• 确认至少一个实例重新拿到 leader=true

2. Scale Target 持续 Error

现象：

• oah_controller_scale_target_phase_error 持续为 1
• OAHControllerScaleTargetError 告警触发
• /snapshot.controller.scaleTarget.reasonCode 为 selector_no_match、forbidden、timeout 等

优先检查：

• scale_target.kubernetes.label_selector 是否只命中一个 Deployment
• controller 是否有 deployments get/list 与 deployments/scale get/patch
• strict egress 是否放行了 Kubernetes API

建议命令：

kubectl -n <namespace> get deploy -l '<label-selector>'
kubectl -n <namespace> auth can-i get deployments --as=system:serviceaccount:<namespace>:<service-account>
kubectl -n <namespace> auth can-i patch deployments/scale --as=system:serviceaccount:<namespace>:<service-account>
kubectl -n <namespace> logs deploy/<controller-deployment> --tail=200
curl http://<controller-pod-ip>:8788/snapshot

常见原因：

• selector 0 命中或多命中
• target Deployment 名称变化但 values 未同步
• RBAC 不足
• API server 超时 / 网络抖动

恢复动作：

• 优先修正 selector 或 RBAC
• 若是网络问题，先回滚 strict egress 变更或放通 API
• 观察 scaleTarget.phase 从 error 恢复为 accepted/progressing/ready

3. Worker Rollout Stuck

现象：

• oah_controller_scale_target_phase_progressing 长时间为 1
• desired_replicas > scale_target_ready_replicas
• OAHControllerWorkerRolloutStuck 告警触发

优先检查：

• worker Pod 是否创建成功但未 ready
• readinessProbe 是否连续失败
• workspace volume、Redis、Postgres、对象存储是否可达

建议命令：

kubectl -n <namespace> get pods -l app.kubernetes.io/component=sandbox -o wide
kubectl -n <namespace> describe pod <worker-pod>
kubectl -n <namespace> logs <worker-pod> --tail=200
kubectl -n <namespace> get events --sort-by=.lastTimestamp | tail -n 50

常见原因：

• readiness 探针失败
• strict egress 打开后，Redis / Postgres / 对象存储 / 模型运行时未放行
• PVC 或 emptyDir 容量问题
• 新镜像启动失败

恢复动作：

• 先定位是探针失败、依赖不可达还是镜像异常
• 如为 strict egress 误拦，先回滚 overlay 或补放行
• 必要时回滚 chart / 镜像版本

4. Worker Drain 超时

现象：

• worker 进入 draining 后长时间不退出
• Pod 长时间处于 Terminating
• 日志中出现 drain timeout recovery

优先检查：

• worker.drain.timeoutMs
• worker.terminationGracePeriodSeconds
• worker.drain.timeoutStrategy
• 当前是否存在长时间运行的 run / workspace flush

建议命令：

kubectl -n <namespace> logs <worker-pod> --tail=200
kubectl -n <namespace> describe pod <worker-pod>
curl http://<worker-pod-ip>:8787/healthz
curl http://<worker-pod-ip>:8787/readyz

常见原因：

• terminationGracePeriodSeconds 小于 drain timeout
• preStop 已触发，但 run 本身无法正常结束
• workspace flush / object storage 回写过慢

恢复动作：

• 短期先确认 recovery 策略是否符合预期
• 中期调大 terminationGracePeriodSeconds
• 如 object storage 慢导致 drain 卡住，优先检查出口网络与存储侧性能

5. Scale-Down 一直被阻塞

现象：

• oah_controller_scale_down_allowed=0
• oah_controller_scale_down_blocked_replicas > 0
• OAHControllerScaleDownBlocked 告警持续触发

优先检查：

• /snapshot.controller.scaleDownGate
• worker 是否仍在 draining
• workspace materialization 是否还有 blocker / failure
• placement 是否还引用 late / missing worker

建议命令：

curl http://<controller-pod-ip>:8788/snapshot
kubectl -n <namespace> logs deploy/<controller-deployment> --tail=200
kubectl -n <namespace> logs <worker-pod> --tail=200

常见原因：

• worker 正在 drain
• object-store materialization 尚未 flush 完
• placement 仍引用 late / missing owner worker

恢复动作：

• 先确认是不是健康的保护性阻塞
• 如果只是 drain 未收敛，优先等它自然结束
• 如果是 placement 长时间不收敛，再检查 worker registry 与 Redis 状态

6. Strict Egress 打开后组件不可用

现象：

• rollout 后多个组件同时 not ready
• 日志出现 Redis / Postgres / S3 / model runtime 连接失败
• DNS 解析失败

优先检查：

• 当前是否叠加了 strict-egress.values.yaml 或 prod-hardening.values.yaml
• networkPolicy.egress.dependencies.* 中的 peer selector / CIDR 是否已替换成真实值

建议命令：

kubectl -n <namespace> get networkpolicy
kubectl -n <namespace> describe networkpolicy <name>
kubectl -n <namespace> logs <pod> --tail=200

建议处理顺序：

1. 先确认 DNS 是否放行
2. 再确认 Redis / Postgres
3. 再确认 Kubernetes API
4. 最后确认对象存储 / 模型运行时

恢复动作：

• 最快的恢复方式是回滚 strict egress overlay
• 然后按依赖逐项补 peer selector / CIDR，再重新启用

7. Chart 升级后出现回归

现象：

• 升级后一切资源都存在，但行为回归
• controller 指标异常
• worker drain 或 scale target 行为和升级前不一致

优先检查：

• 本次升级的 values diff
• 镜像 tag diff
• helm get values 和 helm get manifest

建议命令：

helm -n <namespace> history <release>
helm -n <namespace> get values <release> -a
helm -n <namespace> get manifest <release>
kubectl -n <namespace> rollout status deploy/<deployment>

恢复动作：

• 如果问题范围大，先回滚 release
• 回滚后按 Kubernetes Rollout Checklist 重新验证

8. 推荐排障顺序

遇到 K8S 运行异常时，建议按下面顺序排：

1. 先看 controller 是否有 leader
2. 再看 scale target 是否处于 error
3. 再看 worker rollout 是否 stuck
4. 再看 worker drain / scale-down gate
5. 最后看 strict egress / NetworkPolicy 是否误拦

这个顺序的好处是：

• 先判断是不是控制面失效
• 再判断是不是平台调用失效
• 最后才判断执行面和网络面细节