Admission Webhook是Kubernetes准入控制器体系中最灵活的扩展机制。APIServer在处理任何写请求（创建、更新、删除以及connect类请求）时，都会经过一条准入控制链，其中就包括通过HTTP回调外部Webhook服务的环节。开发者只需要部署一个普通的HTTP服务，向APIServer注册对应的WebhookConfiguration，就能介入资源的校验和默认值注入流程。本文从原理、代码实现、部署配置三个层面完整讲一遍Admission Webhook的开发过程。
一、Validating与Mutating：两类Webhook的职责与执行顺序
Kubernetes的准入链分为两个阶段：先执行Mutating（变更）阶段，再执行Validating（校验）阶段。Mutating Webhook负责对资源对象进行修改，比如给Pod注入sidecar容器、补全默认的环境变量、设置默认的资源请求值；Validating Webhook则只做判断，允许或者拒绝这次请求，不能修改对象内容。先变更后校验的顺序是有意设计的，这样校验阶段看到的一定是最终会被持久化的对象状态，避免出现“校验通过但实际落库的对象又变了”的漏洞。
两类Webhook在行为上还有几个容易踩坑的差异。第一，Mutating Webhook修改对象时，通过AdmissionResponse中的patch字段返回一个JSON Patch（RFC 6902），而不是直接返回修改后的完整对象，APIServer会负责应用补丁。第二，如果一个对象匹配了多个Mutating Webhook，每个Webhook都可能被调用多次，因为第一个Webhook修改后的结果可能重新匹配另一个Webhook的规则，这个循环有次数上限，超过后整个请求失败。第三，Validating Webhook一旦有一个返回拒绝，请求立即终止，后续的Webhook不会再执行。
选型上有个简单原则：逻辑是“必须有某个字段，没有就补上”就用Mutating；逻辑是“字段取值不合法就报错”就用Validating。很多场景两者配合使用，比如先由Mutating注入默认镜像仓库地址，再由Validating确认镜像来源符合公司规范。
二、用Go编写Webhook Server
编写Webhook Server本质上是实现一个处理AdmissionReview的HTTP接口。APIServer会把请求体封装成AdmissionReview对象POST过来，服务解析后返回一个带AdmissionResponse的AdmissionReview。下面用一个校验Pod资源限制的例子演示核心代码：
package main
import (
"encoding/json"
"net/http"
admissionv1 "k8s.io/api/admission/v1"
corev1 "k8s.io/api/core/v1"
"k8s.io/apimachinery/pkg/runtime"
"k8s.io/apimachinery/pkg/runtime/serializer"
)
var scheme = runtime.NewScheme()
func init() {
_ = corev1.AddToScheme(scheme)
}
func handleAdmission(w http.ResponseWriter, r *http.Request) {
decoder := serializer.NewCodecFactory(scheme).UniversalDeserializer()
var review admissionv1.AdmissionReview
if err := json.NewDecoder(r.Body).Decode(&review); err != nil {
http.Error(w, "invalid request", http.StatusBadRequest)
return
}
var pod corev1.Pod
_ = json.Unmarshal(review.Request.Object.Raw, &pod)
// 校验逻辑：所有容器必须设置资源限制
var allowed = true
var message string
for _, c := range pod.Spec.Containers {
if c.Resources.Limits.Cpu().IsZero() {
allowed = false
message = "container " + c.Name + " has no CPU limit"
break
}
}
resp := &admissionv1.AdmissionReview{
Response: &admissionv1.AdmissionResponse{
UID: review.Request.UID,
Allowed: allowed,
},
}
if !allowed {
resp.Response.Result = &metav1.Status{Message: message}
}
_ = json.NewEncoder(w).Encode(resp)
}
func main() {
http.HandleFunc("/validate", handleAdmission)
// Webhook必须使用TLS，默认端口一般为443或8443
_ = http.ListenAndServeTLS(":8443", "tls.crt", "tls.key", nil)
}这段代码有几个必须注意的点。返回的AdmissionResponse中UID一定要原样回传请求中的UID，否则APIServer无法关联请求与响应。allowed为false时，通过Result.Message给出人类可读的拒绝原因，kubectl会直接把这段话展示给用户。如果是Mutating Webhook，则需要构造JSON Patch并通过Response.PatchType设置为admissionv1.PatchTypeJSONPatch，Patch字段是base64编码后的补丁内容。
生产环境建议直接使用controller-runtime项目的admission包，它提供了Decorator、Handler抽象以及注入Client的能力，能省去大量手写AdmissionReview解析的样板代码。另外服务要保证幂等和快速响应，APIServer默认超时只有10秒（可在WebhookConfiguration中调整，上限30秒），超时会按failurePolicy的策略决定放行还是拒绝。
三、注册WebhookConfiguration与TLS证书管理
服务写好后，需要在集群中创建ValidatingWebhookConfiguration或MutatingWebhookConfiguration，告诉APIServer哪些资源、哪些操作要回调到哪个地址。下面是一个典型配置：
apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
metadata:
name: pod-resource-validate
webhooks:
- name: validate.pod.example.ipipp.com
admissionReviewVersions: ["v1"]
sideEffects: None
failurePolicy: Fail
timeoutSeconds: 5
clientConfig:
service:
name: webhook-service
namespace: webhook-system
path: /validate
rules:
- operations: ["CREATE", "UPDATE"]
apiGroups: [""]
apiVersions: ["v1"]
resources: ["pods"]
namespaceSelector:
matchExpressions:
- key: webhook-enabled
operator: In
values: ["true"]配置中有几个关键字段。failurePolicy决定Webhook不可用时的行为，Fail表示直接拒绝请求（安全优先），Ignore表示跳过校验（可用性优先），要根据业务重要性权衡。namespaceSelector可以限定Webhook只作用于打了特定标签的命名空间，这一点非常重要，否则Webhook可能会拦截系统命名空间的操作，甚至把自己卡死——如果Webhook服务的Pod创建请求也被自己的Webhook拦截，就会出现死锁，集群永远拉不起来服务。常见的规避做法是排除kube-system和kube-node-lease命名空间，或者用objectSelector跳过特定标签的对象。
TLS证书是最容易出问题的环节。APIServer只接受HTTPS回调，证书必须包含Webhook服务的DNS名（形如service-name.namespace.svc）。可以用cert-manager自动签发和轮换，也可以用集群CA手动签发。需要特别注意的是，若证书由集群根CA签发，需要在clientConfig.caBundle中填入CA证书的base64编码；使用cert-manager时可以用注解让cert-manager自动注入。证书过期后所有匹配的写请求都会失败，务必配置监控告警或直接上cert-manager的自动续期。
四、调试技巧与常见问题排查
开发阶段的调试可以分三层进行。第一层是本地单元测试，直接构造AdmissionReview对象调用处理函数，用go test验证校验逻辑的分支覆盖。第二层是本地起服务，用curl模拟APIServer的POST请求，构造一个AdmissionReview JSON发过去，观察返回的allowed字段是否符合预期。第三层才是接入真实集群，通过kubectl apply触发请求，用kubectl explain或查看Webhook服务的日志确认调用链路。
接入集群后如果请求被莫名拒绝，排查思路通常是这样的：先用kubectl get validatingwebhookconfiguration查看配置是否存在，再检查服务端点是否可达（kubectl get endpoints），然后看APIServer日志中关于webhook调用失败的记录。常见报错包括x509证书校验失败（caBundle不对或证书SAN缺失）、connection refused（服务未就绪）、context deadline exceeded（处理太慢触发超时）。另外记得admissionReviewVersions必须包含APIServer支持的版本，v1.16以下的旧集群只支持v1beta1，写错版本会导致Webhook注册成功但从不被调用。
最后一点实践建议：上线前务必给Webhook配置合理的scope，排除自身依赖的命名空间；灰度阶段可以先把failurePolicy设为Ignore观察日志，确认逻辑无误后再切换为Fail；同时为Webhook服务设置独立的PodDisruptionBudget和资源请求，避免它成为集群写入链路上的单点瓶颈。只要把证书、超时、作用范围这三件事处理好，Admission Webhook就能成为集群治理中非常趁手的工具。
Admission WebhookKubernetes准入控制修改时间：2026-09-07 16:34:48