3. Webhook 开发入门：使用 Go 语言开发一个简单的 Webhook Server

本节将带领你从零开始，使用 Go 语言构建一个最小可用的准入控制 Webhook Server。你将掌握 HTTP Handler 的编写方法、请求与响应的数据结构解析，以及如何将 Webhook 注册到 Kubernetes 集群中。这是后续实现并发处理与 Operator 容量优化的基础。

3.1 Webhook Server 的核心架构

一个标准的准入控制 Webhook Server 本质上是一个 HTTPS 服务，它接收来自 Kubernetes API Server 的 AdmissionReview 请求，根据业务逻辑判断是否允许资源操作，并返回 AdmissionReview 响应。下图展示了请求与响应的流转路径：

3.2 项目初始化与依赖

创建一个新的 Go 模块，并引入 Kubernetes API 的依赖包：

mkdir webhook-demo && cd webhook-demo
go mod init webhook-demo
go get k8s.io/api@v0.28.0
go get k8s.io/apimachinery@v0.28.0

3.3 HTTP Handler 编写

Webhook Server 的核心是 HTTP Handler。它需要完成三个步骤：解码请求、执行业务逻辑、编码响应。以下是一个完整的 Handler 实现：

package main

import (
    "encoding/json"
    "fmt"
    "net/http"

    admissionv1 "k8s.io/api/admission/v1"
    metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
)

// 全局的 HTTP Handler 函数
func admitHandler(w http.ResponseWriter, r *http.Request) {
    // 1. 解码请求
    var review admissionv1.AdmissionReview
    if err := json.NewDecoder(r.Body).Decode(&review); err != nil {
        http.Error(w, err.Error(), http.StatusBadRequest)
        return
    }

    // 2. 执行业务逻辑（此处为示例：始终允许）
    responseReview := admissionv1.AdmissionReview{
        TypeMeta: metav1.TypeMeta{
            APIVersion: "admission.k8s.io/v1",
            Kind:       "AdmissionReview",
        },
        Response: &admissionv1.AdmissionResponse{
            UID:     review.Request.UID,
            Allowed: true,
        },
    }

    // 3. 编码响应
    w.Header().Set("Content-Type", "application/json")
    if err := json.NewEncoder(w).Encode(responseReview); err != nil {
        http.Error(w, err.Error(), http.StatusInternalServerError)
    }
}

3.4 请求与响应结构详解

AdmissionReview 是 Webhook 通信的顶层结构。下表对比了请求和响应中核心字段的差异：

3.5 启动 HTTPS 服务

Webhook Server 必须使用 HTTPS 协议。以下代码展示了如何加载 TLS 证书并启动服务：

func main() {
    // 注册路由
    http.HandleFunc("/validate", admitHandler)

    // 启动 HTTPS 服务
    // 需要提前准备 server.crt 和 server.key
    err := http.ListenAndServeTLS(":8443", "server.crt", "server.key", nil)
    if err != nil {
        fmt.Printf("启动失败: %v\n", err)
    }
}

3.6 注册 Webhook 到 Kubernetes

编写一个 ValidatingWebhookConfiguration 资源，将 Webhook Server 注册到集群中：

apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
metadata:
  name: demo-webhook
webhooks:
- name: demo.example.com
  clientConfig:
    url: "https://webhook-service:8443/validate"
    caBundle: <base64 编码的 CA 证书>
  rules:
  - operations: ["CREATE", "UPDATE"]
    apiGroups: [""]
    apiVersions: ["v1"]
    resources: ["pods"]
  admissionReviewVersions: ["v1"]
  sideEffects: None

3.7 完整项目结构

一个最小可用的 Webhook 项目通常包含以下文件：

• main.go — 入口文件，包含 HTTP 路由注册和 TLS 启动逻辑
• handler.go — 核心 Handler 实现，包含请求解码、业务逻辑、响应编码
• webhook.go — 可选，封装 Webhook 配置和工具函数
• server.crt / server.key — TLS 证书和私钥
• Dockerfile — 容器化构建文件
• deployment.yaml — Kubernetes Deployment 和 Service 配置

下图展示了项目文件之间的依赖关系与构建流程：

3.8 常见错误与排查

在开发 Webhook 时，以下错误最为常见：

• 证书不匹配： API Server 无法验证 Webhook 的 TLS 证书，导致连接被拒绝。检查 caBundle 是否与服务器证书匹配。
• UID 不一致： 响应中的 UID 与请求不一致，API Server 会返回 InternalError。
• 超时设置： 默认 Webhook 超时为 10 秒，如果 Handler 处理时间过长，API Server 会中断连接并拒绝操作。
• 响应格式错误： 返回的 JSON 不符合 AdmissionReview 结构，API Server 无法解析。