Kubernetes Pod Security Admission Webhook 独立部署指南为无法内置启用 PodSecurity 的集群接入 Pod 安全标准【免费下载链接】kubernetesProduction-Grade Container Scheduling and Management项目地址: https://gitcode.com/GitHub_Trending/kuber/kubernetes本篇指南介绍 Kubernetes 官方仓库中staging/src/k8s.io/pod-security-admission/webhook目录下的 Pod Security Admission Webhook下文简称 Pod Security Webhook。它是一个校验型动态准入控制器Validating Admission Webhook使用与内置于kube-apiserver的 Pod Security Admission Controller 完全相同的 Go 代码包构建专门面向那些无法启用内置 PodSecurity 准入控制器的集群。读完本文你将掌握该 Webhook 的证书生成、Kustomize 一键部署、清单逐项拆解、PodSecurityConfiguration 配置编写以及底层命令行参数与实现原理能够在自己的集群中复刻这套独立的安全准入方案。一、为什么需要独立运行的 Pod Security WebhookKubernetes 的 Pod 安全标准Pod Security Standards定义了privileged、baseline、restricted三级安全基线并通过命名空间标签驱动准入控制。在常规集群中这一能力由内置的PodSecurity准入控制器Admission Controller直接提供。但并非所有环境都能使用内置控制器。Webhook 的 README.md 明确指出该 Webhook适用于无法使用内置 PodSecurity 准入控制器的环境例如准入控制器列表受限、API Server 版本过旧、或使用第三方发行版托管控制面等场景。它的核心设计特点是复用同一套代码逻辑README 原文强调其 built with the same Go package as the Pod Security Admission Controller。从仓库目录结构可以印证这一点——pod-security-admission 下同时包含admission/准入校验实现与配置 APIPodSecurityConfiguration的v1alpha1/v1beta1/v1版本定义policy/Pod 安全标准三级策略的校验逻辑cmd/webhook/独立 Webhook 服务的入口webhook/本文讲解的镜像构建与部署清单。因此无论是以内置控制器还是独立 Webhook 的形式运行策略判定结果与配置语义都能保持一致这大大降低了迁移与维护成本。二、快速开始从证书生成到一键部署1. 目录结构与交付物概览webhook 目录包含三类交付物文件作用Makefile构建二进制、构建镜像、生成证书、推送镜像的入口Dockerfile基于gcr.io/distroless/static:latest的极简运行镜像入口为/pod-security-webhook二进制manifests/9 个示例 Kubernetes 清单命名空间、RBAC、Deployment、Service、Webhook 配置等kustomization.yaml根目录顶层 Kustomize组合清单 生成 TLS Secret 注入 CA 到 Webhook 配置kustomization.yamlmanifests 内子层 Kustomize声明要渲染的基础清单文件README 说明该 Webhook 的镜像托管在 SIG-Auth 的容器镜像仓库中。Makefile 中默认REGISTRY gcr.io/k8s-staging-sig-auth、IMAGE gcr.io/k8s-staging-sig-auth/pod-security-webhook而 50-deployment.yaml 中实际引用的正式发布镜像为registry.k8s.io/sig-auth/pod-security-webhook:v1.25.0。2. 生成 Webhook 证书Webhook 以 HTTPS 提供服务因此需要一对 CA 证书与 Webhook 服务端证书。README 给出的命令只有一行make certs但为了让读者理解其背后发生了什么这里展开 Makefile 中certs目标L47-L57的完整步骤创建pki/目录用openssl genrsa生成 2048 位 CA 私钥pki/ca.key用openssl req生成自签 CA 证书pki/ca.crt有效期 3650 天Common Name 形如pod-security-webhook-ca-$(时间戳)生成 Webhook 服务端私钥pki/tls.key与证书签名请求pki/tls.csr其 CN 为webhook.pod-security-webhook.svc——这正是稍后 Service 在集群内的 DNS 名称写入 SAN 扩展文件pki/extensions.txtsubjectAltNameDNS:webhook.pod-security-webhook.svc并追加extendedKeyUsageserverAuth表明该证书仅用于服务端认证用 CA 为 CSR 签发有效期 730 天的服务端证书pki/tls.crt。最终在pki/下产出三个文件ca.crt、tls.crt、tls.key。make certs生成的证书正好覆盖https://webhook.pod-security-webhook.svc这一服务地址与 README 的表述一致。如需自定义域名则需要按上面的流程自行调整 CN 与 SAN。3. 使用 Kustomize 部署 Webhook证书就绪后执行kubectl apply -k .-k .表示在 webhook 目录下以 Kustomize 方式渲染并应用。整个流程由两层kustomization.yaml驱动内层 manifests/kustomization.yaml 声明了 9 个基础资源文件外层 kustomization.yaml 做三件事README 将其概括为应用 manifests 子目录下的清单、创建包含服务端证书的 Secret、把 CA bundle 注入校验 Webhookbases: - ./manifests # 生成 TLS Secret secretGenerator: - name: pod-security-webhook namespace: pod-security-webhook type: kubernetes.io/tls options: disableNameSuffixHash: true files: - pki/ca.crt - pki/tls.crt - pki/tls.key # 将 CA 注入 ValidatingWebhookConfiguration replacements: - source: kind: Secret name: pod-security-webhook namespace: pod-security-webhook fieldPath: data.ca\.crt targets: - select: kind: ValidatingWebhookConfiguration name: pod-security-webhook.kubernetes.io fieldPaths: - webhooks.0.clientConfig.caBundle - webhooks.1.clientConfig.caBundle options: create: true其中secretGenerator把pki/下三个文件打包成名为pod-security-webhook的kubernetes.io/tls类型 SecretdisableNameSuffixHash: true保证 Secret 名字不含随机后缀便于 Deployment 稳定引用replacements则从该 Secret 中取出ca.crt内容自动回填到ValidatingWebhookConfiguration两个 webhook 条目的clientConfig.caBundle字段。这就是为什么 70-validatingwebhookconfiguration.yaml 中两个 webhook 的caBundle都先留空——最终由 Kustomize 在 apply 阶段填充。提示若make certs之前已经执行过kubectl apply -k .重新生成证书后需要再次 apply 以刷新 Secret 中的证书数据。三、部署清单逐项拆解为了让读者能按需裁剪下面把manifests/下的清单逐个讲清楚。1. 命名空间10-namespace.yaml10-namespace.yaml 创建pod-security-webhook命名空间并打上标签labels: pod-security.kubernetes.io/enforce: restricted清单注释说明虽然 Webhook 的namespaceSelector会排除该命名空间以避免Webhook 校验 Webhook 自己的循环依赖但 Deployment 的 Pod spec 本身完全兼容restricted级别非 root 用户、丢弃全部 capabilities、禁用特权提升等见下文 Deployment 一节因此仍将其标记为restricted保持命名空间安全标签的一致性与可审计性。2. RBACServiceAccount / ClusterRole / ClusterRoleBindingWebhook 在校验时需要读取命名空间获取其上的 Pod 安全标签与被校验对象本身因此需要只读权限20-serviceaccount.yaml创建同名的ServiceAccount30-clusterrole.yaml定义ClusterRole仅授予对pods、namespaces的get/watch/list三个只读动词——权限遵循最小化原则40-clusterrolebinding.yaml将上述二者绑定。3. 配置与密钥的载体ConfigMap / Secret配置与证书并不直接写死在 Deployment 中而是以 ConfigMap 与 Secret 形式挂载20-configmap.yaml把PodSecurityConfiguration配置以podsecurityconfiguration.yaml为 key 存放内容详见下一节pod-security-webhookSecret由外层 Kustomize 的secretGenerator生成内含ca.crt、tls.crt、tls.key。4. Deployment50-deployment.yaml50-deployment.yaml 是运行核心值得逐点关注spec: serviceAccountName: pod-security-webhook priorityClassName: system-cluster-critical nodeSelector: kubernetes.io/os: linux kubernetes.io/arch: amd64 volumes: - name: config configMap: { name: pod-security-webhook } - name: pki secret: { secretName: pod-security-webhook } containers: - name: pod-security-webhook image: registry.k8s.io/sig-auth/pod-security-webhook:v1.25.0 terminationMessagePolicy: FallbackToLogsOnError ports: - name: webhook containerPort: 10250 args: [ --config, /etc/config/podsecurityconfiguration.yaml, --tls-cert-file, /etc/pki/tls.crt, --tls-private-key-file, /etc/pki/tls.key, --secure-port, 10250, ]几个设计细节均来自清单内注释与结构解释如下监听端口选择 10250端口大于 1024 无需低端口绑定特权且 10250 与 kubelet 端口相同在 apiserver → 节点的防火墙规则中通常已被放行。由于 Pod 使用自身 IP 且未启用hostNetwork与 kubelet 并不会发生端口冲突镜像 tag 为v1.25.0这是当前仓库清单中固定引用的版本实际部署时可替换为所需版本priorityClassName: system-cluster-critical让 Webhook Pod 成为集群关键负载配合 20-resourcequota.yaml 中针对该优先级类、上限为pods: 3的 ResourceQuota在资源紧张时也能保证 Webhook 可被调度安全上下文完全符合restricted基线allowPrivilegeEscalation: false、capabilities.drop: [ALL]、runAsNonRoot: true、runAsUser: 1000、seccompProfile: RuntimeDefault与命名空间上的restricted标签一致示范了安全组件自身也遵守安全基线的实践资源请求/限制requests 100m CPU、limits 500m CPUConfigMap 挂载到/etc/config只读Secret 挂载到/etc/pki只读。5. Service60-service.yaml60-service.yaml 将 Webhook 暴露为集群内服务metadata: name: webhook # 完整 DNSwebhook.pod-security-webhook.svc spec: ports: - port: 443 targetPort: webhook selector: app: pod-security-webhookService 名webhook 命名空间pod-security-webhook恰好构成证书中签发的 SAN/CN 地址webhook.pod-security-webhook.svc443 端口转发到容器的webhook命名端口即 10250。6. ValidatingWebhookConfiguration70-validatingwebhookconfiguration.yaml70-validatingwebhookconfiguration.yaml 定义了两个webhook 条目职责分工不同这是理解该方案的关键条目一强制执行 webhookpod-security-webhook.kubernetes.io作用于CREATE/UPDATE覆盖资源namespaces、pods、pods/ephemeralcontainers——即真正的 Pod 级强制点failurePolicy: Fail失败即拒绝fail-closed。清单注释也提醒fail-closed 会给运维带来挑战可考虑改为Ignore但必须权衡安全收益的损失namespaceSelector使用kubernetes.io/metadata.name NotIn [pod-security-webhook]显式排除自身命名空间避免循环依赖通过clientConfig.service指向pod-security-webhook/webhooksideEffects: None、admissionReviewVersions: [v1]、timeoutSeconds: 5。条目二建议/审计 webhookadvisory.pod-security-webhook.kubernetes.io覆盖高阶工作负载对象本身deployments、statefulsets、daemonsets、replicasets、jobs、cronjobs、podtemplates、replicationcontrollers以便在审计audit与告警warn模式下对模板中尚未生成的 Pod给出建议性结果也能以注解形式输出审计信息failurePolicy: Ignore非强制性的审计通道可以安全地 fail-open清单注释Non-enforcing resources can safely fail-open。命名空间标签中pod-security.kubernetes.io/audit、/warn所触发的注解将分别带有上面两个 webhook 的名称前缀方便在事件与审计日志中识别来源。四、Webhook 配置PodSecurityConfiguration 详解与内置 PodSecurity 准入控制器一致Webhook 需要一个配置文件来决定如何校验进入的资源。README 也强调真实部署前强烈建议先阅读官方关于如何为不同负载选择合适策略级别policy levels的文档如从 PSP 迁移时的分级建议。该配置文件由 20-configmap.yaml 承载完整内容如下apiVersion: v1 kind: ConfigMap metadata: name: pod-security-webhook namespace: pod-security-webhook data: podsecurityconfiguration.yaml: | apiVersion: pod-security.admission.config.k8s.io/v1beta1 kind: PodSecurityConfiguration # 当命名空间未设置 mode 标签时使用的默认值。 # # Level 标签取值必须是下列之一 # - privileged默认 # - baseline # - restricted # # Version 标签取值必须是下列之一 # - latest默认 # - 具体版本如 v1.22 defaults: enforce: privileged enforce-version: latest audit: privileged audit-version: latest warn: privileged warn-version: latest exemptions: # 需要豁免的已认证用户名列表。 usernames: [] # 需要豁免的 RuntimeClass 名称列表。 runtimeClasses: [] # 需要豁免的命名空间列表。 namespaces: []配置字段语义defaults默认策略对应内置控制器的四个维度——enforce强制拒绝违规 Pod、audit记录审计事件但不拒绝、warn向 API 返回用户可见的警告。每个维度既可单独配level也可配version策略版本level取值只能是privileged、baseline、restricted三者之一默认privileged即默认不收紧避免未打标签的命名空间被误伤version取值是latest或形如v1.22的具体版本默认latest跟踪最新策略规则。exemptions豁免三类豁免对象——usernames按已认证用户名整体跳过校验runtimeClasses按 RuntimeClass 名称跳过校验例如需要特权运行时的特殊工作负载namespaces按命名空间跳过校验。这些默认值与豁免项与命名空间上的pod-security.kubernetes.io/{enforce,audit,warn}、pod-security.kubernetes.io/{enforce,audit,warn}-version标签共同决定最终判定命名空间标签优先未设置标签时回落到配置文件中的defaults。样本配置中三者默认均为privileged属于默认放行、按命名空间逐步收紧的稳妥策略——这正是从宽松策略向安全基线渐进迁移的推荐做法。配置 API 的类型定义位于 admission/api/types.go其中v1alpha1、v1beta1、v1各版本的类型与默认值实现可分别在 admission/api/v1alpha1/types.go、admission/api/v1beta1/types.go、admission/api/v1/types.go 中查看字段校验逻辑在 admission/api/validation/validation.go。五、命令行参数与运行原理源码级Webhook 的 Go 入口在 cmd/webhook/webhook.go服务端组装逻辑在 cmd/webhook/server/server.go参数定义集中在 cmd/webhook/server/options/options.go。支持的命令行参数Options 结构体L33-L44与AddFlagsL58-L65定义了如下参数参数类型默认值说明--configstring空PodSecurity 配置文件路径必填对应--config /etc/config/podsecurityconfiguration.yaml--kubeconfigstring空连接 API Server 的 kubeconfig 路径留空则使用集群内配置in-cluster config--client-qps-limitfloat3220访问 API Server 的 QPS 上限限流--client-qps-burstint50访问 API Server 的突发 QPS 上限--secure-portint8443安全端口来自 apiserver 的 SecureServingOptions默认DefaultPort 8443清单中显式覆盖为10250--tls-cert-filestring空HTTPS 服务端证书路径--tls-private-key-filestring空HTTPS 服务端私钥路径其中 TLS 相关 flag 来自k8s.io/apiserver/pkg/server/options的SecureServingOptionsoptions.go L47-L54 使用NewSecureServingOptions()并在ServerCert.PairName指定为webhook。值得注意的是 QPS 限流参数的默认值DefaultClientQPSLimit 20、DefaultClientQPSBurst 50确保 Webhook 在验证阶段需要回查命名空间标签时不会对 API Server 造成突发压力。为什么能保证与内置控制器判定一致README 的核心承诺是用与 Pod Security Admission Controller 相同的 Go 包构建。从代码组织看Webhook 进程只负责把AdmissionReview请求转交给位于 admission 与 policy 目录中的同一套策略评估逻辑这一部分同样被内置控制器复用。因此理论上两种部署形态下同一命名空间、同一 Pod 会得到一致的判定结果。这一点为先用 Webhook 做审计/告警、再在原生集群内切换到内置 enforce提供了平滑路径。校验的基本数据流由清单结构推断客户端提交namespaces、pods、pods/ephemeralcontainers的CREATE/UPDATE请求ValidatingWebhookConfiguration条目一命中API Server 向https://webhook.pod-security-webhook.svc:443发送AdmissionReviewWebhook 依据命名空间的 enforce/audit/warn 标签缺省回落到 ConfigMap 中的defaults与豁免清单调用策略引擎判定违反enforce的请求被拒绝failurePolicy: Fail下校验失败也拒绝违反audit/warn的请求被放行但写入审计注解与警告信息由 webhook 名称前缀区分来源。六、部署后的验证与运维要点部署完成后可以从几个角度确认 Webhook 工作正常确认资源就绪kubectl -n pod-security-webhook get deploy,svc,secret configmap检查 Deployment 可用、Service 存在、TLS Secret 已生成kubectl get validatingwebhookconfiguration pod-security-webhook.kubernetes.io -o yaml查看两个 webhook 的clientConfig.caBundle是否已被 Kustomize 填入验证 enforce在一个打了pod-security.kubernetes.io/enforce: baseline或restricted标签的测试命名空间中尝试创建privileged: true的 Pod应看到请求被 Admission 拒绝并返回策略说明观察 audit/warn在不影响运行的前提下用audit/warn模式先观察集群内工作负载的合规情况再决定是否提升为enforce证书有效期make certs签发的服务端证书有效期 730 天、CA 证书 3650 天需在到期前续期重新生成并 apply Secret 后必要时滚动重启 Deploymentfail-closed 的可用性权衡强制执行 webhook 的failurePolicy: Fail意味着该 Webhook 不可用时 Pod 创建会被阻塞需结合自身可用性要求评估是否改为Ignore清单注释已就这一取舍给出提示。七、参与贡献该 Webhook 属于k8s.io/pod-security-admission子项目的一部分贡献与代码规范遵循其父目录的指南详见 CONTRIBUTING.md涵盖问题报告、代码提交流程与开发约定。镜像构建与推送入口均可复用 Makefile 中的build、container、push、clean目标。小结Pod Security Admission Webhook 是 Kubernetes 在内置 PodSecurity 不可用场景下官方提供的同构替代方案它复用同一策略引擎、以独立进程 集群内服务的形式提供与内置控制器一致的 Pod 安全标准校验。通过make certskubectl apply -k .两条命令即可完成证书与整套清单的部署PodSecurityConfiguration的defaults/exemptions与命名空间标签共同决定了 enforce、audit、warn 三种模式的实际行为强制执行与建议/审计两个 Webhook 条目的解耦则让集群可以先审计后强制地安全落地 Pod 安全基线。【免费下载链接】kubernetesProduction-Grade Container Scheduling and Management项目地址: https://gitcode.com/GitHub_Trending/kuber/kubernetes创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
