企业官网建设流程全解析

• 云原生
• 操作系统
• 容器编排

本篇文章围绕 Talos Linux 机器配置中security配置文档族展开，系统讲解ImageVerificationConfig（镜像签名验证策略）与TrustedRootsConfig（附加受信 CA 根）两类文档的 YAML 结构与字段语义，并结合仓库源码说明其解析、校验、落盘与消费链路，帮助你在 Talos Linux 集群中落地镜像供应链安全与私有 CA 信任能力。

一、security 配置文档族概览

在 Talos Linux 的配置体系中，apiVersion: v1alpha1之下除了经典的MachineConfig之外，还支持一系列独立的配置文档（config documents）。security包提供了与安全相关的机器配置文档，仓库中的文档骨架位于 website/content/v1.15/reference/configuration/security/_index.md，其下包含两份实质性文档：

源码层面，这两类文档的类型定义与校验逻辑分别位于 pkg/machinery/config/types/security/image_verification.go 与 pkg/machinery/config/types/security/trusted_roots.go，它们在init()中通过registry.Register注册到配置文档注册表（见 pkg/machinery/config/internal/registry），从而能被MachineConfig之外的独立文档形式被解析和加载。

二、ImageVerificationConfig：镜像签名验证策略

2.1 完整配置示例

ImageVerificationConfig文档的完整 YAML 示例如下（与官方参考文档及源码中的exampleImageVerificationConfigV1Alpha1()示例一致，见 pkg/machinery/config/types/security/image_verification.go）：

apiVersion: v1alpha1 kind: ImageVerificationConfig # List of verification rules. rules: - image: registry.k8s.io/* # Image reference pattern to match for this rule. # Keyless verifier configuration to use for this rule. keyless: issuer: https://accounts.google.com # OIDC issuer URL for keyless verification. subject: krel-trust@k8s-releng-prod.iam.gserviceaccount.com # Expected subject for keyless verification. # # Regex pattern for subject matching. # subjectRegex: .*@example\.com - image: my-registry.example.com/* # Image reference pattern to match for this rule. # Public key verifier configuration to use for this rule. publicKey: certificate: |- # A public certificate in PEM format accepted for image signature verification. -----BEGIN CERTIFICATE----- MII--Sample Value-- -----END CERTIFICATE----- - image: localhost:3000/* # Image reference pattern to match for this rule. deny: true # Deny pulling images matching the pattern (default: false).

该文档只有一个顶层字段rules，类型为[]ImageVerificationRuleV1Alpha1（字段定义见 pkg/machinery/config/types/security/image_verification.go）：

2.2 规则字段（rules[]）

每条ImageVerificationRuleV1Alpha1定义一条验证规则，其字段如下（源码定义见 pkg/machinery/config/types/security/image_verification.go）：

2.2.1image：镜像引用模式匹配规则

image字段支持 glob 通配模式，但只匹配镜像的 registry 和 repository 部分，不匹配 tag 或 digest。匹配针对归一化后的镜像引用进行——归一化引用总是以 registry 域名开头：

• docker.io/library/nginx*可以匹配nginx:latest；
• 而library/nginx*匹配不到任何镜像（缺少 registry 域）；
• Docker Hub 的域名始终被归一化为docker.io，因此针对index.docker.io或registry-1.docker.io编写的模式与docker.io模式匹配到的是同一批镜像。

官方文档给出的两个示例：

image: docker.io/library/nginx

image: registry.k8s.io/*

需要说明的是，该匹配语义并不仅仅是一句文档描述。在Validate()中，Talos 会对模式做合法性预警（见 pkg/machinery/config/types/security/image_verification.go）：

• 模式中包含@（digest 分隔符）时给出警告：匹配只作用于 registry 与 repository，不作用于 tag 或 digest；
• 模式中包含:且位于第一个/之后（很可能误把 tag 写进了模式）时给出警告；
• 通过patternMatchesNoImage()（见同文件 L280-L300）判断模式是否“无论如何都匹配不到任何镜像”——例如没有 glob 也没有/的模式，因为每个归一化引用都包含/，nginx这样的写法永远无法匹配。

这些校验逻辑会输出 warning 而非直接报错，帮助你在配置阶段尽早发现模式书写错误。

2.2.2keyless：Cosign 无密钥验证

ImageKeylessVerifierV1Alpha1使用 Cosign keyless 验证方式，即基于 OIDC 身份（Fulcio 签发的短期证书 + Rekor 透明日志）进行签名验证，无需预置公钥。字段如下（见 pkg/machinery/config/types/security/image_verification.go）：

subject与subjectRegex二选一即可；官方示例：

issuer: https://accounts.google.com

issuer: https://token.actions.githubusercontent.com

subjectRegex: .*@example\.com

2.2.3publicKey：静态公钥验证

ImagePublicKeyVerifierV1Alpha1使用静态公钥（公钥证书）进行签名验证，适合无法使用 keyless 流程（如离线环境）或需要固定信任某签名主体的场景。字段如下（见 pkg/machinery/config/types/security/image_verification.go）：

示例：

publicKey: certificate: |- -----BEGIN CERTIFICATE----- MII--Sample Value-- -----END CERTIFICATE-----

2.3 规则的组合约束与校验逻辑

Validate()对每条规则施加了严格的组合约束（见 pkg/machinery/config/types/security/image_verification.go）：

• imagePattern必填：每条规则必须指定image模式，否则报错；
• skip与deny不能同时为 true；
• skip/deny与验证器互斥：如果skip或deny为 true，则不能再配置keyless或publicKey验证器；
• 至少一个验证器：既不是 skip 也不是 deny 的规则，必须配置至少一个验证器；
• keyless 与 publicKey 二选一：同一条规则不能同时配置keyless与publicKey；
• keyless 细节：issuer必填；subject与subjectRegex至少填一个；
• publicKey 细节：certificate必填。

这些规则通过errors.Join聚合，一个配置文件中多处错误会一并返回。

2.4 从配置到运行时资源：控制器消费链路

ImageVerificationConfig并不是停留在配置层面的声明。在 machined 中，security.ImageVerificationConfigController持续监听生效中的机器配置（configres.MachineConfigType/ActiveID），并把文档中的每条规则转换为security.ImageVerificationRule资源（见 internal/app/machined/pkg/controllers/security/image_verification_config.go）：

• 每条规则以%04d序号（如0000、0001）作为资源 ID 写入，顺序即规则在文档中的顺序；
• 写入时通过imageref.NormalizePattern()将镜像模式归一化后存储，因此执行talosctl get imageverificationrules时看到的正是实际被匹配的模式形态；
• skip、deny、keyless（issuer/subject/subjectRegex）与publicKey（certificate）字段被逐一映射进资源 spec。

该控制器对应的单元测试位于 internal/app/machined/pkg/controllers/security/image_verification_config_test.go，集成层面在 internal/integration/api/images.go 中有覆盖，读者可借此验证行为。

2.5 典型使用场景

• 供应链安全（registry 白名单 + 签名验证）：对官方镜像仓库使用 keyless 验证（如registry.k8s.io/*匹配 Kubernetes 官方发布签名），对内网私有仓库使用静态公钥验证；
• 镜像源管控：对开发用的本地仓库（如localhost:3000/*）直接deny: true拒绝拉取，防止生产节点使用非预期镜像源；
• 灰度放行：对暂不支持签名的镜像先用skip: true跳过验证，待签名补齐后再收紧策略。

三、TrustedRootsConfig：附加受信 CA 根

3.1 完整配置示例

TrustedRootsConfig允许为节点配置额外的受信 CA 根证书。完整 YAML 示例（与官方文档及源码中的exampleTrustedRootsConfigV1Alpha1()一致，见 pkg/machinery/config/types/security/trusted_roots.go）：

apiVersion: v1alpha1 kind: TrustedRootsConfig name: my-enterprise-ca # Name of the config document. certificates: | # List of additional trusted certificate authorities (as PEM-encoded certificates). -----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----

字段说明（见 pkg/machinery/config/types/security/trusted_roots.go）：

注意TrustedRootsConfig还实现了config.NamedDocument接口（见 pkg/machinery/config/types/security/trusted_roots.go），name字段在文档合并、去重等场景中充当文档标识。

3.2 证书注入的实现原理

ExtraTrustedRootCertificates()方法（见 pkg/machinery/config/types/security/trusted_roots.go）在返回证书内容时，会自动在证书串前面拼接一段以配置name为标题的头部（形如\nmy-enterprise-ca:\n==============），用于标识这批证书的来源。

真正把证书写入节点的消费方是TrustedRootsController（见 internal/app/machined/pkg/controllers/secrets/trusted_roots.go）：

1. 读取生效的机器配置，获取所有TrustedRoots()文档的ExtraTrustedRootCertificates()；
2. 以系统默认 CA 证书集合（defaultCACertificates）为基底，将附加证书用\n\n拼接在后面；
3. 将最终内容写入EtcFileSpec资源，落盘路径为常量DefaultTrustedRelativeCAFile，即ssl/certs/ca-certificates.crt（定义见 pkg/machinery/constants/constants.go），文件权限0o644。

也就是说，TrustedRootsConfig的效果等价于往系统 CA 信任链中追加 PEM 证书，使节点上基于该系统 CA 链的组件（如容器镜像拉取、apiserver 与 etcd 之间的 TLS 验证等）都能信任这些附加根。对应测试见 internal/app/machined/pkg/controllers/secrets/trusted_roots_test.go 与 pkg/machinery/config/types/security/trusted_roots_test.go。

3.3 典型使用场景

• 企业私有 CA：节点需要信任公司内部签发 TLS 证书的 CA，才能与内部镜像仓库、API 网关等正常建立 TLS 连接；
• 离线/内网环境：自建 CA 签发的 registry 证书、etcd 证书等，通过TrustedRootsConfig统一注入，避免逐台节点手工操作。

四、两类配置文档的使用方式

在 Talos Linux 中，ImageVerificationConfig与TrustedRootsConfig都是独立的配置文档，可以作为机器配置的一部分直接写入，或通过talosctl machineconfig相关流程与主配置合并。需要注意的是：

• 文档apiVersion均为v1alpha1，kind分别为ImageVerificationConfig与TrustedRootsConfig；
• 两个文档类型都通过registry.Register注册（见 pkg/machinery/config/types/security/image_verification.go 与 pkg/machinery/config/types/security/trusted_roots.go），因此可与标准机器配置一同被解析；
• 配置下发后，分别由上文所述的两个 COSI 控制器实时消费，配置变更会即时反映到镜像验证规则与系统 CA 信任链中，无需重启节点。

对于镜像验证规则的落地形态，可以执行talosctl get imageverificationrules查看控制器生成的规则资源，其展示的模式即为归一化后的实际匹配模式（见 internal/app/machined/pkg/controllers/security/image_verification_config.go），方便你核对配置是否按预期生效。

五、小结

security配置文档族为 Talos Linux 提供了两块关键的安全能力：

1. 镜像签名验证（ImageVerificationConfig）：基于 Cosign keyless（OIDC 身份）或静态公钥证书对镜像签名进行验证，支持按镜像模式 skip/deny 组合策略，为镜像供应链安全提供第一道防线；
2. 受信根配置（TrustedRootsConfig）：以声明式方式向节点追加 PEM 格式的 CA 根证书，最终写入系统 CA 信任链文件ssl/certs/ca-certificates.crt，让企业私有 CA 与内网 TLS 场景开箱即用。

两份文档的完整字段参考可继续查阅 ImageVerificationConfig 参考文档 与 TrustedRootsConfig 参考文档；更深层的类型定义与校验逻辑见 pkg/machinery/config/types/security/，运行时消费逻辑见 internal/app/machined/pkg/controllers/security/ 与 internal/app/machined/pkg/controllers/secrets/。

• 云原生
• 操作系统
• 容器编排