Skip to content

Commit acc510d

Browse files
cert-manager-prow[bot]cert-manager-prow[bot]
authored
Merge pull request #1745 from hawksight/clusterbundle-future
trust-manager announcement blog clusterbundles future state
2 parents 33107bf + fc196d2 commit acc510d

File tree

1 file changed

+190
-0
lines changed

1 file changed

+190
-0
lines changed

‎content/announcements/2025-09-05-trust-manager-clusterbundle.md‎

Lines changed: 190 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,190 @@
1+
---
2+
slug: trust-manager-clusterbundle-future
3+
title: trust-manager is moving the ClusterBundle
4+
description: A look at how trust-manager is moving to ClusterBundle and the impact for you
5+
date: "2025-09-05T12:00:00Z"
6+
---
7+
8+
We would like to share details about a major upcoming change to [trust-manager](github.com/cert-manager/trust-manager).
9+
10+
## TL;DR
11+
12+
- trust-manager will move its current functionality from the `Bundle` resource to a new `ClusterBundle` resource.
13+
- You will need to replace `Bundle` YAML with `ClusterBundle` YAML, which will have a similar but different specification.
14+
- In the future, `Bundle` may return as a namespace-scoped CRD.
15+
16+
## Current State
17+
18+
trust-manager is currently using a `Bundle` resource as the mechanism for cluster administrators to distribute Certificate Authority (CA) certificates within their clusters.
19+
This CRD is scoped at the cluster level and takes in `sources` from a central cluster namespace and then distributes to `targets` in other namespaces.
20+
21+
```sh
22+
> kubectl api-resources
23+
NAME SHORTNAMES APIVERSION NAMESPACED KIND
24+
bundles trust.cert-manager.io/v1alpha1 false Bundle
25+
```
26+
27+
If you are familiar with the sister project cert-manager you might well expect to see a `ClusterBundle`, based on the existing usage of `Issuer` being namespaced and `ClusterIssuer` being cluster-scoped.
28+
29+
```sh
30+
NAME SHORTNAMES APIVERSION NAMESPACED KIND
31+
clusterissuers ciss cert-manager.io/v1 false ClusterIssuer
32+
issuers iss cert-manager.io/v1 true Issuer
33+
```
34+
35+
trust-manager does not currently follow that pattern of cluster level CRDs being prefixed by `Cluster`.
36+
This may be confusing to new trust-manager users or at least feels a little inconsistent.
37+
38+
## What's Changing
39+
40+
Simply put, trust-manager is moving to using a `ClusterBundle` by default.
41+
This more accurately reflects the scope of the current `Bundle` resource.
42+
This more closely ties with the Kubernetes native `ClusterTrustBundle` resource, which also acts as a cluster-level resource.
43+
More details on this can be [found here](https://kubernetes.io/docs/reference/access-authn-authz/certificate-signing-requests/#cluster-trust-bundles).
44+
45+
For trust-manager users, this means:
46+
47+
1) Deprecating and ultimately removing the `Bundle` resource and the API group `trust.cert-manager.io/v1alpha1`.
48+
1) Creating `ClusterBundle` in the API group `trust-manager.io/v1alpha2` as the new default.
49+
50+
Checkout [API Changes](#api-changes) for more details on what this means.
51+
52+
Eventually, you will see something like this after installing trust-manager and listing `api-resource`:
53+
54+
```sh
55+
> kubectl api-resources
56+
NAME SHORTNAMES APIVERSION NAMESPACED KIND
57+
clusterbundles trust-manager.io/v1alpha2 false ClusterBundle
58+
```
59+
60+
### Minimal Example
61+
62+
For simpler setups, such as only public CAs, the change should be fairly minimal. So if you currently have:
63+
64+
```yaml
65+
apiVersion: trust.cert-manager.io/v1alpha1
66+
kind: Bundle
67+
metadata:
68+
name: public-ca-certs
69+
spec:
70+
sources:
71+
- useDefaultCAs: true
72+
target:
73+
configMap:
74+
key: ca-certificates.crt
75+
```
76+
77+
It would now look like:
78+
79+
```yaml
80+
apiVersion: trust-manager.io/v1alpha2
81+
kind: ClusterBundle
82+
metadata:
83+
name: public-ca-certs
84+
spec:
85+
includeDefaultCAs: true
86+
target:
87+
configMap:
88+
data:
89+
- key: ca-certificates.crt
90+
namespaceSelector:
91+
matchLabels: {}
92+
```
93+
94+
> ⚠️ Please note that the specification is subject to change before release!
95+
> If you have any suggestions for last-minute adjustments, please reach out to the cert-manager maintainers.
96+
> See [this section below](#how-to-jump-in) for details.
97+
98+
If you want to explore more of the resource specifications right now, you can apply the CRD in a lab or development cluster and use `kubectl explain` to see what configuration options are available.
99+
100+
```sh
101+
kubectl apply -f https://raw.githubusercontent.com/cert-manager/trust-manager/refs/heads/main/deploy/crds/trust-manager.io_clusterbundles.yaml
102+
kubectl explain clusterbundles.trust-manager.io.spec
103+
```
104+
105+
Don't forget to clean up, as the resource is not released!
106+
107+
```sh
108+
kubectl delete -f https://raw.githubusercontent.com/cert-manager/trust-manager/refs/heads/main/deploy/crds/trust-manager.io_clusterbundles.yaml
109+
```
110+
111+
### API Changes
112+
113+
In the API change, there are two key elements to consider:
114+
115+
1) The API group is changing from `trust.cert-manager.io` to `trust-manager.io`.
116+
1) The API version is going from `v1alpha1` to `v1alpha2`.
117+
118+
The changing of the group `trust.cert-manager.io` to `trust-manager.io` is a shortening of the overall URL, but also reflects the general move towards trust-manager being a completely independent project to cert-manager.
119+
While both projects are maintained by the same set of awesome maintainers, we fundamentally believe that one project should be able to exist without the other, reducing the overall tooling you might need in your cluster.
120+
A key part of making the projects independent is removing the need for webhooks, and therefore removing the certificates needed to secure that webhook communication.
121+
Kubernetes advances in [Server Side Apply](https://kubernetes.io/docs/reference/using-api/server-side-apply/) (SSA) and [Common Expression Language](https://kubernetes.io/docs/reference/using-api/cel/)e (CEL) make it much easier to perform resource validation with the Kubernetes components, without having to hand that off to a webhook service to do the resource validation.
122+
That's a different goal, and we are not at that state of independence right now.
123+
Look out for a future post exploring that topic.
124+
125+
The API version change has meaning worth considering too. It is still an `alpha` level resource!
126+
This means that the resource specification could still change in a backwards incompatible way if there was a need.
127+
In practice, we will likely be much safer and considerate of any specification change.
128+
Just look at the effort the maintainers have gone to with this change alone, for an alpha level resource.
129+
We all understand the frustration of things changing, especially when we work with so many CRDs from many different projects.
130+
That plays a big part in our mindset to try and make changes in a way that impact users as minimally as possible.
131+
132+
## Impact On You
133+
134+
The migration of resources from old to new will be assisted by a new conversion controller.
135+
136+
> ⚠️ Please note that this is not a webhook conversion, as a conversion webhook can only convert between different versions of the same API group.
137+
138+
This leaves two actions for administrators:
139+
140+
1) Upgrade trust-manager as we release new versions, but we know you already do this!
141+
1) Update your deployment manifests to replace the `Bundle` resources with the new `ClusterBundle` specification.
142+
143+
> ⚠️ We will provide detailed instructions as we release the new resource.
144+
145+
### Timeline
146+
147+
We are not yet in a position to give you specific dates of changes, but we can more generically give you an overview in terms of releases.
148+
149+
1. Release N - New CRD for `ClusterBundle` is released & `Bundle` is deprecated.
150+
1. Release N+X - `Bundle` resource is removed.
151+
152+
#### Future State
153+
154+
Take this with a pinch of salt, but the current vision for trust-manager after `ClusterBundle` might include:
155+
156+
- The return of a new `trust-manager.io/v1alpha2 Bundle` resource, which is namespace scoped.
157+
158+
## Getting Involved
159+
160+
cert-manager maintained projects are open to everyone as CNCF projects.
161+
We welcome all feedback and contributions on the proposed `ClusterBundle` API and to our projects more generally.
162+
163+
### Help Needed
164+
165+
If you have the time, there is still a lot of work to get us to the future state where `ClusterBundle` is the default.
166+
Things needed include, but are not limited to:
167+
168+
- Website documentation updates
169+
- Migration guidance
170+
- Reviewing Pull Requests (PRs) of the incremental changes
171+
- Helping to communicate the changes as they occur
172+
- Code contributions
173+
174+
### How to jump in
175+
176+
See our [website docs](../docs/contributing/README.md), or come join us on [slack](../docs/contributing/README.md#slack)!
177+
178+
### References
179+
180+
To find out more about this change and others, here are some starting points:
181+
182+
- [Design document for `ClusterBundle` name change](https://github.com/cert-manager/trust-manager/blob/main/design/20241124-rename-bunde-to-clusterbundle.md)
183+
- [A more technical implementation plan](https://github.com/cert-manager/trust-manager/issues/242)
184+
185+
### Credits
186+
187+
We would like to thank two maintainers in particular for their substantial contributions to `ClusterBundles`:
188+
189+
- Firstly [Erik](https://github.com/erikgb) for being the driving force and contributor behind this change.
190+
- And [Ashley](https://github.com/sgtcodfish) for reviewing, supporting, and being the main point of contact on all things trust-manager related.

0 commit comments

Comments
 (0)