Talos Linux 的 KubeAdmissionControlConfig 配置指南:为 kube-apiserver 定制准入控制插件

原创2026-09-22 19:49:551,852 阅读
文章标签:云原生操作系统容器编排

Talos Linux 的 KubeAdmissionControlConfig 配置指南:为 kube-apiserver 定制准入控制插件

KubeAdmissionControlConfig 是 Talos Linux(面向 Kubernetes 的现代 Linux 发行版)中用于配置 kube-apiserver 准入控制(Admission Control)插件的独立配置文档。它允许以多文档(multi-doc)配置的方式声明 PodSecurity 等准入插件及其完整参数,替代旧的 v1alpha1 cluster.apiServer.admissionControl 内联写法,且默认由 talosctl gen config 自动生成。读完本文,你将掌握该配置文档的字段语义、默认 PodSecurity 策略的完整参数、它与旧式配置的互斥关系,以及它在 machined 控制器与静态 Pod 渲染链路中的实际生效机制。

配置文档概览:结构与字段说明

KubeAdmissionControlConfig 是一个 apiVersion: v1alpha1、kind: KubeAdmissionControlConfig 的独立文档,与 Talos 多文档配置体系中的其他文档(如 KubeAPIServerConfig、KubeAuditPolicyConfig)并列存在。其完整结构如下:

apiVersion: v1alpha1
kind: KubeAdmissionControlConfig
name: PodSecurity # Admission control plugin name, should be a valid Kubernetes admission control plugin name.
# Kubernetes API server admission control plugins.
configuration:
    apiVersion: pod-security.admission.config.k8s.io/v1alpha1
    defaults:
        audit: restricted
        audit-version: latest
        enforce: baseline
        enforce-version: latest
        warn: restricted
        warn-version: latest
    exemptions:
        namespaces:
            - kube-system
        runtimeClasses: []
        usernames: []
    kind: PodSecurityConfiguration

该文档仅包含两个字段,含义如下:

字段 类型 描述 取值
name string 准入控制插件名,必须是合法的 Kubernetes 准入控制插件名。 如 PodSecurity、ResourceQuota、NamespaceLifecycle 等(官方插件列表)
configuration Unstructured Kubernetes API server 准入控制插件的字面配置,其值原样作为该插件的准入控制配置传入。 插件对应的配置结构,如 PodSecurityConfiguration 等

结构体定义与配置注册

该配置文档在源码中对应 KubeAdmissionControlConfigV1Alpha1 结构体,定义于 pkg/machinery/config/types/k8s/admission_control.go:

type KubeAdmissionControlConfigV1Alpha1 struct {
	meta.Meta `yaml:",inline"`

	MetaName string `yaml:"name"`
	PluginConfig meta.Unstructured `yaml:"configuration"`
}

其中 meta.Unstructured 意味着 configuration 字段在 YAML 解析层面是"透传"的:它不被 Talos 强类型化,而是以任意结构化数据的形式保留,最终以 JSON 形式写入 kube-apiserver 的准入控制配置文件。这种设计使得 Talos 无需为每个准入插件的配置结构单独建模,只要该插件的配置是合法的 Kubernetes 对象即可。

从文档注册机制看,该类型通过 init() 中的 registry.Register(KubeAdmissionControlConfig, ...) 注册为 v1alpha1 版本的可解析文档,并实现了以下接口(见 admission_control.go):

  • config.K8sAdmissionControlPluginConfig:作为准入控制插件配置参与集群配置合并;
  • config.NamedDocument:以 name 字段作为文档名;
  • config.Validator:参与配置校验;
  • container.V1Alpha1ConflictValidator:与旧式 v1alpha1 配置做冲突校验;
  • container.ControlplaneOnlyConfig:标记为仅适用于控制平面节点(定义见 pkg/machinery/config/container/container.go)。

默认 PodSecurity 配置:内置策略的完整参数

为降低使用门槛,Talos 提供了开箱即用的默认准入控制配置——DefaultPodSecurityAdmissionControlConfig(),其实现同样位于 admission_control.go:

func DefaultPodSecurityAdmissionControlConfig() *KubeAdmissionControlConfigV1Alpha1 {
	cfg := NewKubeAdmissionControlConfigV1Alpha1()
	cfg.MetaName = "PodSecurity"

	cfg.PluginConfig.Object = map[string]any{
		"apiVersion": "pod-security.admission.config.k8s.io/v1alpha1",
		"kind":       "PodSecurityConfiguration",
		"defaults": map[string]any{
			"enforce":         "baseline",
			"enforce-version": "latest",
			"audit":           "restricted",
			"audit-version":   "latest",
			"warn":            "restricted",
			"warn-version":    "latest",
		},
		"exemptions": map[string]any{
			"usernames":      []any{},
			"runtimeClasses": []any{},
			"namespaces":     []any{"kube-system"},
		},
	}

	return cfg
}

该默认配置的三个维度取值含义:

配置项 默认值 作用
enforce baseline 强制执行的最低安全级别,违反即拒绝创建 Pod
enforce-version latest 强制执行所使用的 Pod Security Standards 版本
audit restricted 以 restricted 级别记录审计事件,不阻止创建
audit-version latest 审计事件记录的版本
warn restricted 对违反 restricted 的请求发出警告,不阻止创建
warn-version latest 警告使用的版本
exemptions.namespaces ["kube-system"] 豁免的命名空间,其内 Pod 不参与 Pod Security 评估
exemptions.runtimeClasses [] 豁免的 RuntimeClass 列表
exemptions.usernames [] 豁免的用户名列表

这是一个典型的"渐进式安全"组合:enforce 使用 baseline 保证集群可运行性,同时通过 warn 与 audit 以更严格的 restricted 级别暴露潜在违规,便于逐步收紧策略。

默认文档的自动注入

该默认配置会被 talosctl gen config 自动写入生成的配置中,无需手动添加。证据位于 pkg/machinery/config/generate/kubernetes.go:在生成集群配置文档列表时,k8s.DefaultPodSecurityAdmissionControlConfig() 被作为第一批文档之一加入结果集。这意味着新生成的 Talos 集群默认启用 Pod Security 准入控制。

校验规则与旧式配置互斥

Talos 对 KubeAdmissionControlConfig 施加了两类校验(对应 admission_control_test.go 中的测试用例):

1. 字段必填校验(Validate):name 字段不能为空,否则返回错误 admission control plugin name is required。测试用例 TestKubeAdmissionControlConfigValidate 验证了空配置报错、合法配置通过两种情形。

2. 与 v1alpha1 旧式配置冲突校验(V1Alpha1ConflictValidate):如果同一个配置中还存在 v1alpha1 的 cluster.apiServer.admissionControl(旧的内联准入插件列表,定义于 pkg/machinery/config/types/v1alpha1/v1alpha1_types.go),则返回错误 admission control plugin config is already set in v1alpha1 config。这是 Talos 多文档配置迁移时的典型约束:同一条准入控制信息只能通过一种方式声明,避免语义歧义。相关测试用例见 TestKubeAdmissionControlConfigV1Alpha1Validate。

从配置到 kube-apiserver:生效链路解析

理解了文档本身的字段后,更关键的问题是:这个 YAML 文档究竟如何变成 kube-apiserver 启动时的 --admission-control-config-file?

第一步:合并为 AdmissionControlConfig 资源。 控制平面控制器将配置文档合并为单一资源 AdmissionControlConfigs.kubernetes.talos.dev(ID 为 admission-control),其定义在 pkg/machinery/resources/k8s/admissioncontrol_config.go。该资源的 Spec 由 []AdmissionPluginSpec 组成,每个元素包含插件 Name 与 Configuration(map[string]any),与文档结构一一对应。

第二步:渲染静态 Pod 配置文件。 internal/app/machined/pkg/controllers/k8s/render_config_static_pods.go 中的 admissionControlConfig() 函数读取该资源,将其转换为 Kubernetes 的 apiserverv1.AdmissionConfiguration 对象:

func admissionControlConfig(spec *k8s.AdmissionControlConfigSpec) func() (runtime.Object, error) {
	return func() (runtime.Object, error) {
		var cfg apiserverv1.AdmissionConfiguration

		cfg.APIVersion = apiserverv1.SchemeGroupVersion.String()
		cfg.Kind = "AdmissionConfiguration"
		cfg.Plugins = []apiserverv1.AdmissionPluginConfiguration{}

		for _, plugin := range spec.Config {
			raw, err := json.Marshal(plugin.Configuration)
			...
			cfg.Plugins = append(cfg.Plugins, apiserverv1.AdmissionPluginConfiguration{
				Name: plugin.Name,
				Configuration: &runtime.Unknown{Raw: raw},
			})
		}

		return &cfg, nil
	}
}

可以看到,Talos 将每个插件的 Configuration 通过 json.Marshal 序列化为 runtime.Unknown.Raw,原样嵌入 AdmissionConfiguration。这正是文档字段描述中"其值为字面 Kubernetes 准入控制配置"的实现体现——Talos 不解析、不改写插件配置内容,只负责传递。

第三步:触发渲染并滚动更新。 RenderConfigsStaticPodController 将 AdmissionControlConfig 声明为输入(render_config_static_pods.go),并在每次渲染后把各配置资源的版本号拼入 k8s.ConfigStatusStaticPodID 的版本中(render_config_static_pods.go)。也就是说,一旦你修改 KubeAdmissionControlConfig 文档并应用新配置,控制平面控制器会感知到资源版本变化,从而触发 kube-apiserver 静态 Pod 的重新渲染与滚动更新,准入控制配置即告生效。

自定义准入控制插件:实践步骤

基于上述机制,你可以扩展出任意 Kubernetes 准入插件,而不限于 PodSecurity。步骤如下:

  1. 编写配置文档:将上述示例中的 name 改为目标插件名(如 ResourceQuota、LimitRanger),configuration 填入该插件对应的 Kubernetes 配置对象。Talos 不校验插件配置内容,只要求它是合法的结构化 YAML。
  2. 合并到集群配置:使用 talosctl config patch(或直接在生成的多文档配置文件中追加该文档)将其并入 controlplane 配置,例如:
talosctl gen config <cluster-name> <cluster-endpoint> \
  --with-docs=false --with-examples=false > talosconfig.yaml
# 编辑 talosconfig.yaml,追加 KubeAdmissionControlConfig 文档
talosctl apply-config --file talosconfig.yaml --nodes <controlplane-node>
  1. 注意互斥约束:若配置中已存在 v1alpha1 的 cluster.apiServer.admissionControl 字段,需要先移除该字段,否则配置校验会因冲突而失败。
  2. 验证生效:应用后检查 kube-apiserver 静态 Pod 是否滚动更新,并观察其启动参数中的 --admission-control-config-file 指向的配置文件内容。

小结

KubeAdmissionControlConfig 是 Talos Linux 多文档配置体系中面向准入控制的统一入口:name 指定插件、configuration 透传插件的字面配置。Talos 内置了以"enforce=baseline、warn/audit=restricted"为组合的默认 PodSecurity 配置,并在 talosctl gen config 时自动注入;运行时则由 machined 控制器将文档合并为 AdmissionControlConfig 资源、渲染为 AdmissionConfiguration 文件交给 kube-apiserver。掌握它的字段语义、默认参数与生效链路,即可安全、精准地定制 Kubernetes 控制平面的准入策略。

登录后查看全文
talos