Webhook 准入控制系统

Volcano Admission Webhook 系统的完整技术参考文档。 核心源码路径: pkg/webhooks/

1. 概述#

Volcano Webhook 准入控制系统基于 Kubernetes Admission Webhook 机制，对 Volcano CRD 资源 (Job, Queue, PodGroup, CronJob, JobFlow, HyperNode) 以及原生 Pod 资源执行准入验证 (Validating) 和变更注入 (Mutating)。系统由 vc-webhook-manager 组件运行，通过 ValidatingWebhookConfiguration 和 MutatingWebhookConfiguration 向 API Server 注册。

1.1 核心能力#

• 资源验证: 在 CREATE / UPDATE / DELETE 操作前验证资源的合法性
• 默认值注入: 在 CREATE 操作时自动填充缺省字段
• 策略约束: 确保资源配置符合集群管理策略
• 层级队列管理: 验证队列的父子关系和资源约束
• DAG 验证: 验证 Job 和 JobFlow 的依赖关系是否构成有向无环图
• 拓扑验证: 验证 HyperNode 的成员配置合法性

1.2 Webhook 类型#

2. Webhook 架构#

2.1 核心组件#

2.2 Router 核心接口#

AdmitFunc - 所有 Admission Handler 的统一函数签名:

// 源码: pkg/webhooks/router/interface.go
type AdmitFunc func(admissionv1.AdmissionReview) *admissionv1.AdmissionResponse

AdmissionService - 描述一个 Admission Webhook 服务:

type AdmissionService struct {
    Path    string                // HTTP 路径，如 "/jobs/validate"
    Func    AdmitFunc             // 处理函数
    Handler AdmissionHandler      // HTTP Handler (由 RegisterAdmission 自动生成)

    ValidatingConfig *whv1.ValidatingWebhookConfiguration  // Validating 配置
    MutatingConfig   *whv1.MutatingWebhookConfiguration    // Mutating 配置

    Config *AdmissionServiceConfig  // 运行时配置 (客户端、Lister 等)
}

AdmissionServiceConfig - 运行时依赖注入，包含 SchedulerNames、KubeClient、VolcanoClient、QueueLister、QueueInformer、Recorder 和 ConfigData 等运行时配置。

2.3 注册机制#

每个 Webhook Handler 通过 init() 函数 + blank import 的方式自动注册:

2.4 HTTP 请求处理流程#

// 源码: pkg/webhooks/router/server.go
func Serve(w io.Writer, r *http.Request, admit AdmitFunc) {
    // 1. 读取请求 Body
    // 2. 校验 Content-Type 为 application/json
    // 3. 反序列化为 AdmissionReview
    // 4. 调用 admit(ar) 获取 AdmissionResponse
    // 5. 构建响应并写回
}

3. Webhook 注册表#

以下是 Volcano 中所有 11 个 Webhook 的完整注册信息:

4. Job Validation 规则#

源码: pkg/webhooks/admission/jobs/validate/admit_job.go

4.1 CREATE 验证#

4.2 UPDATE 验证#

UPDATE 操作的验证规则:

• Task 数量不能增减 (len(old.Tasks) != len(new.Tasks))
• 仅允许修改 minAvailable、tasks[*].replicas 和 PriorityClassName
• 各 Task 的 replicas >= 0、minAvailable <= replicas
• 全局 minAvailable <= totalReplicas
• NetworkTopology 的 highestTierAllowed 和 highestTierName 互斥
• PartitionPolicy 约束检查

4.3 关键验证项汇总#

5. Job Mutation 规则#

源码: pkg/webhooks/admission/jobs/mutate/mutate_job.go

Job Mutation 仅在 CREATE 操作时触发，通过 JSON Patch 机制注入默认值:

5.1 默认值注入规则#

5.2 Plugin 自动添加#

当 Job 配置了特定分布式框架 Plugin 时，自动添加依赖的 Plugin:

6. Queue Validation 规则#

源码: pkg/webhooks/admission/queues/validate/validate_queue.go

6.1 CREATE/UPDATE 验证#

6.2 State 验证#

合法的 Queue 状态值:

• Open - 队列开放，接受作业提交
• Closed - 队列关闭

6.3 资源约束验证#

资源字段的约束关系:

Guarantee <= Deserved <= Capability

具体验证逻辑:

6.4 层级队列验证#

6.5 DELETE 验证#

7. Queue Mutation 规则#

源码: pkg/webhooks/admission/queues/mutate/mutate_queue.go

Queue Mutation 仅在 CREATE 操作时触发:

8. PodGroup Validation#

源码: pkg/webhooks/admission/podgroups/validate/validate_podgroup.go

PodGroup Validation 仅在 CREATE 操作时触发:

9. PodGroup Mutation#

源码: pkg/webhooks/admission/podgroups/mutate/mutate_podgroup.go

PodGroup Mutation 仅在 CREATE 操作时触发，处理 Namespace 级别的队列覆盖:

10. Pod Validation#

源码: pkg/webhooks/admission/pods/validate/admit_pod.go

Pod Validation 仅在 CREATE 操作时触发:

10.1 调度器过滤#

仅对 schedulerName 在配置的 Volcano 调度器名称列表中的 Pod 生效，非 Volcano 调度的 Pod 直接放行。

10.2 PDB Annotation 验证#

验证 Pod 上的 PodDisruptionBudget 相关 Annotation:

互斥约束: 上述两个 Annotation 不能同时配置。

11. Pod Mutation#

源码: pkg/webhooks/admission/pods/mutate/mutate_pod.go

Pod Mutation 基于 AdmissionConfiguration 文件中定义的 Resource Group 规则进行 Pod 注入:

11.1 Resource Group 匹配机制#

支持两种 Resource Group 匹配方式:

11.2 注入内容#

12. CronJob Validation#

源码: pkg/webhooks/admission/cronjobs/validate/admit_cronjob.go

CronJob Validation 在 CREATE 和 UPDATE 操作时触发:

12.1 验证规则#

12.2 Name 长度限制说明#

CronJob 创建 Job 时会自动添加时间戳后缀 (最多 11 字符)，Kubernetes 资源名最大为 63 字符，因此 CronJob Name 限制为 63 - 11 = 52 字符。

13. JobFlow Validation#

源码: pkg/webhooks/admission/jobflows/validate/validate_jobflow.go

JobFlow Validation 在 CREATE 和 UPDATE 操作时触发:

验证规则:

• 所有 Flow 中引用的依赖目标 (DependsOn.Targets) 必须在 Flows 列表中定义
• 依赖关系图必须构成 DAG (有向无环图)，不允许存在循环依赖

14. HyperNode Validation#

源码: pkg/webhooks/admission/hypernodes/validate/admit_hypernode.go

HyperNode Validation 在 CREATE 和 UPDATE 操作时触发:

注意: Selector 互斥性、字段格式等验证由 CRD Schema (kubebuilder validation) 和 CEL XValidation 规则处理，Webhook 仅负责 CRD 层面无法覆盖的运行时验证。

15. Admission 处理流程#

以下序列图展示了从 API Server 到 Webhook Handler 的完整请求处理链路:

16. 配置管理#

16.1 Enabled Admission 配置#

Webhook Manager 通过 --enabled-admission 参数控制启用哪些 Webhook。ForEachAdmission() 函数解析该配置并遍历已启用的 Admission:

// 源码: pkg/webhooks/router/admission.go
func ForEachAdmission(config *options.Config, handler func(*AdmissionService) error) error {
    admissions := strings.Split(strings.TrimSpace(config.EnabledAdmission), ",")
    for _, admission := range admissions {
        if service, found := admissionMap[admission]; found {
            if err := handler(service); err != nil {
                return err
            }
        }
    }
    return nil
}

16.2 AdmissionConfiguration 文件#

AdmissionConfiguration 用于 Pod Mutation Webhook 的 Resource Group 配置:

// 源码: pkg/webhooks/config/config.go
type AdmissionConfiguration struct {
    sync.Mutex
    ResGroupsConfig []ResGroupConfig `yaml:"resourceGroups"`
}

type ResGroupConfig struct {
    ResourceGroup string            `yaml:"resourceGroup"`
    Object        Object            `yaml:"object"`
    SchedulerName string            `yaml:"schedulerName"`
    Tolerations   []v1.Toleration   `yaml:"tolerations"`
    Labels        map[string]string `yaml:"labels"`
    Affinity      string            `yaml:"affinity"`
}

type Object struct {
    Key   string   `yaml:"key"`
    Value []string `yaml:"value"`
}

16.3 配置文件示例#

# admission-configuration.yaml
resourceGroups:
  - resourceGroup: "gpu-group"
    object:
      key: "namespace"
      value: ["gpu-workloads", "ml-training"]
    schedulerName: "volcano"
    labels:
      accelerator: "nvidia-gpu"
    tolerations:
      - key: "nvidia.com/gpu"
        operator: "Exists"
        effect: "NoSchedule"
  - resourceGroup: "cpu-group"
    object:
      key: "annotation"
      value: ["volcano.sh/resource-group: cpu-intensive"]
    schedulerName: "volcano"
    labels:
      workload-type: "cpu"

16.4 配置热加载#

AdmissionConfiguration 支持通过文件系统监控 (fsnotify) 实现热加载。WatchAdmissionConf() 函数监控配置文件目录，在 Write 或 Create 事件时自动重新解析并更新 admissionConf 全局配置。

17. Schema 解码器#

pkg/webhooks/schema/schema.go 提供了各种 CRD 资源的解码函数:

每个解码函数验证 resource 与期望的 GroupVersionResource 匹配后，使用 Codecs.UniversalDeserializer() 反序列化原始字节并返回类型化对象。