📚 课程目录第4章 Webhook工作原理

4. Webhook 工作原理：请求流程、Admission Review、Webhook Server 部署模式

Webhook 是 Kubernetes 平台实现策略注入与资源变更的核心扩展机制。理解其工作原理，是构建生产级准入控制平台的基础。本节从请求流程、核心数据结构、服务部署三个维度展开。

4.1 请求流程：从 API 请求到准入决策

当用户通过 kubectl 或 API 调用创建/更新资源时，Kubernetes API Server 会在资源持久化之前，依次经过认证、鉴权、Mutating Webhook、对象校验、Validating Webhook 等阶段。下图展示了完整的准入请求链路：

关键时序：Mutating Webhook 先于 Validating Webhook 执行。Mutating 可以修改请求对象（如注入 Sidecar、设置默认值），修改后的对象再交给 Validating 做策略校验。两个阶段任一返回拒绝，资源都不会被持久化。

4.2 Admission Review：Webhook 的核心数据契约

Kubernetes API Server 与 Webhook Server 之间通过 AdmissionReview 对象进行通信。该对象是请求与响应的统一载体，定义在 k8s.io/api/admission/v1 包中。

4.2.1 请求结构（AdmissionRequest）

API Server 向 Webhook 发送的 POST 请求体中包含以下关键字段：

字段	类型	说明
`uid`	string	请求唯一标识，响应中必须原样返回
`kind`	GroupVersionKind	被操作资源的 GVK（如 Pod / v1）
`resource`	GroupVersionResource	被操作资源的 GVR（如 pods / v1）
`operation`	string	操作类型：CREATE / UPDATE / DELETE / CONNECT
`object`	RawExtension	请求对象的完整 JSON 表示（Mutating 阶段可修改）
`oldObject`	RawExtension	UPDATE/DELETE 时，集群中已有的旧对象
`userInfo`	UserInfo	发起请求的用户身份信息
`dryRun`	bool	是否为 DryRun 模式

4.2.2 响应结构（AdmissionResponse）

Webhook Server 必须在 30 秒内返回 AdmissionReview 响应，其中 response 字段包含：

字段	类型	说明
`uid`	string	必须与请求 uid 一致
`allowed`	bool	true 表示允许，false 表示拒绝
`status`	Status	拒绝时返回错误码与消息（如 403 Forbidden）
`patch`	[]byte	Mutating 模式下，返回 JSON Patch 操作（Base64 编码）
`patchType`	string	固定为 `JSONPatch`
`warnings`	[]string	警告信息，会展示给用户但不阻止请求

  开发要点：响应中的 uid 必须与请求一致，否则 API Server 会丢弃响应并记录错误。Mutating Webhook 的 patch 必须使用标准 JSON Patch 格式（RFC 6902），且操作路径必须正确。

4.3 Webhook Server 部署模式

Webhook Server 的部署方式直接影响可用性、延迟和运维复杂度。以下是三种主流部署模式的对比：

部署模式	架构描述	适用场景	注意事项
In-Cluster Service	Webhook 以 Deployment + Service 形式运行在集群内，API Server 通过 ClusterIP 或 NodePort 调用	标准生产环境，与集群网络同域	需配置 TLS 证书（通常使用 cert-manager 自动签发）
Out-of-Cluster HTTPS	Webhook 部署在集群外（如独立服务器、云函数），API Server 通过公网或专线 HTTPS 调用	多集群共享策略、遗留系统集成	延迟较高，需配置防火墙规则与外部 DNS
Sidecar / Agent 模式	Webhook 以 DaemonSet 或 Sidecar 形式运行在每个节点上，通过本地回环地址通信	低延迟、高吞吐场景（如大规模集群）	运维复杂度高，需管理节点级证书

4.3.1 In-Cluster 模式的标准配置示例

以下是一个典型的 Webhook 配置片段，展示如何通过 ValidatingWebhookConfiguration 将 API Server 指向集群内的 Webhook Service：

apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
metadata:
  name: "pod-policy.example.com"
webhooks:
- name: "pod-policy.example.com"
  clientConfig:
    service:
      namespace: "webhook-system"
      name: "webhook-service"
      path: "/validate"
    caBundle: "LS0tLS1CRUdJTiBDRV...=="  # Base64 编码的 CA 证书
  rules:
  - operations: ["CREATE", "UPDATE"]
    apiGroups: [""]
    apiVersions: ["v1"]
    resources: ["pods"]
  admissionReviewVersions: ["v1"]
  sideEffects: None
  timeoutSeconds: 10

证书与安全：Webhook 必须使用 TLS 1.2+ 证书，且证书的 CN 或 SAN 必须与 clientConfig.service 中的 DNS 名称匹配。生产环境推荐使用 cert-manager 自动管理证书轮换，避免手动更新 caBundle。

4.4 部署模式对比图

下图从网络路径和组件依赖角度，对比 In-Cluster 与 Out-of-Cluster 两种模式的架构差异：

4.5 生产环境部署建议

超时设置：timeoutSeconds 建议设为 5-10 秒，避免 Webhook 阻塞 API Server 请求队列。
失败策略：failurePolicy 在关键策略（如安全准入）上设为 Fail，在辅助功能（如标签注入）上设为 Ignore。
资源过滤：通过 namespaceSelector 和 objectSelector 缩小 Webhook 作用范围，减少不必要的调用。
高可用：Webhook 服务至少部署 2 个副本，并配置 Pod Anti-Affinity 避免单点故障。
监控与日志：记录每次 AdmissionReview 的请求耗时、拒绝原因、patch 大小，用于容量规划与审计。

最佳实践：在开发阶段使用 kubectl plugin 或本地代理工具（如 telepresence）将 Webhook 服务暴露到本地，配合 --dry-run=server 快速验证策略逻辑，避免频繁部署。