API Server：集群的统一入口¶

kube-apiserver 是控制面中公开 Kubernetes HTTP API 的核心组件。kubectl、Controller、Scheduler 和 Kubelet 都通过它读取或更新 API 对象；通过校验的写请求由其存储层写入 etcd。API Server 通过 etcd Watch 更新内存中的 Watch Cache，完整的数据流和客户端续接语义见 etcd Watch 机制。

这里以创建 default/vllm-demo Deployment 为例，说明一条写请求在 API Server 中的处理过程。kubectl 提交资源后，API Server 依次执行身份认证、授权、Mutating Admission、资源对象校验和 Validating Admission，再通过存储层将 Deployment 写入 etcd。未启用服务端 dry-run 时，返回 201 Created 表示 Deployment 已完成持久化。

Deployment 资源清单¶

vllm-demo Deployment 中需要关注以下配置：

• Pod 选择器：spec.selector.matchLabels 与 spec.template.metadata.labels 都使用 app: vllm-demo，满足 Deployment selector 必须匹配 Pod template label 的校验规则。
• 运行时与 GPU：runtimeClassName: nvidia 选择节点上的 nvidia runtime handler。limits.nvidia.com/gpu: "1" 为 Pod 申请一张 GPU。
• 模型缓存：vllm-model-cache PVC 挂载到 /root/.cache/huggingface，Pod 重建后可以继续使用已经下载的模型文件。
• vLLM 进程：容器使用 vllm/vllm-openai:v0.27.1 镜像，执行 vllm serve Qwen/Qwen3-0.6B --port 8000。

apiVersion: apps/v1
kind: Deployment
metadata:
  name: vllm-demo
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: vllm-demo
  template:
    metadata:
      labels:
        app: vllm-demo
    spec:
      runtimeClassName: nvidia
      containers:
        - name: vllm
          image: vllm/vllm-openai:v0.27.1
          command: ["vllm", "serve"]
          args: ["Qwen/Qwen3-0.6B", "--port", "8000"]
          ports:
            - containerPort: 8000
          resources:
            limits:
              nvidia.com/gpu: "1"
          volumeMounts:
            - name: model-cache
              mountPath: /root/.cache/huggingface
      volumes:
        - name: model-cache
          persistentVolumeClaim:
            claimName: vllm-model-cache

使用 kubectl apply 提交 Deployment：

kubectl apply -f examples/chapter-01/12-vllm/02-deployment.yaml

首次创建 Deployment 时，请求目标是：

POST /apis/apps/v1/namespaces/default/deployments

下图展示了 Deployment 创建请求从 TLS 连接到持久化的主要路径，包含身份认证、授权、准入、资源对象校验和存储。

flowchart LR
    K["kubectl / REST client"] --> T["TLS 与 RequestInfo"]
    T --> AU["Authentication\n调用者是谁"]
    AU --> AZ["Authorization\n能否创建 Deployment"]
    AZ --> MA["Mutating Admission\n允许修改对象"]
    MA --> V["资源对象校验\nDeployment 固有规则"]
    V --> VA["Validating Admission\n允许拒绝对象"]
    VA --> S["Registry / Storage"]
    S --> E["etcd"]
    E --> R["201 Created"]

Deployment 写入 etcd 后，后续组件继续通过 API Server 读取和更新对象。工作负载对象的创建见 Controller：从 Deployment 到 Pod，节点选择见 Scheduler：Pod 的节点选择，节点执行见 Kubelet：节点上的 Pod 管理。

身份认证¶

客户端先与 API Server 建立 TLS 连接。kubectl 从 kubeconfig 读取 API 地址、CA 和客户端凭据，认证模块据此得到用户名与用户组。API Server 支持 ServiceAccount Token、客户端证书、OIDC Token 和认证 Webhook 等认证方式。

认证模块完成凭据校验后，使用 user.Info 保存用户名、UID、用户组和附加属性。Kubernetes v1.36.4 的源码定义包含四个方法：

type Info interface {
    GetName() string
    GetUID() string
    GetGroups() []string
    GetExtra() map[string][]string
}

user.DefaultInfo 是这个接口的常用实现。例如，一个经过 OIDC 认证的用户可以表示为：

&user.DefaultInfo{
    Name:   "alice@example.com",
    UID:    "00u123456",
    Groups: []string{"platform-admins", "system:authenticated"},
    Extra: map[string][]string{
        "example.com/tenant": []string{"ai-platform"},
    },
}

Name、UID、Groups 和 Extra 分别对应四个 getter。具体值由认证模块填写，客户端证书认证通常提供用户名和用户组，OIDC 或认证 Webhook 还可以提供 UID 与附加属性。API Server 将这份信息放入请求上下文，授权、审计和准入随后读取它。

以下命令通过当前 kubeconfig 查询自己的 user.Info，输出位于 status.userInfo：

kubectl auth whoami -o yaml

认证失败通常返回 401 Unauthorized；允许匿名请求的集群会将未认证请求识别为匿名用户，并送入授权阶段。

请求授权¶

授权阶段判断当前身份能否执行请求中的操作。

RBAC 使用 Role 保存权限规则，使用 RoleBinding 将这些权限授予用户、用户组或 ServiceAccount。下面的 Role 允许在 default namespace 创建 Deployment；RoleBinding 将这项权限授予用户 alice@example.com。

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: vllm-deployment-creator
  namespace: default
rules:
  - apiGroups: ["apps"]
    resources: ["deployments"]
    verbs: ["create"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: alice-vllm-deployment-creator
  namespace: default
subjects:
  - kind: User
    name: alice@example.com
    apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: Role
  name: vllm-deployment-creator
  apiGroup: rbac.authorization.k8s.io

这组配置只允许 alice@example.com 在 default namespace 创建 Deployment。

集群管理员可以模拟 Alice 的身份，验证这项权限：

kubectl auth can-i create deployments.apps \
  --namespace default \
  --as alice@example.com

使用 --as 需要当前身份具备 impersonate 权限。Alice 使用自己的 kubeconfig 时可以省略该参数。RBAC 允许请求后，API Server 继续执行 Admission 和类型校验；授权拒绝时返回 403 Forbidden。

准入控制¶

准入控制位于授权之后、对象持久化之前，主要处理创建、更新和删除等资源写操作。Mutating Admission 可以修改请求对象，Validating Admission 根据对象和策略决定是否放行。GET、LIST 和 WATCH 等读取操作直接绕过准入控制。

API Server 先运行 Mutating Admission，再完成资源对象校验，随后运行 Validating Admission。任一准入插件拒绝请求，当前对象都不会写入 etcd。完整的处理顺序和插件列表见 Kubernetes 中的准入控制。

准入阶段¶

准入控制分为修改和校验两个阶段。Mutating Admission 先修改或拒绝对象；通过修改阶段的对象再进入 Validating Admission。校验阶段保留对象内容，可以放行、拒绝、告警或记录审计信息；任一拒绝结果都会终止当前请求。

下图在 Kubernetes 官方流程图中补充了 MutatingAdmissionPolicy。四个准入扩展点的相对顺序是 MutatingAdmissionPolicy、Mutating Webhook、ValidatingAdmissionPolicy 和 Validating Webhook。

图：Kubernetes v1.36 Admission Control 阶段。在 Kubernetes 官方流程图基础上补充 MutatingAdmissionPolicy，CC BY 4.0。

MutatingAdmissionPolicy¶

Kubernetes v1.36 提供 Stable 的 MutatingAdmissionPolicy。它在 API Server 进程内执行 CEL，使用 ApplyConfiguration 或 JSON Patch 修改对象，不需要部署 HTTPS Webhook。具体 API 和补丁类型见 Mutating Admission Policy。

apiVersion: admissionregistration.k8s.io/v1
kind: MutatingAdmissionPolicy
metadata:
  name: add-managed-by-annotation.example.com
spec:
  failurePolicy: Fail
  reinvocationPolicy: Never
  matchConstraints:
    resourceRules:
      # 这条 Policy 只修改新建的 apps/v1 Deployment。
      - apiGroups: ["apps"]
        apiVersions: ["v1"]
        operations: ["CREATE"]
        resources: ["deployments"]
  mutations:
    - patchType: ApplyConfiguration
      applyConfiguration:
        # ApplyConfiguration 合并目标 annotation，保留对象中已有的其他 annotation。
        expression: >-
          Object{
            metadata: Object.metadata{
              annotations: {
                "admission.example.com/managed-by": "mutating-admission-policy"
              }
            }
          }
---
apiVersion: admissionregistration.k8s.io/v1
kind: MutatingAdmissionPolicyBinding
metadata:
  name: add-managed-by-annotation.example.com
spec:
  # Policy 只有被 Binding 引用后才会执行。
  policyName: add-managed-by-annotation.example.com
  matchResources:
    # Kubernetes 自动为 Namespace 添加这个不可变标签。
    namespaceSelector:
      matchLabels:
        kubernetes.io/metadata.name: default

kubectl apply \
  -f examples/chapter-01/02-02-admission/01-mutating-admission-policy/policy.yaml
kubectl apply \
  --dry-run=server \
  -f examples/chapter-01/02-02-admission/01-mutating-admission-policy/input.yaml \
  -o yaml

Mutating Webhook¶

MutatingAdmissionWebhook 根据 MutatingWebhookConfiguration 中的资源、操作、命名空间和对象选择器匹配请求，再按顺序调用外部 HTTPS Webhook。API Server 使用 AdmissionReview 发送请求；Webhook 可以返回 JSON Patch 修改对象，也可以拒绝请求。

每个 Webhook 都可以配置超时和调用失败时的处理方式。timeoutSeconds 默认为 10 秒，failurePolicy 默认为 Fail。配置了 reinvocationPolicy: IfNeeded 的 Webhook 还可能在对象被后续 Webhook 修改后再次执行。

apiVersion: admissionregistration.k8s.io/v1
kind: MutatingWebhookConfiguration
metadata:
  name: pod-labeler.example.com
webhooks:
  - name: pod-labeler.example.com
    admissionReviewVersions: ["v1"]
    sideEffects: None
    failurePolicy: Fail
    matchPolicy: Equivalent
    reinvocationPolicy: IfNeeded
    timeoutSeconds: 5
    clientConfig:
      service:
        namespace: admission-demo
        name: admission-webhook
        path: /mutate
        port: 443
      # 部署脚本生成 CA；注册前将占位符替换为 Secret 中的 base64 数据。
      caBundle: "${CA_BUNDLE}"
    namespaceSelector:
      matchLabels:
        kubernetes.io/metadata.name: default
    rules:
      # 只对 Pod CREATE 返回 JSON Patch，不处理后续 UPDATE。
      - operations: ["CREATE"]
        apiGroups: [""]
        apiVersions: ["v1"]
        resources: ["pods"]
        scope: Namespaced

package main

import (
    "log"
    "net/http"
    "time"
)

func main() {
    mux := newServeMux()
    server := &http.Server{
        Addr:              ":8443",
        Handler:           mux,
        ReadHeaderTimeout: 5 * time.Second,
    }

    log.Println("admission webhook listening on :8443")
    // kube-apiserver 只调用 HTTPS Webhook；证书通常由 Secret 挂载到 /tls。
    log.Fatal(server.ListenAndServeTLS("/tls/tls.crt", "/tls/tls.key"))
}

func newServeMux() *http.ServeMux {
    mux := http.NewServeMux()
    // 两个 WebhookConfiguration 使用不同 path，共用同一个 HTTPS 服务。
    mux.Handle("/mutate", admissionHandler(mutatePod))
    mux.Handle("/validate", admissionHandler(validatePod))
    // HTTPS 健康检查不进入 AdmissionReview 解码逻辑。
    mux.HandleFunc("/healthz", func(w http.ResponseWriter, _ *http.Request) {
        w.WriteHeader(http.StatusOK)
    })
    return mux
}

package main

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

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

type admissionFunc func(*admissionv1.AdmissionRequest) admissionv1.AdmissionResponse

func admissionHandler(handle admissionFunc) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        if r.Method != http.MethodPost {
            http.Error(w, "only POST is supported", http.StatusMethodNotAllowed)
            return
        }

        mediaType, _, err := mime.ParseMediaType(r.Header.Get("Content-Type"))
        if err != nil || mediaType != "application/json" {
            http.Error(w, "Content-Type must be application/json", http.StatusUnsupportedMediaType)
            return
        }

        var review admissionv1.AdmissionReview
        // 限制请求体大小，避免异常请求占用过多内存。
        body := http.MaxBytesReader(w, r.Body, 1<<20)
        if err := json.NewDecoder(body).Decode(&review); err != nil {
            http.Error(w, fmt.Sprintf("decode AdmissionReview: %v", err), http.StatusBadRequest)
            return
        }
        if review.Request == nil {
            http.Error(w, "AdmissionReview.request is required", http.StatusBadRequest)
            return
        }

        response := handle(review.Request)
        // AdmissionResponse 必须回显 request.uid，API Server 用它匹配请求和响应。
        response.UID = review.Request.UID
        responseReview := admissionv1.AdmissionReview{
            TypeMeta: metav1.TypeMeta{
                APIVersion: admissionv1.SchemeGroupVersion.String(),
                Kind:       "AdmissionReview",
            },
            Response: &response,
        }

        // allowed=false 也是一次成功的 Webhook 调用，因此业务拒绝仍返回 HTTP 200。
        w.Header().Set("Content-Type", "application/json")
        if err := json.NewEncoder(w).Encode(responseReview); err != nil {
            log.Printf("encode AdmissionReview response: %v", err)
        }
    })
}

func allowed() admissionv1.AdmissionResponse {
    return admissionv1.AdmissionResponse{Allowed: true}
}

func denied(code int32, message string) admissionv1.AdmissionResponse {
    return admissionv1.AdmissionResponse{
        Allowed: false,
        Result: &metav1.Status{
            Code:    code,
            Message: message,
        },
    }
}

package main

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

    admissionv1 "k8s.io/api/admission/v1"
    corev1 "k8s.io/api/core/v1"
)

const managedLabel = "admission.example.com/managed"

type jsonPatchOperation struct {
    Operation string `json:"op"`
    Path      string `json:"path"`
    Value     any    `json:"value,omitempty"`
}

func mutatePod(request *admissionv1.AdmissionRequest) admissionv1.AdmissionResponse {
    var pod corev1.Pod
    if err := json.Unmarshal(request.Object.Raw, &pod); err != nil {
        return denied(http.StatusBadRequest, "decode Pod: "+err.Error())
    }

    if pod.Labels[managedLabel] == "true" {
        // reinvocationPolicy=IfNeeded 可能再次调用 Webhook，重复执行时不再生成补丁。
        return allowed()
    }

    var patch jsonPatchOperation
    if pod.Labels == nil {
        // JSON Patch 不能向不存在的父路径添加子字段，先创建完整的 labels map。
        patch = jsonPatchOperation{
            Operation: "add",
            Path:      "/metadata/labels",
            Value:     map[string]string{managedLabel: "true"},
        }
    } else {
        // JSON Pointer 用 ~1 表示 label key 中的斜杠。
        patch = jsonPatchOperation{
            Operation: "add",
            Path:      "/metadata/labels/admission.example.com~1managed",
            Value:     "true",
        }
    }

    patchBytes, err := json.Marshal([]jsonPatchOperation{patch})
    if err != nil {
        return denied(http.StatusInternalServerError, "encode JSON Patch: "+err.Error())
    }

    patchType := admissionv1.PatchTypeJSONPatch
    return admissionv1.AdmissionResponse{
        Allowed:   true,
        PatchType: &patchType,
        // Patch 保存原始 JSON 字节；外层 AdmissionReview 编码时会自动转换为 base64。
        Patch: patchBytes,
    }
}

kubectl create namespace demo
kubectl label namespace demo istio-injection=enabled --overwrite

kubectl run web \
  --namespace demo \
  --image nginx:1.27-alpine \
  --port 80

kubectl wait \
  --namespace demo \
  --for=condition=Ready pod/web \
  --timeout=120s

kubectl get pod web --namespace demo
kubectl get pod web \
  --namespace demo \
  -o jsonpath='{.spec.containers[*].name}{"\n"}'

资源对象校验¶

Mutating Admission 结束后，API Server 调用当前资源的 RESTCreateStrategy.Validate 校验修改后的对象。这些规则属于 Kubernetes API 对象本身的固定约束，由对应资源的服务端实现提供，不是 Admission Controller，也不由集群管理员配置。

对于 apps/v1 Deployment，deploymentStrategy.Validate 调用 ValidateDeployment。校验内容包括副本数不能为负数、selector 必须有效、Deployment strategy 取值合法，以及 Pod template 满足 Deployment 的约束。

spec.selector 与 spec.template.metadata.labels 的匹配检查位于 ValidatePodTemplateSpecForReplicaSet。两者不匹配时，API Server 返回 422 Invalid，Deployment 不会写入 etcd。kubectl 先把 YAML 转换为 API 请求，字段类型和未知字段由 API Server 在更早的解码阶段处理；资源对象校验检查解码后对象的字段取值及字段之间的关系。

ValidatingAdmissionPolicy¶

ValidatingAdmissionPolicy 让集群管理员用 CEL 校验提交给 Kubernetes API 的对象，例如要求对象包含指定标签、限制字段取值，或者检查多个字段之间的关系。校验在 API Server 进程内完成，不需要部署外部 Webhook。

Policy 定义匹配资源和 CEL 校验表达式，ValidatingAdmissionPolicyBinding 决定规则的生效范围与处理动作。Deny 拒绝请求，Warn 向客户端返回警告，Audit 为审计事件添加注解。

CEL 表达式可以读取 object、oldObject 和 request.userInfo 等请求信息。校验依赖镜像扫描结果或其他外部系统数据时，可以使用 Validating Webhook。

apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingAdmissionPolicy
metadata:
  name: deployment-replica-limit.example.com
spec:
  failurePolicy: Fail
  matchConstraints:
    resourceRules:
      # 创建和修改 Deployment 都需要重新校验副本数。
      - apiGroups: ["apps"]
        apiVersions: ["v1"]
        operations: ["CREATE", "UPDATE"]
        resources: ["deployments"]
  validations:
    # CEL 返回 false 时，Binding 中的 Deny 动作使 API Server 拒绝请求。
    - expression: object.spec.replicas <= 5
      message: Deployment replicas must not exceed 5
---
apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingAdmissionPolicyBinding
metadata:
  name: deployment-replica-limit.example.com
spec:
  # Policy 定义校验内容，Binding 决定生效范围和失败动作。
  policyName: deployment-replica-limit.example.com
  validationActions: [Deny]
  matchResources:
    # 只校验 default 命名空间中的 Deployment。
    namespaceSelector:
      matchLabels:
        kubernetes.io/metadata.name: default

kubectl apply \
  -f examples/chapter-01/02-02-admission/03-validating-admission-policy/policy.yaml
kubectl apply \
  --dry-run=server \
  -f examples/chapter-01/02-02-admission/03-validating-admission-policy/input-denied.yaml

Validating Webhook¶

ValidatingAdmissionWebhook 根据 ValidatingWebhookConfiguration 匹配请求，并行调用外部 HTTPS Webhook。Webhook 读取修改阶段生成的最终对象、userInfo 和请求信息，再返回允许或拒绝结果；对象修改由前面的 Mutating Admission 完成。

外部服务可以结合镜像仓库、漏洞扫描结果或其他系统状态执行校验。匹配规则、AdmissionReview 格式和 TLS 配置见 动态准入控制。

apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
metadata:
  name: pod-security.example.com
webhooks:
  - name: pod-security.example.com
    admissionReviewVersions: ["v1"]
    sideEffects: None
    failurePolicy: Fail
    matchPolicy: Equivalent
    timeoutSeconds: 5
    clientConfig:
      service:
        namespace: admission-demo
        name: admission-webhook
        path: /validate
        port: 443
      # API Server 使用这个 CA 校验 admission-webhook.admission-demo.svc 的证书。
      caBundle: "${CA_BUNDLE}"
    namespaceSelector:
      matchLabels:
        kubernetes.io/metadata.name: default
    rules:
      # Ephemeral Container 通过独立子资源更新，需要显式匹配 pods/ephemeralcontainers。
      - operations: ["CREATE", "UPDATE"]
        apiGroups: [""]
        apiVersions: ["v1"]
        resources: ["pods", "pods/ephemeralcontainers"]
        scope: Namespaced

package main

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

    admissionv1 "k8s.io/api/admission/v1"
    corev1 "k8s.io/api/core/v1"
)

func validatePod(request *admissionv1.AdmissionRequest) admissionv1.AdmissionResponse {
    var pod corev1.Pod
    if err := json.Unmarshal(request.Object.Raw, &pod); err != nil {
        return denied(http.StatusBadRequest, "decode Pod: "+err.Error())
    }

    for _, container := range pod.Spec.InitContainers {
        if isPrivileged(container.SecurityContext) {
            return denied(http.StatusForbidden, fmt.Sprintf("init container %q cannot be privileged", container.Name))
        }
    }
    for _, container := range pod.Spec.Containers {
        if isPrivileged(container.SecurityContext) {
            return denied(http.StatusForbidden, fmt.Sprintf("container %q cannot be privileged", container.Name))
        }
    }
    // pods/ephemeralcontainers 是独立子资源，WebhookConfiguration 需要显式匹配它。
    for _, container := range pod.Spec.EphemeralContainers {
        if isPrivileged(container.SecurityContext) {
            return denied(http.StatusForbidden, fmt.Sprintf("ephemeral container %q cannot be privileged", container.Name))
        }
    }

    return allowed()
}

func isPrivileged(context *corev1.SecurityContext) bool {
    // 未设置 privileged 与显式设置 false 都符合这条示例策略。
    return context != nil && context.Privileged != nil && *context.Privileged
}

apiVersion: policies.kyverno.io/v1
kind: ValidatingPolicy
metadata:
  name: disallow-privileged-containers
spec:
  validationActions:
    - Deny
  matchConstraints:
    resourceRules:
      - apiGroups: [""]
        apiVersions: ["v1"]
        operations: ["CREATE", "UPDATE"]
        resources: ["pods", "pods/ephemeralcontainers"]
  variables:
    - name: allContainers
      expression: >-
        object.spec.containers +
        object.spec.?initContainers.orValue([]) +
        object.spec.?ephemeralContainers.orValue([])
  validations:
    - expression: >-
        variables.allContainers.all(
          c,
          c.?securityContext.?privileged.orValue(false) == false
        )
      message: Privileged containers are not allowed in Pods

内置 Admission Controller¶

内置 Admission Controller 编译在 kube-apiserver 中。API Server 通过 --enable-admission-plugins 和 --disable-admission-plugins 管理这些插件。

常见插件包括：

• LimitRanger：根据命名空间中的 LimitRange 补充默认资源请求，并校验资源上下限。
• ResourceQuota：检查本次写入是否超过命名空间的资源配额。
• PodSecurity：按照命名空间配置的 Pod Security Standards 执行 enforce、audit 和 warn。
• ServiceAccount：Pod 未指定 serviceAccountName 时填入 default，并校验引用的 ServiceAccount。
• RuntimeClass：校验 Pod 引用的 RuntimeClass，并应用对应的 Pod 开销与调度约束。
• NodeRestriction：限制 Kubelet 可以修改的 Node 和 Pod 对象范围。

各插件的默认启用状态、执行阶段和配置参数记录在 Admission Controller 参考文档。

规则来源与处理方式¶

Deployment 自身的固定约束与集群策略使用不同的处理机制：

API 版本转换¶

apiVersion 指定客户端请求和响应采用的资源结构；storage version 指定 API Server 写入 etcd 的资源结构。两者不同时，API Server 在读写过程中完成版本转换。同一资源可以同时提供多个对外版本，而 etcd 中的新写入统一使用当前 storage version。

API Server 从不同位置获得内置资源和 Custom Resource 的类型定义，因此两类资源使用不同的转换实现：

• Kubernetes 内置资源：Deployment、Pod 等资源的外部 Go 类型、内部 Go 类型和转换函数都随 Kubernetes 源码编译进 kube-apiserver。例如，客户端提交的 Deployment 对应 apps/v1.Deployment，API Server 内部使用 apps/__internal.Deployment。这些类型和转换函数注册在 runtime.Scheme 中；API Server 通过这份注册表完成请求版本、内部类型和 storage version 之间的转换。整个过程在 API Server 进程内完成，相关概念见 Storage Versions。

• CRD 提供的 Custom Resource：标准 CRD 不能把资源专用的 Go 类型和转换函数注册到 kube-apiserver 的 runtime.Scheme。API Server 使用 unstructured.Unstructured 保存解码后的字段，也就是以通用的键值结构表示对象；CRD schema 仍然负责字段默认值、裁剪和校验。spec.conversion.strategy 只支持 None 和 Webhook：None 在 API Server 进程内执行，但只修改 apiVersion，不属于 typed conversion；Webhook 通过 ConversionReview 调用外部 HTTPS 服务。Kubebuilder 生成的 Go 类型和 Hub/Spoke 转换方法运行在 Webhook 进程中，不会被动态加载到 kube-apiserver。具体行为见 Versions in CustomResourceDefinitions。

如果自定义 API 必须在提供该 API 的进程内完成 typed conversion，可以实现 Extension API Server，并通过 API Aggregation Layer 接入 Kubernetes。外部版本、内部类型和转换函数会注册到 Extension API Server 自己的 runtime.Scheme；这种资源由 Aggregated API 提供，不再是 CRD。

版本转换解决的问题¶

API 发布后仍会继续演进，常见变化包括字段改名、字段拆分、嵌套结构调整和默认值变化。已经部署的客户端可能继续提交旧版本，etcd 中也可能保留由旧 storage version 写入的对象。

以 ModelServer 为例，v1beta1 和 v1 表达相同的模型、服务副本和端口，但字段结构不同：

客户端通过 v1beta1 创建对象时，API Server 调用 Conversion Webhook，把对象转换成当前 storage version v1 后写入 etcd。客户端再次通过 v1beta1 读取时，API Server 从 etcd 取得 v1 对象，再调用 Webhook 转换为 v1beta1 响应。

CRD 版本字段¶

CRD 在 spec.versions 中分别控制 REST endpoint 和 etcd 写入格式：

• served：true 时，API Server 为该版本提供 REST endpoint，并把它发布到 API discovery。
• storage：指定 Custom Resource 写入 etcd 时使用的版本。一个 CRD 必须且只能有一个 storage: true 的版本。
• status.storedVersions：记录 etcd 中可能仍然存在的 storage version。完成数据迁移后才能从这里和 spec.versions 中移除旧版本。

同一个版本可以同时设置 served: false 和 storage: false。API Server 不会为它安装 REST handler，也不会用它写入 etcd；CRD 仍需保留该版本的 structural schema。

转换机制¶

内置资源的 typed conversion¶

Deployment 的外部版本是 apps/v1.Deployment，API Server 使用的内部类型是 apps/__internal.Deployment。请求按 apps/v1 解码并应用该版本的默认值，再通过 runtime.Scheme 转换成内部类型。Storage Codec 写入 etcd 前把内部对象转换成 storage version；读取时先恢复内部类型，再按客户端访问的 served version 编码响应。

flowchart LR
    W["apps/v1 wire object"] --> D["Decode + apps/v1 defaults"]
    D --> I["apps/__internal Deployment"]
    I --> R["Registry / REST Strategy"]
    R --> S["Storage Codec"]
    S --> E["etcd storage version"]
    E --> S2["Storage Codec"]
    S2 --> I2["apps/__internal Deployment"]
    I2 --> O["requested served version"]

相关代码按职责分布在以下目录：

内置资源的 served version 与 API Server 能解码的历史版本不完全相同。旧 endpoint 被移除后，请求无法再访问该版本；API Server 仍可保留相应类型和转换函数，用于读取升级前写入的历史数据。

CRD 的 None 策略¶

None 是 CRD 的默认转换策略。API Server 保留对象字段，只把返回对象的 apiVersion 改成目标版本。这个方式不处理字段改名或结构变化，适用于各版本 schema 相同的 CRD。

spec:
  conversion:
    strategy: None

版本之间存在字段差异时，None 可能让目标版本得到缺失字段，或者让 unknown-field pruning 删除无法识别的字段。此类 API 需要 Conversion Webhook。

CRD 的 Webhook 策略¶

Webhook 策略通过 CRD 的 spec.conversion 指向 HTTPS 服务。API Server 使用 ConversionReview 传递转换请求：

• request.objects 保存待转换的源对象。
• request.desiredAPIVersion 指定目标版本。
• 响应按输入顺序返回相同数量的对象，并保留 name、namespace 和 UID。

{
  "apiVersion": "apiextensions.k8s.io/v1",
  "kind": "ConversionReview",
  "request": {
    "uid": "2b9f5bb9-6fc5-4b3f-a730-4e9d39b0f0a4",
    "desiredAPIVersion": "ai.course.example.com/v1",
    "objects": [
      {
        "apiVersion": "ai.course.example.com/v1beta1",
        "kind": "ModelServer",
        "metadata": {"name": "qwen-demo", "namespace": "default"},
        "spec": {
          "modelRef": "Qwen/Qwen3-0.6B",
          "scale": {"replicas": 1},
          "http": {"port": 8000}
        }
      }
    ]
  }
}

Conversion Webhook 只负责不同 API 版本之间的等价转换。字段合法性由各版本的 OpenAPI schema 和 Admission 规则处理；转换失败不应被用作准入策略。

Conversion Webhook 的 Hub 设计¶

CRD 需要转换字段结构时，三种方案都配置 conversion.strategy: Webhook，API Server 按相同协议调用外部 Webhook。下表比较的是 Webhook 内部的三种 Hub/Spoke 组织方案，并不是三种并列的 CRD 转换机制。

三种方案在 CRD 中都启用同一种转换策略：

spec:
  conversion:
    strategy: Webhook

下图中的双向箭头表示 Webhook Server 内部维护的转换函数。API Server 只提交源对象和目标 apiVersion，不参与 Hub/Spoke 转换。

固定的非公开 CRD 版本¶

固定 Hub 保留在 CRD 的 spec.versions 中，通过 served: false 关闭 REST endpoint，通过 storage: false 排除 etcd 写入。对外版本和 storage version 可以继续演进，每个新版本只需增加与固定 Hub 之间的双向转换。

flowchart LR
    B["v1beta1<br/>served=true"] <--> H["v1alpha1 Hub<br/>declared in CRD<br/>served=false<br/>storage=false"]
    V["v1<br/>served=true<br/>storage=true"] <--> H

最新公开版本¶

最新公开版本同时作为 Hub，通常也作为 storage version。发布 v2 后，Hub 从 v1 切换到 v2，原来的 v1 变成 Spoke，Webhook 需要补充旧版本与新 Hub 之间的转换。如果同时把 storage version 切换到 v2，还要另行迁移以旧版本保存的存量对象。

flowchart LR
    subgraph R1["发布 v2 之前"]
        B1["v1beta1 Spoke"] <--> H1["v1 Hub<br/>served=true<br/>storage=true"]
    end
    subgraph R2["发布 v2 之后"]
        B2["v1beta1 Spoke"] <--> H2["v2 Hub<br/>served=true<br/>storage=true"]
        V1["v1 Spoke"] <--> H2
    end
    H1 -. "Hub 随最新版本切换" .-> H2

Webhook 内部类型¶

内部 Hub 只存在于 Webhook Server 的 Go 代码中，不列入 CRD 的 spec.versions。Webhook 把源版本转换成内部类型，再由内部类型转换成目标版本；对外版本和 storage version 的变化不会改变 Hub 的 API 可见性。

flowchart LR
    subgraph C["CRD spec.versions"]
        B["v1beta1<br/>served=true"]
        V["v1<br/>served=true<br/>storage=true"]
    end
    subgraph W["Conversion Webhook process"]
        H["internal.ModelServer Hub<br/>not declared in CRD"]
    end
    B <--> H
    V <--> H

Kubebuilder Multi-Version API 介绍了 controller-runtime 的 Hub/Spoke 接口；Kubernetes 多版本 API 转换最佳实践 对三种 Hub 结构给出了进一步比较。

Webhook conversion 的实现¶

本仓库的 Kubebuilder 示例采用固定的非公开 CRD 版本作为 Hub。v1alpha1 保留在 CRD 中，但不提供 REST endpoint，也不作为 storage version；v1beta1 和 v1 分别实现与该 Hub 之间的双向转换。

flowchart LR
    S["Source<br/>v1beta1.ModelServer"] --> C1["v1beta1.ConvertTo()"]
    C1 --> H["v1alpha1.ModelServer<br/>conversion.Hub"]
    H --> C2["v1.ConvertFrom()"]
    C2 --> T["Target<br/>v1.ModelServer"]

v1alpha1 在 controller-runtime 中实现 conversion.Hub。API Server 发送的 ConversionReview 只包含源对象和目标 apiVersion，不会请求 v1alpha1 endpoint。controller-runtime 根据源对象和目标版本构造两个 Spoke，在 Webhook 进程内依次调用源版本的 ConvertTo() 和目标版本的 ConvertFrom()。反向转换使用相同的 Hub 和相反的 Spoke 顺序。

实现位于 examples/chapter-01/02-03-crd-conversion。项目使用 Kubebuilder v4.15.0、controller-runtime v0.24.1 和 controller-tools v0.21.0。

以下命令为 v1alpha1 生成 Hub，为两个公开版本生成 Spoke 方法和 /convert Webhook 配置：

kubebuilder create webhook \
  --group ai \
  --version v1alpha1 \
  --kind ModelServer \
  --conversion \
  --spoke v1beta1,v1

Kubebuilder v4.15.0 会给 Hub 自动添加 +kubebuilder:storageversion。本例删除该 marker，给 v1alpha1 添加 +kubebuilder:unservedversion：

// +kubebuilder:object:root=true
// +kubebuilder:unservedversion
// +kubebuilder:subresource:status

// ModelServer 是转换专用 Hub，不提供 REST API，也不作为 storage version。
type ModelServer struct {
    metav1.TypeMeta   `json:",inline"`
    metav1.ObjectMeta `json:"metadata,omitempty"`
    Spec              ModelServerSpec   `json:"spec"`
    Status            ModelServerStatus `json:"status,omitempty"`
}

v1 根类型使用 +kubebuilder:storageversion，生成 CRD 时成为唯一 storage version：

// +kubebuilder:object:root=true
// +kubebuilder:storageversion
// +kubebuilder:subresource:status

// ModelServer 是 v1 API 的根类型，也是当前 storage version。
type ModelServer struct {
    metav1.TypeMeta   `json:",inline"`
    metav1.ObjectMeta `json:"metadata,omitempty"`
    Spec              ModelServerSpec   `json:"spec"`
    Status            ModelServerStatus `json:"status,omitempty"`
}

v1alpha1 通过空的 Hub() 方法实现 conversion.Hub。v1beta1 和 v1 实现 conversion.Convertible：

package v1alpha1

import "sigs.k8s.io/controller-runtime/pkg/conversion"

var _ conversion.Hub = &ModelServer{}

// Hub 将 v1alpha1 标记为 ModelServer 的唯一转换中心。
func (*ModelServer) Hub() {}

v1beta1 的转换函数展示了两个方向的字段映射。类型断言失败时返回明确错误，ObjectMeta 使用 DeepCopy，避免转换结果与源对象共享 map 或 slice：

package v1beta1

import (
    "fmt"

    "sigs.k8s.io/controller-runtime/pkg/conversion"

    v1alpha1 "github.com/cr7258/course/examples/chapter-01/02-03-crd-conversion/api/v1alpha1"
)

var _ conversion.Convertible = &ModelServer{}

// ConvertTo 把 v1beta1 的分组字段写入 Hub 的规范化表示。
func (src *ModelServer) ConvertTo(dstRaw conversion.Hub) error {
    dst, ok := dstRaw.(*v1alpha1.ModelServer)
    if !ok {
        return fmt.Errorf("expected *v1alpha1.ModelServer, got %T", dstRaw)
    }

    dst.ObjectMeta = *src.ObjectMeta.DeepCopy()
    dst.Spec.ModelID = src.Spec.ModelRef
    dst.Spec.ReplicaCount = src.Spec.Scale.Replicas
    dst.Spec.HTTPPort = src.Spec.HTTP.Port
    dst.Status.Phase = src.Status.Phase
    return nil
}

// ConvertFrom 把 Hub 的规范化字段恢复成 v1beta1 的分组字段。
func (dst *ModelServer) ConvertFrom(srcRaw conversion.Hub) error {
    src, ok := srcRaw.(*v1alpha1.ModelServer)
    if !ok {
        return fmt.Errorf("expected *v1alpha1.ModelServer, got %T", srcRaw)
    }

    dst.ObjectMeta = *src.ObjectMeta.DeepCopy()
    dst.Spec.ModelRef = src.Spec.ModelID
    dst.Spec.Scale.Replicas = src.Spec.ReplicaCount
    dst.Spec.HTTP.Port = src.Spec.HTTPPort
    dst.Status.Phase = src.Status.Phase
    return nil
}

manager 将三个版本注册到同一个 Scheme。Hub 即使不提供 REST endpoint，也必须注册，否则 controller-runtime 无法构造 Hub 对象：

utilruntime.Must(aiv1alpha1.AddToScheme(scheme))
utilruntime.Must(aiv1beta1.AddToScheme(scheme))
utilruntime.Must(aiv1.AddToScheme(scheme))

Webhook manager 为 ModelServer 注册 controller-runtime 的 conversion handler：

package v1alpha1

import (
    ctrl "sigs.k8s.io/controller-runtime"

    aiv1alpha1 "github.com/cr7258/course/examples/chapter-01/02-03-crd-conversion/api/v1alpha1"
)

// SetupModelServerWebhookWithManager 为 ModelServer 注册 conversion handler。
func SetupModelServerWebhookWithManager(mgr ctrl.Manager) error {
    return ctrl.NewWebhookManagedBy(mgr, &aiv1alpha1.ModelServer{}).
        Complete()
}

CRD 的 conversion 配置指向 Webhook Service 的 /convert。Conversion Webhook 使用 CRD 字段，不创建 MutatingWebhookConfiguration 或 ValidatingWebhookConfiguration：

# The following patch enables a conversion webhook for the CRD
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: modelservers.ai.course.example.com
spec:
  conversion:
    strategy: Webhook
    webhook:
      clientConfig:
        service:
          namespace: system
          name: webhook-service
          path: /convert
      conversionReviewVersions:
      - v1

下图展示了客户端通过 v1beta1 更新对象、API Server 以 v1 写入 etcd，再把响应转换回 v1beta1 的过程：

sequenceDiagram
    participant C as Client
    participant A as API Server
    participant W as Conversion Webhook
    participant E as etcd

    C->>A: PUT ai.course.example.com/v1beta1
    A->>W: ConversionReview(objects=v1beta1, desiredAPIVersion=v1)
    Note over W: v1beta1.ConvertTo(v1alpha1 Hub)
    Note over W: v1.ConvertFrom(v1alpha1 Hub)
    W-->>A: convertedObjects=v1
    A->>E: store ai.course.example.com/v1
    E-->>A: stored v1 object + revision
    A->>W: ConversionReview(objects=v1, desiredAPIVersion=v1beta1)
    Note over W: v1.ConvertTo(v1alpha1 Hub)
    Note over W: v1beta1.ConvertFrom(v1alpha1 Hub)
    W-->>A: convertedObjects=v1beta1
    A-->>C: v1beta1 response

读取方向使用相同协议。客户端访问 v1beta1 endpoint 时，API Server 从 etcd 读取 v1，再请求 Webhook 转换为 v1beta1。LIST 请求可以在一份 ConversionReview 中携带多个对象，Webhook 必须保持输入顺序和对象数量。

Conversion Webhook 位于 Custom Resource 的读写路径。服务不可用、证书失效或返回对象不符合协议时，需要转换的读取和写入都会失败。生产部署需要覆盖以下运行条件：

• Webhook 使用多个可用副本。
• 服务端证书能够自动轮换。
• 转换延迟和超时受到监控。
• 协议错误和调用失败触发告警。

仓库中的 verify-kind.sh 创建独立的 crd-conversion-demo Kind 集群，生成临时 TLS 证书并部署 Webhook。脚本检查以下结果：

• v1alpha1 不出现在 API discovery，v1beta1 和 v1 都有 REST endpoint。
• 对象通过 v1beta1 创建后，可以通过 v1 读取。
• 对象通过 v1 更新后，v1beta1 和 v1 返回相同副本数。
• control-plane 中的 etcd 原始值使用 ai.course.example.com/v1。
• CRD 的 status.storedVersions 只有 v1。

cd examples/chapter-01/02-03-crd-conversion
./verify-kind.sh

Kubernetes v1.36.1 的实测结果如下。输入对象、完整输出、依赖版本和清理命令记录在 CRD 多版本转换示例。

v1alpha1 REST endpoint: not served
Created with v1beta1: modelRef=Qwen/Qwen3-0.6B scale.replicas=1 http.port=8000
Read with v1: model.name=Qwen/Qwen3-0.6B replicas=1 server.port=8000
Updated with v1: replicas=3
Read after update: v1beta1.scale.replicas=3 v1.replicas=3
etcd apiVersion: ai.course.example.com/v1
CRD status.storedVersions: v1
Conversion webhook verification passed.

Storage version 迁移¶

把 storage: true 从 v1beta1 切换到 v1，只影响之后的写入。etcd 中已有对象仍保持 v1beta1 编码，CRD 的 status.storedVersions 会继续记录曾经用作存储的版本。

切换 storage version 后不必立即重写旧对象。只要 CRD 仍保留旧版本，并且 Conversion Webhook 支持新旧版本之间的转换，API Server 就能读取旧对象，并按客户端请求的版本返回。此时旧对象仍依赖旧版本 schema 和对应的转换代码，版本迁移还没有完成。

从 CRD 的 spec.versions 删除旧版本，或者从 Webhook 删除旧版本的转换代码之前，必须先把已有对象重写为当前 storage version。Kubernetes v1.36 提供 Beta 的 StorageVersionMigration API，默认关闭。启用时，需要在 kube-apiserver 和 kube-controller-manager 打开 StorageVersionMigrator feature gate，并在 kube-apiserver 启用 storagemigration.k8s.io/v1beta1 API。

无法启用该功能时，可以按照 CustomResourceDefinition 的版本 中的手动迁移流程，列出并重新写入全部现有对象，使 API Server 按当前 storage version 保存。确认迁移完成后，再更新 status.storedVersions。

仅切换 storage version 不会让 status.storedVersions 自动删除旧条目。对象重写完成后检查该字段；如果迁移工具没有更新它，再显式保留当前版本：

kubectl patch crd modelservers.ai.course.example.com \
  --subresource=status \
  --type=merge \
  -p '{"status":{"storedVersions":["v1"]}}'

存储迁移与客户端迁移是两项独立工作。仍有客户端访问旧 API 时，可以继续保留该 served version；所有客户端完成迁移后，再把旧版本设为 served: false。旧版本既不再 served，也不再出现在 status.storedVersions 后，才可以从 CRD schema 和 Webhook 转换代码中删除。

对象版本¶

以下命令读取 vllm-demo Deployment 的对象标识和版本字段：

kubectl get --raw \
  '/apis/apps/v1/namespaces/default/deployments/vllm-demo' \
  | jq '{
      name: .metadata.name,
      uid: .metadata.uid,
      resourceVersion: .metadata.resourceVersion,
      generation: .metadata.generation
    }'

metadata.uid 标识一个对象实例；同名对象删除重建后会得到新的 UID。resourceVersion 的顺序、读取路径与续接方式见 etcd Watch 机制。对于 Deployment，PrepareForUpdate 在 spec 或 metadata.annotations 变化时递增 generation。

核心源码¶

API Server 在启动时组装服务、注册资源路由，并创建准入插件与存储对象。请求到达后，HTTP 过滤器补充请求信息并执行认证、流控和授权；资源 Handler 负责解码与准入，Registry 组织资源校验和读写，Storage 实现最终的数据访问。

以下调用关系以 Kubernetes v1.36.4 源码为依据，写入路径使用内置的 apps/v1 Deployment。源码片段保留关键字段和调用，使用 ... 省略与当前机制无关的分支。

• 服务组成与启动：CreateServerChain 组装 APIExtensionsServer、KubeAPIServer 和 APIAggregator，PrepareRun 与 Run 完成服务准备和监听。
• API 注册与请求路由：资源提供者创建 REST Storage，InstallREST 根据它实现的接口安装 GET、LIST、CREATE、UPDATE 等操作对应的 HTTP Handler。
• HTTP 过滤器链：DefaultBuildHandlerChain 将请求信息、认证、审计、流控和授权包装在路由外层，请求通过这些过滤器后进入资源 Handler。
• 对象解码与创建：createHandler 把请求体解码为内部对象，执行 Mutating Admission，并把对象和校验回调交给资源的 Create 方法。
• 准入插件管理与调用：Plugins 保存插件工厂，NewFromPlugins 创建有序插件链；创建请求在 Handler 中调用 Admit，在 Registry 中通过回调调用 Validate。
• REST Strategy 与通用 Registry：Deployment Strategy 提供资源规则，Store 复用通用创建、更新和读取流程，并连接底层 Storage。
• 对象持久化与响应：Storage 对对象编码并执行 etcd 写入，再把保存结果交回 Handler；服务端 dry-run 执行准入与校验后返回对象。
• 更新、补丁与并发控制：PUT 与 PATCH 汇入 Store.Update，通过 GuaranteedUpdate 处理当前对象、更新回调和条件写入。
• 读取、监听与 Watch Cache：CacheDelegator 根据请求语义选择缓存或底层存储，Cacher 提供缓存读取与事件流，后台 LIST/WATCH 持续更新缓存。

服务组成与启动¶

kube-apiserver 在同一进程内组合 CRD、内置资源和聚合 API 三套服务，通过委派链把请求交给对应的处理器。服务构建完成后，进程准备 OpenAPI 与健康检查，再启动 HTTPS 监听和启动后钩子。

服务构建与委派

CreateServerChain 按依赖顺序创建三个服务，每次把已经创建的服务作为下一层的委派目标：

• APIExtensionsServer：安装 CRD API，并为自定义资源提供处理入口；委派链末端连接未找到资源的处理器。
• KubeAPIServer：安装 Pod、Deployment 等内置资源 API；将 APIExtensionsServer 作为委派目标。
• APIAggregator：管理 APIService 并接入扩展 API 服务；将 KubeAPIServer 作为委派目标，最终返回给进程入口。

构建顺序是 APIExtensionsServer → KubeAPIServer → APIAggregator。请求从最外层 APIAggregator 进入，本层未接管的路径沿相反方向委派；命中内置资源的处理器后，执行对应的 REST 操作。聚合 API 的代理路径由 APIService 配置决定。

三个构造调用分别接收下一层 Handler，并返回当前层服务对象：

func CreateServerChain(config CompletedConfig) (*aggregatorapiserver.APIAggregator, error) {
    notFoundHandler := notfoundhandler.New(
        config.KubeAPIs.ControlPlane.Generic.Serializer,
        genericapifilters.NoMuxAndDiscoveryIncompleteKey,
    )
    // 先创建委派链最内层的 CRD 服务。
    apiExtensionsServer, err := config.ApiExtensions.New(
        genericapiserver.NewEmptyDelegateWithCustomHandler(notFoundHandler),
    )
    ...
    crdAPIEnabled := config.ApiExtensions.GenericConfig.MergedResourceConfig.ResourceEnabled(
        apiextensionsv1.SchemeGroupVersion.WithResource("customresourcedefinitions"),
    )

    // 内置资源服务把未接管的路径委派给 CRD 服务。
    kubeAPIServer, err := config.KubeAPIs.New(apiExtensionsServer.GenericAPIServer)
    ...

    // 聚合服务位于最外层，接收进程的请求入口。
    aggregatorServer, err := controlplaneapiserver.CreateAggregatorServer(
        config.Aggregator,
        kubeAPIServer.ControlPlane.GenericAPIServer,
        apiExtensionsServer.Informers.Apiextensions().V1().CustomResourceDefinitions(),
        crdAPIEnabled,
        apiVersionPriorities,
    )
    ...
    return aggregatorServer, nil
}

三个服务通过进程内 Handler 连接。通用服务的构造代码 将下一层的 UnprotectedHandler() 传给 NewAPIServerHandler，后者把它设置为路由未匹配时的处理入口。委派使用下一层的路由 Handler，已执行的外层过滤器链无需再次运行。

监听与启动后钩子

Run 读取选项、完成配置并创建委派链，再调用返回对象的 PrepareRun 和 Run：

func Run(ctx context.Context, opts options.CompletedOptions) error {
    ...
    config, err := NewConfig(opts)
    ...
    completed, err := config.Complete()
    ...
    server, err := CreateServerChain(completed)
    ...

    // API 安装完成后，准备服务运行所需的路由和检查。
    prepared, err := server.PrepareRun()
    ...

    // 运行返回的最外层聚合服务。
    return prepared.Run(ctx)
}

• PrepareRun：聚合服务调用通用服务的 PrepareRun。通用实现先递归准备委派目标，再安装 OpenAPI、healthz、livez 和 readyz；聚合服务随后准备聚合 OpenAPI。
• RunWithContext：preparedAPIAggregator.Run 将调用交给通用服务，后者组织运行及关闭阶段，并调用 NonBlockingRunWithContext 启动监听。
• NonBlockingRunWithContext：先通过 SecureServingInfo.Serve 启动 HTTPS 服务，再调用 RunPostStartHooks，为每个钩子启动独立 goroutine，启动 Informer、控制器等后台任务。

启动后钩子与 HTTP 服务并发运行；是否可以接收正常流量，由就绪检查反映。监听端口已启动与全部初始化任务完成是两个不同的状态。

API 注册与请求路由¶

内置资源在启动时把 REST Storage 注册到 API 组，再由安装器根据 Storage 实现的 Go 接口创建 HTTP 路由。以 Deployment 为例，POST /apis/apps/v1/namespaces/default/deployments 最终匹配创建路由，并调用持有 Deployment Storage 的处理函数。

资源与 Storage 映射

StorageProvider.NewRESTStorage 创建 apps API 组信息，调用 v1Storage 收集资源，再把返回值写入 APIGroupInfo.VersionedResourcesStorageMap["v1"]。这个字段的类型是 map[string]map[string]rest.Storage，两层键分别为 API 版本和资源路径。

deployments、deployments/status 和 deployments/scale 是三个独立的映射项，分别连接主资源、状态子资源和扩缩容子资源的 REST 实现。deploymentstore.NewStorage 在内部调用 NewREST，再组装这些实现；请求路由安装器接收的是这组资源处理接口。

v1Storage 在 Deployment API 启用时创建这些 Storage，并按资源路径写入映射：

func (p StorageProvider) v1Storage(
    apiResourceConfigSource serverstorage.APIResourceConfigSource,
    restOptionsGetter generic.RESTOptionsGetter,
) (map[string]rest.Storage, error) {
    storage := map[string]rest.Storage{}

    if resource := "deployments"; apiResourceConfigSource.ResourceEnabled(
        appsapiv1.SchemeGroupVersion.WithResource(resource),
    ) {
        deploymentStorage, err := deploymentstore.NewStorage(restOptionsGetter)
        if err != nil {
            return storage, err
        }
        // 为主资源和子资源分别提供 REST 实现。
        storage[resource] = deploymentStorage.Deployment
        storage[resource+"/status"] = deploymentStorage.Status
        storage[resource+"/scale"] = deploymentStorage.Scale
    }
    ...
    return storage, nil
}

InstallAPIs 收集各资源提供者返回的 APIGroupInfo，将具名 API 组交给 InstallAPIGroups。随后按以下层次完成安装：

• InstallAPIGroups：检查 API 组与版本信息，准备 OpenAPI 类型信息，再调用 installAPIResources。
• installAPIResources：遍历组内启用的版本，创建对应的 APIGroupVersion，将资源映射、编解码器等配置交给版本级安装器。
• APIGroupVersion.InstallREST：组合 /apis/apps/v1 前缀，创建 APIInstaller，安装资源路由和版本发现接口，再把 WebService 加入 GoRestfulContainer。
• APIInstaller.Install：按排序后的资源路径遍历 Storage，逐项调用 registerResourceHandlers。

接口能力与处理函数

registerResourceHandlers 读取资源作用域、类型和 Storage 的接口能力，再决定可以安装哪些操作。例如，rest.Creater 提供创建能力，rest.Getter 提供单对象读取能力，rest.Lister 提供列表读取能力；安装器据此生成 POST、GET 等路由。

对于 Deployment 的创建操作，安装器为 POST 选择 restfulCreateResource，再通过 ws.POST(action.Path).To(handler) 将处理函数绑定到资源路径。RequestScope 随处理函数一起传入，保存资源身份、对象类型、编解码器、名称与命名空间解析方式和字段管理等请求处理上下文。

安装器通过接口类型断言取得创建能力，再将它绑定到 POST 路由的闭包中：

func (a *APIInstaller) registerResourceHandlers(
    path string, storage rest.Storage, ws *restful.WebService,
) (*metav1.APIResource, *storageversion.ResourceInfo, error) {
    ...
    // 资源实现的接口决定可以安装哪些操作。
    creater, isCreater := storage.(rest.Creater)
    namedCreater, isNamedCreater := storage.(rest.NamedCreater)
    lister, isLister := storage.(rest.Lister)
    getter, isGetter := storage.(rest.Getter)
    ...
    for _, action := range actions {
        ...
        switch action.Verb {
        ...
        case request.MethodPost:
            var handler restful.RouteFunction
            if isNamedCreater {
                handler = restfulCreateNamedResource(namedCreater, reqScope, admit)
            } else {
                handler = restfulCreateResource(creater, reqScope, admit)
            }
            ...
        }
    }
    ...
}

func restfulCreateResource(
    r rest.Creater, scope handlers.RequestScope, admit admission.Interface,
) restful.RouteFunction {
    return func(req *restful.Request, res *restful.Response) {
        // 请求命中路由后，进入通用创建 Handler。
        handlers.CreateResource(r, &scope, admit)(res.ResponseWriter, req.Request)
    }
}

注册阶段建立“路径、HTTP 方法、REST 实现”的对应关系；请求到达时，闭包把原始 HTTP 请求、响应写入器和预先保存的 Storage 交给 handlers.CreateResource。对象解码、准入和持久化由后续创建路径完成。

HTTP 过滤器链¶

请求进入资源 Handler 前，先经过一组嵌套的 http.Handler。这些过滤器解析请求身份、补充 Context、执行访问检查或排队，并在条件满足时调用下一层。DefaultBuildHandlerChain 从资源路由向外包装 Handler，因此源码中的包装顺序与请求进入顺序相反。

包装顺序与请求顺序

DefaultBuildHandlerChain 先用 WithAuthorization 包装 apiHandler，再向外加入 APF、用户模拟、审计和认证等过滤器。例如先构造 Authorization(apiHandler)，再构造 Authentication(Authorization(apiHandler)) 时，请求会先执行 Authentication。

图中保留的主要执行顺序为：WithAuditInit → WithRequestInfo → WithAuthentication → WithAudit → WithConstrainedImpersonation → WithPriorityAndFairness → WithAuthorization → apiHandler。其中 APF 排队发生在操作授权检查之前；日志、超时、Tracing 等过滤器穿插在完整链中。

APF 已配置、受约束用户模拟开启时，主要包装调用如下。ConstrainedImpersonation 在所述版本中默认开启，其他分支及辅助过滤器用 ... 省略。

func DefaultBuildHandlerChain(apiHandler http.Handler, c *Config) http.Handler {
    handler := apiHandler
    ...
    // 先包装靠近资源路由的授权层。
    handler = genericapifilters.WithAuthorization(handler, c.Authorization.Authorizer, c.Serializer)
    ...
    if c.FlowControl != nil {
        workEstimatorCfg := flowcontrolrequest.DefaultWorkEstimatorConfig()
        requestWorkEstimator := flowcontrolrequest.NewWorkEstimator(
            c.StorageObjectCountTracker.Get, c.FlowControl.GetInterestedWatchCount,
            workEstimatorCfg, c.FlowControl.GetMaxSeats,
        )
        ...
        handler = genericfilters.WithPriorityAndFairness(
            handler, c.LongRunningFunc, c.FlowControl,
            requestWorkEstimator, c.RequestTimeout/4,
        )
        ...
    }
    ...
    if c.FeatureGate.Enabled(genericfeatures.ConstrainedImpersonation) {
        handler = impersonation.WithConstrainedImpersonation(
            handler, c.Authorization.Authorizer, c.Serializer,
        )
        ...
    }
    ...
    handler = genericapifilters.WithAudit(
        handler, c.AuditBackend, c.AuditPolicyRuleEvaluator, c.LongRunningFunc,
    )
    ...
    failedHandler := genericapifilters.Unauthorized(c.Serializer)
    failedHandler = genericapifilters.WithFailedAuthenticationAudit(
        failedHandler, c.AuditBackend, c.AuditPolicyRuleEvaluator,
    )
    ...
    handler = genericapifilters.WithAuthentication(
        handler, c.Authentication.Authenticator, failedHandler,
        c.Authentication.APIAudiences, c.Authentication.RequestHeaderConfig,
    )
    ...
    // 后包装的层先收到请求，为内层提供请求信息与审计上下文。
    handler = genericapifilters.WithRequestInfo(handler, c.RequestInfoResolver)
    ...
    handler = genericapifilters.WithAuditInit(handler)
    return handler
}

Context 与短路返回

过滤器通过请求 Context 传递已经解析的数据。WithRequestInfo 调用 NewRequestInfo，将 URL 和 HTTP 方法转换为结构化的资源操作。例如，向 /apis/apps/v1/namespaces/default/deployments 发送 POST，会得到 API 组 apps、版本 v1、命名空间 default、资源 deployments 和逻辑操作 create。

过滤器把 RequestInfo 写入新 Context，再调用内层 Handler：

func WithRequestInfo(handler http.Handler, resolver request.RequestInfoResolver) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {
        ctx := req.Context()
        info, err := resolver.NewRequestInfo(req)
        ...

        // 使用携带 RequestInfo 的新 Context 继续执行内层 Handler。
        req = req.WithContext(request.WithRequestInfo(ctx, info))
        handler.ServeHTTP(w, req)
    })
}

认证成功后，WithAuthentication 把用户信息写入同一个请求的 Context。后续用户模拟、APF 和授权过滤器据此读取请求者及资源操作；授权通过后才继续进入 apiHandler。

发生拒绝时，过滤器直接写入响应并返回。认证链未返回有效身份时调用 failedHandler，由 Unauthorized 生成 401 Unauthorized 响应；包装它的 WithFailedAuthenticationAudit 按审计配置记录这条失败路径。操作授权明确拒绝时返回 403 Forbidden。这些分支都在资源 Handler 执行之前结束请求。

对象解码与创建¶

创建 Handler 把 HTTP 请求体转换成资源的内部对象，执行 Mutating Admission，再把对象和校验回调交给 REST Storage。以 Deployment 为例，客户端提交 apps/v1 对象，Handler 和 Registry 通过 runtime.Object 接口传递内存中的 *apps.Deployment，具体资源规则由后续的 Deployment Strategy 执行。

请求上下文与对象解码

同一套 Handler 需要服务不同资源、版本和子资源。RequestScope 保存这条资源路由所需的处理能力：

• Resource、Kind、Subresource 标识当前资源、对象类型和子资源。
• Namer 从请求中取得名称与命名空间；Serializer 参与输入、输出格式协商。
• Creater、Convertor、Defaulter、Typer 提供对象创建、版本转换、默认值填充和类型识别能力。
• HubGroupVersion 指定内存处理使用的版本；Deployment 使用内部版本。
• FieldManager 维护字段管理信息，例如 metadata.managedFields。

每次请求的取消信号、用户身份和命名空间保存在请求的 context.Context 中。RequestScope 则由路由安装时配置，供该路由的 Handler 使用。

CreateResource 通过适配器调用 createHandler。Handler 读取请求体和 CreateOptions 后，使用资源的 New 方法取得对象容器，再通过 DecoderToVersion 把解码目标设为 HubGroupVersion。runtime.Object 提供类型信息访问和深拷贝接口，允许通用 Handler 接收不同的 API 对象。

createHandler 的解码路径 根据 fieldValidation 选择解码器。Warn 和 Strict 都使用严格解码器，后续错误分支再决定把未知字段等问题作为警告还是错误处理。

func createHandler(r rest.NamedCreater, scope *RequestScope, admit admission.Interface, includeName bool) http.HandlerFunc {
    return func(w http.ResponseWriter, req *http.Request) {
        ...
        defaultGVK := scope.Kind
        original := r.New()

        // 按字段校验模式选择普通或严格解码器。
        validationDirective := fieldValidation(options.FieldValidation)
        decodeSerializer := s.Serializer
        if validationDirective == metav1.FieldValidationWarn || validationDirective == metav1.FieldValidationStrict {
            decodeSerializer = s.StrictSerializer
        }

        // 解码目标是后续内存处理使用的版本。
        decoder := scope.Serializer.DecoderToVersion(decodeSerializer, scope.HubGroupVersion)
        ...
        obj, gvk, err := decoder.Decode(body, &defaultGVK, original)
        ...
    }
}

创建调用与校验回调

解码完成后，Handler 检查对象的命名空间，清理客户端提供的系统元数据，并把对象、用户、资源、操作类型和 dry-run 标志封装成准入属性。FieldManager.UpdateNoErrors 更新字段管理信息，随后调用 MutationInterface.Admit。

Validating Admission 通过回调传给资源的 Create 方法。AdmissionToValidateObjectFunc 返回一个 ValidateObjectFunc：执行这个回调时，它依据传入对象重新构造准入属性，补齐可能由 Registry 生成的名称，再调用 ValidationInterface.Validate。

requestFunc 保存创建操作；定义闭包时尚未执行 r.Create。调用顺序是更新字段管理信息、执行 Admit，然后执行闭包，把对象和新构造的校验回调传入 Registry。

admissionAttributes := admission.NewAttributesRecord(
    obj, nil, scope.Kind, namespace, name, scope.Resource,
    scope.Subresource, admission.Create, options,
    dryrun.IsDryRun(options.DryRun), userInfo,
)

// 定义创建操作；校验回调由 Registry 在合适的阶段执行。
requestFunc := func() (runtime.Object, error) {
    return r.Create(
        ctx, name, obj,
        rest.AdmissionToValidateObjectFunc(admit, admissionAttributes, scope),
        options,
    )
}
...
result, err := finisher.FinishRequest(ctx, func() (runtime.Object, error) {
    liveObj, err := scope.Creater.New(scope.Kind)
    if err != nil {
        return nil, fmt.Errorf("failed to create new object (Create for %v): %v", scope.Kind, err)
    }
    obj = scope.FieldManager.UpdateNoErrors(liveObj, obj, managerOrUserAgent(options.FieldManager, req.UserAgent()))
    admit = fieldmanager.NewManagedFieldsValidatingAdmissionController(admit)

    // 变更准入通过后才调用资源创建接口。
    if mutatingAdmission, ok := admit.(admission.MutationInterface); ok && mutatingAdmission.Handles(admission.Create) {
        if err := mutatingAdmission.Admit(ctx, admissionAttributes, scope); err != nil {
            return nil, err
        }
    }
    ...
    result, err := requestFunc()
    ...
    return result, err
})

创建成功后，transformResponseObject 按协商的媒体类型和响应版本编码结果，返回 201 Created。服务端 dry-run 也经过这条响应路径，是否持久化由传入存储层的 dry-run 标志决定。

准入插件管理与调用¶

API Server 在启动时按配置创建准入插件，并把实例保存到同一条有序插件链中。处理请求时，Admit 和 Validate 分别遍历这条链，选择支持当前操作且实现相应接口的插件。一个插件可以同时参与两个阶段。

插件注册与初始化

RegisterAllAdmissionPlugins 汇总内置插件的注册入口。各插件通过 Plugins.Register 把名称和工厂函数写入注册表，工厂函数负责根据插件配置创建实例。

AdmissionOptions.ApplyTo 取得启用的插件列表，读取配置，准备 Client、Informer 等共享依赖，再调用 NewFromPlugins。插件的排列遵循选项中的推荐顺序和启用、禁用配置。

NewFromPlugins 逐个读取配置并初始化插件；InitPlugin 调用工厂、注入依赖，再执行初始化检查。完成的链经过重入包装和指标包装后，保存到 Config.AdmissionControl。

func (ps *Plugins) NewFromPlugins(pluginNames []string, configProvider ConfigProvider, pluginInitializer PluginInitializer, decorator Decorator) (Interface, error) {
    handlers := []Interface{}
    ...
    for _, pluginName := range pluginNames {
        pluginConfig, err := configProvider.ConfigFor(pluginName)
        if err != nil {
            return nil, err
        }

        // 创建实例、注入依赖并校验初始化结果。
        plugin, err := ps.InitPlugin(pluginName, pluginConfig, pluginInitializer)
        if err != nil {
            return nil, err
        }
        if plugin != nil {
            if decorator != nil {
                handlers = append(handlers, decorator.Decorate(plugin, pluginName))
            } else {
                handlers = append(handlers, plugin)
            }
            ...
        }
    }
    ...
    // 两个准入阶段共用同一组有序插件实例。
    return newReinvocationHandler(chainAdmissionHandler(handlers)), nil
}