准入 Webhook 故障是什么
动态准入控制把资源的创建与更新请求交给外部 Webhook 服务做校验（validating）或改写（mutating）。当 Webhook 服务本身不可用、端点为空、证书出错或处理超时时，请求会直接失败，报错文本会指明是哪个 Webhook 拒绝或调用失败。failurePolicy 决定这种行为的影响面：设为 Fail 时 Webhook 不可用会阻塞写入，设为 Ignore 时请求放行但失去校验。
基本信息
| 配置对象 | ValidatingWebhookConfiguration、MutatingWebhookConfiguration |
|---|---|
| 触发时机 | 资源创建、更新、删除等准入阶段 |
| 指向目标 | 通常是一个 Service，最终落到具体 Pod 端点 |
| 失败行为 | failurePolicy 为 Fail 阻塞，Ignore 放行 |
| 典型影响 | 部署、扩容、创建对象随机失败 |
典型使用场景
- 发布突然报错：错误文本带 webhook 名称，说明是校验服务而非权限问题
- 集群组件挂掉连带业务不可写：Webhook 服务故障时，需要先恢复服务或临时调整策略
- 灰度上线策略：新策略先以非强制方式运行，观察误判后再切换为强制
- TLS 证书过期：Webhook 服务的证书到期后调用失败，集群范围的写入受影响
- 端点排查：确认 Service 选择器与端口是否指向真正提供服务的 Pod
排查路径
排查路径
kubectl get validatingwebhookconfigurations,mutatingwebhookconfigurations # 找出相关配置
kubectl describe validatingwebhookconfiguration my-policy | tail -30 # 看失败策略与指向的服务
kubectl get svc -n webhook-system # 目标服务是否存在
kubectl get endpoints -n webhook-system webhook-svc # 端点是否为空
kubectl -n webhook-system logs deploy/webhook-server --tail=50 # 服务侧是否有报错
kubectl get apiservice | grep -v True # 相关聚合组件状态两类典型报错
两类典型报错
# 拒绝型：Webhook 正常返回但判定不通过
Error from server: error when creating "pod.yaml": admission webhook
"validate.example.com" denied the request: <具体理由>
# 调用失败型：Webhook 不可达或证书异常
Error from server: failed calling webhook "validate.example.com":
Post "https://webhook-svc.webhook-system.svc:443/validate": connect: connection refused报错与处置对照
| 报错特征 | 指向 | 处置 |
|---|---|---|
| denied the request | 策略本身拒绝了请求 | 读理由并修正清单，属预期行为 |
| connection refused | 端点不可达 | 检查 Service 选择器、端口与 Pod 状态 |
| no endpoints available | Service 无就绪后端 | 先把 Webhook 服务拉起来 |
| x509 / certificate | 证书不匹配或过期 | 核对 caBundle 与服务证书有效期 |
| context deadline exceeded | 处理超时 | 检查服务性能与 timeoutSeconds 设置 |
把 failurePolicy 改成 Ignore 能让写入立刻恢复，但同时也让所有校验静默失效——策略类 Webhook 被绕过意味着合规与安全约束暂时消失。这是应急手段，必须记录变更并在故障恢复后立即改回。
Webhook 服务通常以高可用方式部署并被多类资源依赖，它的 Pod 数量与就绪状态直接决定集群能否写入。给它配置反亲和与 PodDisruptionBudget，比事后再做故障切换更省事。