trust-manager 正在迁移到 ClusterBundle

trust-manager 方面分享了一个关于项目即将发生的重要变化的详细信息。

• trust-manager 即将把当前的 Bundle 资源功能，迁移到一个新的 ClusterBundle 资源。
• 你需要将 Bundle 的 YAML 替换成 ClusterBundle YAML，规格类似但有所不同。
• 未来，Bundle 可能会以命名空间范围的 CRD 形式重新出现。

当前状态

trust-manager 目前使用 Bundle 资源，作为集群管理员在集群中分发证书颁发机构（CA）证书的机制。这个 CRD 是集群级别的，从集群中心命名空间中获取数据源，然后同步到其他命名空间的目标。

> kubectl api-resources
NAME                                SHORTNAMES              APIVERSION                                NAMESPACED   KIND
bundles                                                     trust.cert-manager.io/v1alpha1            false        Bundle

如果你熟悉其姊妹项目 cert-manager，可能会预期看到 ClusterBundle，因为 Issuer 是命名空间范围的，而 ClusterIssuer 是集群范围的。

NAME                                SHORTNAMES              APIVERSION                                NAMESPACED   KIND
clusterissuers                      ciss                    cert-manager.io/v1                        false        ClusterIssuer
issuers                             iss                     cert-manager.io/v1                        true         Issuer

trust-manager 目前没有遵循以 Cluster 前缀表示集群级别 CRD 的模式。对于新用户来说可能有些困惑，或者感觉有些不一致。

变化内容

简单来说，trust-manager 默认将切换为使用 ClusterBundle。这更准确地反映了当前 Bundle 资源的范围。同时这也更贴近 Kubernetes 原生的 ClusterTrustBundle 资源，它也是集群级别资源。

对 trust-manager 用户的影响：

1. 弃用并最终移除 Bundle 资源及其 API 组 trust.cert-manager.io/v1alpha1。

2. 在新的 API 组 trust-manager.io/v1alpha2 中创建 ClusterBundle，作为新的默认资源。

安装 trust-manager 后，查看 api-resources 会看到类似：

> kubectl api-resources
NAME                                SHORTNAMES              APIVERSION                                NAMESPACED   KIND
clusterbundles                                              trust-manager.io/v1alpha2                 false        ClusterBundle

最简示例

对于简单场景，比如只使用公共 CA，改动很小。如果你当前有：

apiVersion: trust.cert-manager.io/v1alpha1
kind:Bundle
metadata:
name:public-ca-certs
spec:
sources:
-useDefaultCAs:true
target:
    configMap:
      key:ca-certificates.crt

现在改成：

apiVersion: trust-manager.io/v1alpha2
kind:ClusterBundle
metadata:
name:public-ca-certs
spec:
includeDefaultCAs:true
target:
    configMap:
      data:
      -key:ca-certificates.crt
    namespaceSelector:
      matchLabels:{}

注意，发布前规格可能会有变动！如果有任何调整建议，可联系 cert-manager 维护者。

如果想提前了解资源规格，可以在测试或开发集群中应用 CRD，并用 kubectl explain 查看配置选项。

kubectl apply -f https://raw.githubusercontent.com/cert-manager/trust-manager/refs/heads/main/deploy/crds/trust-manager.io_clusterbundles.yaml
kubectl explain clusterbundles.trust-manager.io.spec

别忘了清理测试资源，因为此资源尚未正式发布

kubectl delete -f https://raw.githubusercontent.com/cert-manager/trust-manager/refs/heads/main/deploy/crds/trust-manager.io_clusterbundles.yaml

API 变更

主要有两个关键点：

1. API 组由 trust.cert-manager.io 变更为 trust-manager.io。

2. API 版本由 v1alpha1 升级为 v1alpha2。

API 组的变更，一方面缩短了整体 URL，另一方面体现了 trust-manager 正在成为一个完全独立于 cert-manager 的项目。虽然两个项目都由同一组优秀维护者负责，但官方认为项目应能独立存在，减少集群中的工具依赖。实现独立性的关键之一是移除 webhook 依赖，不再需要证书来保护 webhook 通信。Kubernetes 在 Server Side Apply (SSA) 和 Common Expression Language (CEL) 的进步，让资源验证能更方便地由 Kubernetes 组件完成，无需依赖 webhook 服务。目前还没达到完全独立的状态，未来会有专门讨论此话题的文章。

API 版本的变更也很重要：资源仍处于 alpha 阶段。这意味着规格依然可能发生不兼容的变动。但实际上，维护者会非常谨慎对待规格更改

对你的影响

资源迁移将由一个新的转换控制器辅助完成。注意，这不是 webhook 转换，因为 webhook 转换只能在同一 API 组的不同版本间转换。

管理员需要做两件事：

1. 随着新版本发布，升级 trust-manager。

2. 更新部署清单，将 Bundle 资源替换为新的 ClusterBundle 规范。

官方会在新资源发布时提供详细的操作指南。

时间表

官方目前还不能给出具体时间点，但可以大致说明：

1. 版本 N：发布新的 ClusterBundle CRD，并弃用 Bundle。
2. 版本 N+X：移除 Bundle 资源。

未来展望

这只是目前的设想，trust-manager 在 ClusterBundle 之后可能会包括：

• 新的 trust-manager.io/v1alpha2 Bundle 资源回归，命名空间范围的。
• 为 ClusterBundle 增加更多目标资源类型。