Kubernetes 准入控制器 Admission Webhook 允许集群管理员在 API 对象写入 etcd 之前，动态拦截创建、更新或删除请求，并执行自定义逻辑。它弥补了内置准入插件不够灵活的问题，使团队可以把组织内部的合规规则、安全基线以及默认值注入策略，下沉到控制平面统一执行。理解它的运行位置和调用顺序，是构建稳定扩展器的前提。
Admission Webhook 的两种类型与调用时机
Kubernetes 将动态准入 Webhook 划分为ValidatingAdmissionWebhook与MutatingAdmissionWebhook两类。前者只负责校验，当返回拒绝状态时 API 请求直接失败；后者可以在对象被持久化前修改其字段，例如自动注入 Sidecar 容器或填补缺失的标签。两者都在认证与内置授权之后、对象存储之前触发，但变更类必须先于校验类执行，否则校验器看到的是未修正的原文。
从调用链看，kube-apiserver 收到请求后先跑完 mutating 链，再跑 validating 链。如果某个 mutating webhook 响应超时或返回失败，整个请求会被中断，后续校验也不会发生。因此在生产环境必须给 webhook 配置合理的超时时间（默认 10 秒）与失败策略。对于非关键业务，建议把failurePolicy设为 Ignore，避免自研服务宕机引发集群不可用。
下面这段配置展示了如何声明一个校验型 Webhook，它只监听 Pod 的创建与更新，并指向集群内部的服务：
apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
metadata:
name: pod-policy-validator
webhooks:
- name: validate.pods.ippipp.com
rules:
- apiGroups: [""]
apiVersions: ["v1"]
operations: ["CREATE", "UPDATE"]
resources: ["pods"]
clientConfig:
service:
name: policy-svc
namespace: admission
path: "/validate"
failurePolicy: Fail
timeoutSeconds: 5
自研 Webhook 服务的请求处理与代码实现
Webhook 本质是一个接收 HTTPS POST 的 HTTP 服务。apiserver 会把待准入对象封装进AdmissionReview结构，服务端解析后返回同类型的响应，其中包含allowed布尔值与可选的status消息。任何序列化错误都会导致请求被拒，所以必须严格校验请求版本，并对无法识别的字段做兼容处理。
以 Go 语言为例，我们可以使用标准库与 k8s.io/api 提供的类型来快速搭建。下面代码演示了如何读取请求体、解析为AdmissionReview，并针对带有env: prod标签的 Pod 强制要求设置资源限制：
package main
import (
"encoding/json"
"io/ioutil"
"net/http"
admissionv1 "k8s.io/api/admission/v1"
corev1 "k8s.io/api/core/v1"
)
func validate(w http.ResponseWriter, r *http.Request) {
body, _ := ioutil.ReadAll(r.Body)
var review admissionv1.AdmissionReview
if err := json.Unmarshal(body, &review); err != nil {
http.Error(w, "bad request", http.StatusBadRequest)
return
}
req := review.Request
raw := req.Object.Raw
var pod corev1.Pod
json.Unmarshal(raw, &pod)
allowed := true
msg := ""
if pod.Labels["env"] == "prod" {
for _, c := range pod.Spec.Containers {
if c.Resources.Limits == nil {
allowed = false
msg = "生产环境 Pod 容器必须设置资源限制"
break
}
}
}
response := admissionv1.AdmissionReview{
TypeMeta: review.TypeMeta,
Response: &admissionv1.AdmissionResponse{
UID: req.UID,
Allowed: allowed,
Result: &metav1.Status{Message: msg},
},
}
out, _ := json.Marshal(response)
w.Header().Set("Content-Type", "application/json")
w.Write(out)
}
上面的实现没有处理 mutating 场景，若需要注入字段，只需把Response中的Patch字段填充为 JSON Patch 数组，并声明PatchType: JSONPatch。需要注意的是，mutating webhook 返回的补丁会按顺序应用，多个 webhook 之间若修改同一字段可能产生冲突，因此团队内部应当约定好各自负责的资源维度，避免重复覆盖。
另外，TLS 是硬性要求。apiserver 不会向明文 HTTP 端点发送准入请求，你必须将服务证书挂载到容器，并在clientConfig中通过 CA 包校验。很多初学者在本地用自签证书但忘了把 CA 写进caBundle，导致配置生效却一直超时，这是排障时最先检查的项。
与策略引擎方案的对比及落地建议
当准入规则变得复杂，直接写 Webhook 会面临代码膨胀与测试成本上升。社区常用的 Open Policy Agent（OPA）Gatekeeper 或 Kyverno 提供了声明式策略语言，把“不允许特权容器”这类诉求写成 CRD 即可，不需要维护独立服务。它们底层仍是基于 Admission Webhook，只是把策略执行通用化。
对比来看，自研 Webhook 的优势在于逻辑自由度高，可以调用内部系统做实时查询，比如校验镜像是否来自审核过的仓库、工单号是否真实存在。而通用策略引擎擅长静态规则与批量审计，部署简单，社区策略库丰富。如果团队只是做基础安全基线，优先选 Kyverno；若准入动作依赖业务上下文，则保留自定义 Webhook 更合适。
在混合架构中，也可以让 Mutating Webhook 做统一注解注入，再用 Gatekeeper 做最终校验，分层负责。但务必控制 webhook 总数，因为每个请求都要串行经过它们，过多会显著拉长 API 延迟。建议通过namespaceSelector或objectSelector缩小监听范围，只对真正需要的资源生效，从而把性能损耗压到最低。
最后，任何准入组件上线前都应在预发集群做故障演练：主动关闭 Webhook 服务，观察failurePolicy是否符合预期；模拟大对象提交，确认超时与内存占用平稳。只有把降级路径想清楚，动态准入才能真正成为生产集群的护城河，而不是单点隐患。
KubernetesAdmission_Webhook准入控制修改时间：2026-08-18 12:02:34