Talos Linux 的 KubeAdmissionControlConfig 配置指南:为 kube-apiserver 定制准入控制插件
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。步骤如下:
- 编写配置文档:将上述示例中的
name改为目标插件名(如ResourceQuota、LimitRanger),configuration填入该插件对应的 Kubernetes 配置对象。Talos 不校验插件配置内容,只要求它是合法的结构化 YAML。 - 合并到集群配置:使用
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>
- 注意互斥约束:若配置中已存在 v1alpha1 的
cluster.apiServer.admissionControl字段,需要先移除该字段,否则配置校验会因冲突而失败。 - 验证生效:应用后检查 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 控制平面的准入策略。