本文定位：面向已经遇到资源创建失败、发布卡住、控制器重试或 API Server 日志出现 Admission Webhook 错误的平台与安全团队，重点排查调用失败，不展开准入策略治理体系。
Kubernetes Admission Webhook排查的第一步，不是立刻修改策略规则，而是看错误信号属于“策略主动拒绝”还是“API Server 调不到 Webhook”。前者要看规则命中和返回信息，后者通常落在证书、Service、Endpoint、网络路径或超时配置上。
图1：从 API Server 到 Admission Web
先按报错信号给 Webhook 分类
Kubernetes 动态准入控制允许 API Server 通过 Admission Webhook 调用外部服务处理准入请求[1]。如果错误已经指向 admission webhook，排查入口应从用户侧报错、事件、控制器日志和 API Server 日志里提取关键词。
常见错误可以先放进这张排障矩阵：
| 错误现象 | 日志关键词 | 优先检查对象 | 修复方向 |
|---|---|---|---|
| 请求被明确拒绝 | `admission webhook … denied the request` | Webhook 返回信息、策略命中条件、对象字段 | 修正对象配置、调整策略条件或补充例外说明 |
| 发布或控制器长时间卡住 | `context deadline exceeded`、`timeout` | Webhook 后端响应、`timeoutSeconds`、Pod 负载 | 恢复后端、缩短慢路径、降低超时放大影响 |
| TLS 校验失败 | `x509: certificate signed by unknown authority`、`certificate is valid for` | `caBundle`、证书 SAN、Service DNS | 重新注入 CA、签发匹配 Service DNS 的证书 |
| 连接被拒绝 | `connection refused`、`connect: refused` | Service 端口、容器监听端口、readiness | 对齐端口、修复探针和进程监听状态 |
| 没有后端实例 | `no endpoints available for service` | Service selector、EndpointSlice、Webhook Pod | 修正 selector、恢复 Pod、检查命名空间和标签 |
| 只有部分命名空间异常 | `namespaceSelector`、特定 namespace 报错 | 命名空间标签、NetworkPolicy、策略匹配范围 | 校准命名空间标签、放通网络或缩小匹配范围 |
denied 和 timeout 不是同一类问题
`denied the request` 表示 Webhook 已经被调用并返回了拒绝结果，重点在策略语义、对象字段和错误提示。`timeout`、`x509`、`connection refused` 和 `no endpoints` 则说明调用链路没有稳定完成，继续改策略表达式通常不会解决根因。
判断标准：如果 Webhook 后端没有收到请求，优先查链路；如果后端收到并返回拒绝，才回到策略内容。
从 API Server 到 Webhook Service 逐段验证
动态准入控制通过 `MutatingWebhookConfiguration` 和 `ValidatingWebhookConfiguration` 把 API Server 的准入请求转发给外部服务，调用配置、规则匹配、失败处理和 TLS 客户端配置都来自这些对象[2]。排障时可以沿“配置是否命中 → Service 是否存在 → Endpoint 是否就绪 → TLS 是否可信 → 后端是否响应”逐段缩小范围。
建议按下面顺序收集证据：
- 确认是哪一个 Webhook 报错。从用户报错或 API Server 日志里找到 webhook 名称，再定位对应的 WebhookConfiguration。
- 确认请求是否应该命中。检查 `rules`、`namespaceSelector`、`objectSelector` 和操作类型，避免把未命中误判为后端故障。
- 确认 Service 指向哪里。查看 `clientConfig.service.name`、`namespace`、`path`、`port` 是否与实际 Service 一致。
- 确认 Endpoint 是否可用。检查 Service selector、EndpointSlice 和 Webhook Pod readiness。
- 确认 TLS 信任链。核对 `caBundle`、服务端证书 SAN 与 API Server 访问的 Service DNS 是否一致。
kubectl get validatingwebhookconfiguration
kubectl get mutatingwebhookconfiguration
kubectl describe validatingwebhookconfiguration <webhook-config-name>
kubectl get svc,endpointslices,pod -n <webhook-namespace> -l app=<webhook-label>这组 `kubectl` 命令不直接修改集群，只用于定位对象关系[2]。生产环境中如果需要调整 WebhookConfiguration、证书或 Service selector，应先评估影响范围并准备回滚。
图2：MutatingWebhook 与 Validating
先确认调用目标，再讨论策略命中
有些团队会直接跳到策略引擎日志，但配置层已经可能出错。例如 Service 命名空间写错、端口从 443 改成 9443 后 WebhookConfiguration 没同步，或者 Service selector 仍指向旧版本 Pod。此时策略日志可能没有任何新记录，因为请求从未到达后端。
如果同一套策略在某些命名空间正常、另一些命名空间失败，则要同时看 `namespaceSelector` 与网络路径。选择器决定“是否调用”，NetworkPolicy 或集群网络策略决定“能不能调通”，两者的错误表现可能都集中在发布失败上。
x509、caBundle 与 Service DNS 要一起看
Admission Webhook 的 TLS 问题经常表现为 x509 错误。根据 Kubernetes Webhook API 字段说明，`clientConfig.caBundle` 用于让 API Server 校验 Webhook 服务证书；如果不使用 `url`，通常通过 Service 引用集群内服务[2]。Kubernetes 官方 Webhook good practices 也建议为 Webhook 选择短超时、避免慢路径放大集群写请求影响[3]。因此证书排障不能只看 Secret 是否存在，还要看 API Server 访问的主机名和证书 SAN 是否匹配。
证书链路重点检查：
- `caBundle` 是否为空或过期：证书轮换后，WebhookConfiguration 里可能仍是旧 CA。
- 证书 SAN 是否覆盖 Service DNS：常见形式包括 `<svc>.<namespace>.svc`，必要时还要覆盖完整集群域名。
- Secret 与 Pod 是否使用同一套证书：Secret 更新后 Pod 未重载，后端仍在提供旧证书。
- 证书注入控制器是否工作：如果依赖 cert-manager 或平台证书注入器，要检查注入状态和事件。
x509 修复后仍要验证命中路径
证书修复只能证明 TLS 握手恢复，不代表策略结果正确。建议在修复后用一个应通过的对象和一个应拒绝的对象分别验证：前者确认 Webhook 不再误伤正常发布，后者确认策略仍能返回可读的拒绝原因。
Service和Endpoint决定能否连上
`no endpoints available for service` 通常比 x509 更直接：API Server 找到了 Webhook Service，但 Service 背后没有可用后端。常见原因包括 selector 标签不匹配、Webhook Pod CrashLoopBackOff、readiness probe 失败、滚动升级时副本数为 0，或者 EndpointSlice 更新延迟。
排查 Service 可达性时，优先看四个对象：
- Service：端口名、端口号、targetPort 是否与容器监听一致[2]。
- EndpointSlice：是否存在 ready endpoint，地址是否指向当前 Pod。
- Pod：容器是否 Ready，日志是否显示证书加载、监听端口或依赖系统异常。
- NetworkPolicy：是否允许 API Server 或控制面组件访问 Webhook 后端端口。
如果 API Server 日志是 `connection refused`，通常说明网络路径能到目标地址，但目标端口没有服务在监听，或 readiness 与实际监听状态不一致。如果是 `i/o timeout`，更可能是网络策略、路由、防火墙或后端线程阻塞。
failurePolicy 只决定故障放大方式
`failurePolicy` 在 Webhook 调用失败时决定 API Server 是拒绝请求还是忽略该 Webhook 的失败继续处理[2]。它不是根因修复手段，但会决定故障影响面：同样是 Webhook 后端不可达，`Fail` 可能放大发布阻断，`Ignore` 可能让部分策略在故障期间不生效；配合 `timeoutSeconds` 时，还要关注慢 Webhook 对写请求延迟的放大风险[3]。
处理 failurePolicy 前先回答：
- 这个 Webhook 拦截的是安全底线，还是标签补全、提醒、审计类辅助规则？
- 当前故障影响的是单个命名空间、少量资源，还是所有写请求？
- Webhook 后端是否有多副本、PDB、监控告警和证书轮换机制？
- 临时旁路后，能否通过审计日志或后续扫描补齐风险检查？
临时旁路要有退出条件
如果为了恢复发布临时调整 `failurePolicy` 或缩小 selector，应该明确恢复条件，例如 Webhook Pod Ready、EndpointSlice 恢复、证书重新注入、拒绝日志可解释、验证对象通过。否则临时旁路容易变成长期裸奔。
这里的策略治理视角可以只作为延伸阅读：如果团队需要设计长期的准入规则分级、审计和例外流程，可以回到 云原生安全专题 承接；本文主体仍聚焦故障定位。
修复后验证命中、旁路与回滚
Admission Webhook 故障修复完成后，不建议只看“这次发布过去了”。更稳妥的做法是把验证分成命中、旁路、回滚三类路径，分别确认策略仍有效、故障不再放大、配置可以快速恢复。
图3：Webhook 调用失败修复后，应同时验证命中、旁路和回
修复后至少验证：
- 正常对象通过：确认业务发布或控制器调谐不再被 Webhook 调用错误阻断。
- 违规对象被拒绝：确认策略仍能命中，并返回可读拒绝原因。
- Webhook 后端可观测：日志、指标、证书有效期和 Endpoint 状态可被监控。
- 旁路配置已恢复：临时修改过的 `failurePolicy`、selector 或副本数回到预期状态。
- 回滚路径可执行：WebhookConfiguration、证书 Secret、Service selector 和后端版本都能回到上一版。
如果问题与控制面整体认知有关，可以延伸阅读 Kubernetes专题；如果问题聚焦安全策略长期建设，再进入准入策略治理和审计设计，而不是在故障现场继续扩大变更范围。
小结
Kubernetes Admission Webhook 排查要先读错误信号，再沿 API Server 到 Webhook Service 的调用路径逐段验证。`denied` 通常指向策略命中和拒绝原因，`timeout`、`x509`、`connection refused` 和 `no endpoints` 更常指向证书、Service、Endpoint、网络或后端可用性。
`failurePolicy` 能改变故障影响面，但不能替代根因修复。生产环境更推荐先恢复可观测的调用链路，再验证正常对象、违规对象和临时旁路是否符合预期。这样才能把一次发布阻断收敛成可复盘、可预防的 Webhook 可用性问题。
参考资料
- [1] Kubernetes Dynamic Admission Control – 官方文档
- [2] Kubernetes API Reference: ValidatingWebhookConfiguration – 官方文档
- [3] Kubernetes Admission Webhook Good Practices – 官方文档
常见问题
1. Admission Webhook 报 x509 应该先查哪里？
先查 WebhookConfiguration 里的 `caBundle` 是否与后端服务证书的签发 CA 一致，再查服务端证书 SAN 是否覆盖 API Server 实际访问的 Service DNS。不要只看证书 Secret 是否存在，因为 Secret 存在不代表 Pod 已经加载新证书，也不代表 WebhookConfiguration 已同步新 CA。
2. `no endpoints available for service` 是策略问题吗？
通常不是。它说明 API Server 找到了 Webhook Service，但 Service 后面没有 ready endpoint。优先检查 Service selector、EndpointSlice、Webhook Pod readiness、滚动升级副本数和命名空间标签。只有 Endpoint 恢复后，才需要继续验证策略是否正确拒绝或放行对象。
3. Admission Webhook 超时能不能直接改成 Ignore？
可以作为临时止血选项，但不建议作为第一动作。先确认超时是否来自后端阻塞、网络策略、证书握手、DNS 或 Service 端口问题。如果策略属于安全底线，直接改成 Ignore 可能让高风险对象绕过准入检查；如果只是非关键标签补全或提醒类规则，临时旁路也要设置恢复条件和审计补偿。
4. 怎么区分 Mutating 和 Validating 失败？
看报错中的 webhook 名称和对应配置对象。如果最终对象被拒绝的字段不是用户提交的原始字段，先检查 MutatingWebhook 是否注入或改写了对象；如果对象已经变更后再被拒绝，再看 ValidatingWebhook 的规则和拒绝原因。两类 Webhook 的日志应分开收集，避免把变更阶段的问题误判为校验阶段误拦截。
5. Webhook 修复后为什么还要验证违规对象？
因为“发布恢复”只说明调用链路不再阻断正常请求，不代表安全策略仍然有效。修复证书、Service 或 Endpoint 后，建议同时提交一个应被拒绝的测试对象，确认 Webhook 能返回可读拒绝原因；再提交一个应通过的正常对象，确认策略没有扩大误伤范围。
