Skip to content

Commit 98643e0

Browse files
k8s-ci-robotk8s-ci-robot
authored
Merge pull request #9150 from killianmuldoon/pr-add-ownerRef-guide
📖 Add a guide describing ownerReference usage in CAPI
2 parents 253c487 + 6bd6c6b commit 98643e0

File tree

3 files changed

+93
-0
lines changed

3 files changed

+93
-0
lines changed

‎docs/book/src/SUMMARY.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -117,3 +117,4 @@
117117
- [Code Review in Cluster API](./REVIEWING.md)
118118
- [Version Support](./reference/versions.md)
119119
- [Supported Labels and Annotations](./reference/labels_and_annotations.md)
120+
- [Owner References](./reference/owner_references.md)

‎docs/book/src/reference/owner_references.md

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
# Owner References
2+
3+
4+
Cluster API uses [Kubernetes owner references](https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/) to track relationships between objects. These references are used for Kubernetes garbage collection, which is the basis of Cluster deletion in CAPI. They are also used places where the ownership hierarchy is important, for example when using `clusterctl move`.
5+
6+
CAPI uses owner references in an opinionated way. The following guidelines should be considered:
7+
1. Objects should always be created with an owner reference to prevent leaking objects. Initial ownerReferences can be replaced later where another object is a more appropriate owner.
8+
2. Owner references should be re-reconciled if they are lost for an object. This is required as some tools - e.g. velero - may delete owner references on objects.
9+
3. Owner references should be kept to the most recent apiVersion.
10+
- This ensures garbage collection still works after an old apiVersion is no longer served.
11+
4. Owner references should not be added unless required.
12+
- Multiple owner references on a single object should be exceptional.
13+
14+
15+
16+
17+
## Owner reference relationships in Cluster API
18+
19+
The below tables map out the a reference for ownership relationships for the objects in a Cluster API cluster.
20+
Providers may implement their own ownership relationships which may or may not map directly to the below tables.
21+
These owner references are almost all tested in an [end-to-end test](https://github.com/kubernetes-sigs/cluster-api/blob/caaa74482b51fae777334cd7a29595da1c06481e/test/e2e/quick_start_test.go#L31). Lack of testing is noted where this is not the case. CAPI Providers can take advantage of the e2e test framework to ensure their owner references are predictable, documented and stable.
22+
23+
Kubernetes core types
24+
25+
| type | Owner | Note |
26+
|-----------|---------------------|------------------------------------------|
27+
| Secret | KubeadmControlPlane | For cluster certificates |
28+
| Secret | KubeadmConfig | For bootstrap secrets |
29+
| Secret | ClusterResourceSet | When created by CRS. Not covered in e2e. |
30+
| ConfigMap | ClusterResourceSet | When created by CRS |
31+
32+
## Core types
33+
34+
| type | Owner | Note |
35+
|---------------------|---------------------|----------------------------|
36+
| ExtensionConfig | None | |
37+
| ClusterClass | None | |
38+
| Cluster | None | |
39+
| MachineDeployments | Cluster | |
40+
| MachineSet | MachineDeployment | |
41+
| Machine | MachineSet | When created by MachineSet |
42+
| Machine | KubeadmControlPlane | When created by KCP |
43+
| MachineHealthChecks | Cluster | |
44+
45+
46+
47+
## Experimental types
48+
| type | Owner | Note |
49+
|----------------------------|--------------------|------|
50+
| ClusterResourcesSet | None | |
51+
| ClusterResourcesSetBinding | ClusterResourceSet | |
52+
| MachinePool | Cluster | |
53+
54+
55+
## KubeadmControlPlane types
56+
| type | Owner | Note |
57+
|-----------------------------|--------------|------|
58+
| KubeadmControlPlane | Cluster | |
59+
| KubeadmControlPlaneTemplate | ClusterClass | |
60+
61+
62+
## Kubeadm bootstrap types
63+
| type | Owner | Note |
64+
|-----------------------|--------------|-------------------------------------------|
65+
| KubeadmConfig | Machine | When created for Machine |
66+
| KubeadmConfig | MachinePool | When created for MachinePool |
67+
| KubeadmConfigTemplate | Cluster | When referenced in MachineDeployment spec |
68+
| KubeadmConfigTemplate | ClusterClass | When referenced in ClusterClass |
69+
70+
## Infrastructure provider types
71+
| type | Owner | Note |
72+
|-------------------------------|--------------|---------------------------------------------|
73+
| InfrastructureMachine | Machine | |
74+
| InfrastructureMachineTemplate | Cluster | When created by cluster topology controller |
75+
| InfrastructureMachineTemplate | ClusterClass | When referenced in a ClusterClass |
76+
| InfrastructureCluster | Cluster | |
77+
| InfrastructureClusterTemplate | ClusterClass | |
78+
| InfrastructureMachinePool | MachinePool | |
79+
80+

‎test/framework/ownerreference_helpers.go

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -118,6 +118,8 @@ var (
118118

119119
// CoreOwnerReferenceAssertion maps Cluster API core types to functions which return an error if the passed
120120
// OwnerReferences aren't as expected.
121+
// Note: These relationships are documented in https://github.com/kubernetes-sigs/cluster-api/tree/main/docs/book/src/reference/owner_references.md.
122+
// That document should be updated if these references change.
121123
var CoreOwnerReferenceAssertion = map[string]func([]metav1.OwnerReference) error{
122124
extensionConfigKind: func(owners []metav1.OwnerReference) error {
123125
// ExtensionConfig should have no owners.
@@ -161,6 +163,8 @@ var (
161163

162164
// ExpOwnerReferenceAssertions maps experimental types to functions which return an error if the passed OwnerReferences
163165
// aren't as expected.
166+
// Note: These relationships are documented in https://github.com/kubernetes-sigs/cluster-api/tree/main/docs/book/src/reference/owner_references.md.
167+
// That document should be updated if these references change.
164168
var ExpOwnerReferenceAssertions = map[string]func([]metav1.OwnerReference) error{
165169
clusterResourceSetKind: func(owners []metav1.OwnerReference) error {
166170
// ClusterResourcesSet doesn't have ownerReferences (it is a clusterctl move-hierarchy root).
@@ -184,6 +188,8 @@ var (
184188

185189
// KubernetesReferenceAssertions maps Kubernetes types to functions which return an error if the passed OwnerReferences
186190
// aren't as expected.
191+
// Note: These relationships are documented in https://github.com/kubernetes-sigs/cluster-api/tree/main/docs/book/src/reference/owner_references.md.
192+
// That document should be updated if these references change.
187193
var KubernetesReferenceAssertions = map[string]func([]metav1.OwnerReference) error{
188194
secretKind: func(owners []metav1.OwnerReference) error {
189195
// Secrets for cluster certificates must be owned by the KubeadmControlPlane. The bootstrap secret should be owned by a KubeadmControlPlane.
@@ -205,6 +211,8 @@ var (
205211

206212
// KubeadmControlPlaneOwnerReferenceAssertions maps Kubeadm control plane types to functions which return an error if the passed
207213
// OwnerReferences aren't as expected.
214+
// Note: These relationships are documented in https://github.com/kubernetes-sigs/cluster-api/tree/main/docs/book/src/reference/owner_references.md.
215+
// That document should be updated if these references change.
208216
var KubeadmControlPlaneOwnerReferenceAssertions = map[string]func([]metav1.OwnerReference) error{
209217
kubeadmControlPlaneKind: func(owners []metav1.OwnerReference) error {
210218
// The KubeadmControlPlane must be owned by a Cluster.
@@ -226,6 +234,8 @@ var (
226234

227235
// KubeadmBootstrapOwnerReferenceAssertions maps KubeadmBootstrap types to functions which return an error if the passed OwnerReferences
228236
// aren't as expected.
237+
// Note: These relationships are documented in https://github.com/kubernetes-sigs/cluster-api/tree/main/docs/book/src/reference/owner_references.md.
238+
// That document should be updated if these references change.
229239
var KubeadmBootstrapOwnerReferenceAssertions = map[string]func([]metav1.OwnerReference) error{
230240
kubeadmConfigKind: func(owners []metav1.OwnerReference) error {
231241
// The KubeadmConfig must be owned by a Cluster or by a MachinePool.
@@ -248,6 +258,8 @@ var (
248258

249259
// DockerInfraOwnerReferenceAssertions maps Docker Infrastructure types to functions which return an error if the passed
250260
// OwnerReferences aren't as expected.
261+
// Note: These relationships are documented in https://github.com/kubernetes-sigs/cluster-api/tree/main/docs/book/src/reference/owner_references.md.
262+
// That document should be updated if these references change.
251263
var DockerInfraOwnerReferenceAssertions = map[string]func([]metav1.OwnerReference) error{
252264
dockerMachineKind: func(owners []metav1.OwnerReference) error {
253265
// The DockerMachine must be owned by a Machine.

0 commit comments

Comments
 (0)