> For the complete documentation index, see [llms.txt](https://kubernetes.feisky.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://kubernetes.feisky.xyz/extension/auth/admission.md). # 准入控制 准入控制（Admission Control）在授权后对请求做进一步的验证或添加默认参数。不同于授权和认证只关心请求的用户和操作，准入控制还处理请求的内容，并且仅对创建、更新、删除或连接（如代理）等有效，而对读操作无效。 准入控制支持同时开启多个插件，它们依次调用，只有全部插件都通过的请求才可以放过进入系统。 Kubernetes 目前提供了以下几种准入控制插件 * AlwaysAdmit: 接受所有请求。 * AlwaysPullImages: 总是拉取最新镜像。在多租户场景下非常有用。 * DenyEscalatingExec: 禁止特权容器的 exec 和 attach 操作。 * ImagePolicyWebhook: 通过 webhook 决定 image 策略，需要同时配置 `--admission-control-config-file`，配置文件格式见 [这里](https://kubernetes.io/docs/admin/admission-controllers/#configuration-file-format)。 * ServiceAccount：自动创建默认 ServiceAccount，并确保 Pod 引用的 ServiceAccount 已经存在 * SecurityContextDeny：拒绝包含非法 SecurityContext 配置的容器 * ResourceQuota：限制 Pod 的请求不会超过配额，需要在 namespace 中创建一个 ResourceQuota 对象 * LimitRanger：为 Pod 设置默认资源请求和限制，需要在 namespace 中创建一个 LimitRange 对象 * InitialResources：根据镜像的历史使用记录，为容器设置默认资源请求和限制 * NamespaceLifecycle：确保处于 termination 状态的 namespace 不再接收新的对象创建请求，并拒绝请求不存在的 namespace * DefaultStorageClass：为 PVC 设置默认 StorageClass（见 [这里](/concepts/objects/persistent-volume.md#StorageClass)） * DefaultTolerationSeconds：设置 Pod 的默认 forgiveness toleration 为 5 分钟 * PodSecurityPolicy：使用 Pod Security Policies 时必须开启 * NodeRestriction：限制 kubelet 仅可访问 node、endpoint、pod、service 以及 secret、configmap、PV 和 PVC 等相关的资源（仅适用于 v1.7+） * EventRateLimit：限制事件请求数量（仅适用于 v1.9） * ExtendedResourceToleration：为使用扩展资源（如 GPU 和 FPGA 等）的 Pod 自动添加 tolerations * StorageProtection：自动给新创建的 PVC 增加 `kubernetes.io/pvc-protection` finalizer（v1.9 及以前版本为 `PVCProtection`，v.11 GA） * PersistentVolumeClaimResize：允许设置 `allowVolumeExpansion=true` 的 StorageClass 调整 PVC 大小（v1.11 Beta） * PodNodeSelector：限制一个 Namespace 中可以使用的 Node 选择标签 * ValidatingAdmissionWebhook：使用 Webhook 验证请求，这些 Webhook 并行调用，并且任何一个调用拒绝都会导致请求失败 * MutatingAdmissionWebhook：使用 Webhook 修改请求，这些 Webhook 依次顺序调用 Kubernetes v1.7 + 还支持 Initializers 和 GenericAdmissionWebhook，可以用来方便地扩展准入控制。 ## Initializers Initializers 可以用来给资源执行策略或者配置默认选项，包括 Initializers 控制器和用户定义的 Initializer 任务，控制器负责执行用户提交的任务，并完成后将任务从 `metadata.initializers` 列表中删除。 Initializers 的开启方法为 * kube-apiserver 配置 `--admission-control=...,Initializers` * kube-apiserver 开启 `admissionregistration.k8s.io/v1alpha1` API，即配置 `--runtime-config=admissionregistration.k8s.io/v1alpha1` * 部署 Initializers 控制器 另外，可以使用 `initializerconfigurations` 来自定义哪些资源开启 Initializer 功能 ```yaml apiVersion: admissionregistration.k8s.io/v1alpha1 kind: InitializerConfiguration metadata: name: example-config initializers: # the name needs to be fully qualified, i.e., containing at least two "." - name: podimage.example.com rules: # apiGroups, apiVersion, resources all support wildcard "*". # "*" cannot be mixed with non-wildcard. - apiGroups: - "" apiVersions: - v1 resources: - pods ``` Initializers 可以用来 * 修改资源的配置，比如自动给 Pod 添加一个 sidecar 容器或者存储卷 * 如果不需要修改对象的话，建议使用性能更好的 GenericAdmissionWebhook。 如何开发 Initializers * 参考 [Kubernetes Initializer Tutorial](https://github.com/kelseyhightower/kubernetes-initializer-tutorial) 开发 Initializer * Initializer 必须有一个全局唯一的名字，比如 `initializer.vaultproject.io` * Initializer 有可能收到信息不全的资源（比如还未调度的 Pod 没有 nodeName 和 status），在实现时需要考虑这种情况 * 对于 Initializer 自身的部署，可以使用 Deployment，但需要手动设置 initializers 列表为空，以避免无法启动的问题，如 ```yaml apiVersion: apps/v1beta1 kind: Deployment metadata: initializers: pending: [] ``` ## GenericAdmissionWebhook GenericAdmissionWebhook 提供了一种 Webhook 方式的准入控制机制，它不会改变请求对象，但可以用来验证用户的请求。 GenericAdmissionWebhook 的开启方法 * kube-apiserver 配置 `--admission-control=...,GenericAdmissionWebhook` * kube-apiserver 开启 `admissionregistration.k8s.io/v1alpha1` API，即配置 `--runtime-config=admissionregistration.k8s.io/v1alpha1` * 实现并部署 webhook 准入控制器，参考 [这里](https://github.com/caesarxuchao/example-webhook-admission-controller) 的示例 注意，webhook 准入控制器必须使用 TLS，并需要通过 `externaladmissionhookconfigurations.clientConfig.caBundle` 向 kube-apiserver 注册： ```yaml apiVersion: admissionregistration.k8s.io/v1alpha1 kind: ExternalAdmissionHookConfiguration metadata: name: example-config externalAdmissionHooks: - name: pod-image.k8s.io rules: - apiGroups: - "" apiVersions: - v1 operations: - CREATE resources: - pods # fail upon a communication error with the webhook admission controller # Other options: Ignore failurePolicy: Fail clientConfig: caBundle: service: name: namespace: ``` ## PodNodeSelector PodNodeSelector 用来限制一个 Namespace 中 Pod 所允许运行的 Node（功能跟 Taint 相反）。 使用示例： ```yaml apiVersion: v1 kind: Namespace metadata: annotations: scheduler.alpha.kubernetes.io/node-selector: env=production name: namespace3 ``` ## 用户命名空间准入控制（Kubernetes v1.33+） 从 Kubernetes v1.33 开始，用户命名空间功能默认启用，准入控制器可以用来强制执行用户命名空间策略。以下是一些常见的用户命名空间准入控制场景： ### 使用 ValidatingAdmissionWebhook 强制用户命名空间 可以通过自定义 ValidatingAdmissionWebhook 来强制特定工作负载启用用户命名空间： ```yaml apiVersion: admissionregistration.k8s.io/v1 kind: ValidatingAdmissionWebhook metadata: name: enforce-user-namespaces webhooks: - name: usernamespace.security.example.com admissionReviewVersions: ["v1", "v1beta1"] rules: - operations: ["CREATE", "UPDATE"] apiGroups: [""] apiVersions: ["v1"] resources: ["pods"] # 示例：强制高安全级别的 Pod 使用用户命名空间 namespaceSelector: matchLabels: security-level: high clientConfig: service: name: usernamespace-webhook namespace: security-system path: "/validate" ``` ### 使用 MutatingAdmissionWebhook 自动添加用户命名空间 可以通过 MutatingAdmissionWebhook 自动为符合条件的 Pod 启用用户命名空间： ```yaml apiVersion: admissionregistration.k8s.io/v1 kind: MutatingAdmissionWebhook metadata: name: auto-usernamespace webhooks: - name: auto-usernamespace.security.example.com admissionReviewVersions: ["v1", "v1beta1"] rules: - operations: ["CREATE"] apiGroups: [""] apiVersions: ["v1"] resources: ["pods"] # 自动为多租户命名空间中的 Pod 启用用户命名空间 namespaceSelector: matchLabels: tenant: "true" clientConfig: service: name: usernamespace-mutator namespace: security-system path: "/mutate" ``` ### 安全策略建议 在设计用户命名空间准入控制策略时，建议考虑以下因素： * **渐进式部署**：从非关键工作负载开始，逐步扩展到生产环境 * **兼容性检查**：确保应用程序与用户命名空间兼容 * **容器运行时要求**：验证容器运行时支持用户命名空间（containerd 2.0+ 或 CRI-O） * **内核版本检查**：确保节点运行支持的内核版本（Linux 5.19+，推荐 6.3+） ## 推荐配置 对于 Kubernetes >= 1.9.0，推荐配置以下插件 ```bash --admission-control=NamespaceLifecycle,LimitRanger,ServiceAccount,DefaultStorageClass,DefaultTolerationSeconds,MutatingAdmissionWebhook,ValidatingAdmissionWebhook,ResourceQuota ``` 对于 Kubernetes >= 1.6.0，推荐 kube-apiserver 开启以下插件 ```bash --admission-control=NamespaceLifecycle,LimitRanger,ServiceAccount,PersistentVolumeLabel,DefaultStorageClass,ResourceQuota,DefaultTolerationSeconds ``` 对于 Kubernetes >= 1.4.0，推荐配置以下插件 ```bash --admission-control=NamespaceLifecycle,LimitRanger,ServiceAccount,DefaultStorageClass,ResourceQuota ``` ## 参考文档 * [Using Admission Controllers](https://kubernetes.io/docs/admin/admission-controllers/) * [How Kubernetes Initializers work](https://medium.com/google-cloud/how-kubernetes-initializers-work-22f6586e1589)