Skip to content

Commit 64f91d8

Browse files
committed
add note on owner references in garbage collection page
add note on owner references to owner dependents page
1 parent dd2f06f commit 64f91d8

File tree

2 files changed

+36
-0
lines changed

2 files changed

+36
-0
lines changed

content/en/docs/concepts/architecture/garbage-collection.md

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,24 @@ to the labels, each `EndpointSlice` that is managed on behalf of a Service has
3737
an owner reference. Owner references help different parts of Kubernetes avoid
3838
interfering with objects they don’t control.
3939

40+
{{< note >}}
41+
Cross-namespace owner references are disallowed by design.
42+
Namespaced dependents can specify cluster-scoped or namespaced owners.
43+
A namespaced owner **must** exist in the same namespace as the dependent.
44+
If it does not, the owner reference is treated as absent, and the dependent
45+
is subject to deletion once all owners are verified absent.
46+
47+
Cluster-scoped dependents can only specify cluster-scoped owners.
48+
In v1.20+, if a cluster-scoped dependent specifies a namespaced kind as an owner,
49+
it is treated as having an unresolvable owner reference, and is not able to be garbage collected.
50+
51+
In v1.20+, if the garbage collector detects an invalid cross-namespace `ownerReference`,
52+
or a cluster-scoped dependent with an `ownerReference` referencing a namespaced kind, a warning Event
53+
with a reason of `OwnerRefInvalidNamespace` and an `involvedObject` of the invalid dependent is reported.
54+
You can check for that kind of Event by running
55+
`kubectl get events -A --field-selector=reason=OwnerRefInvalidNamespace`.
56+
{{< /note >}}
57+
4058
## Cascading deletion {#cascading-deletion}
4159

4260
Kubernetes checks for and deletes objects that no longer have owner

content/en/docs/concepts/overview/working-with-objects/owners-dependents.md

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,24 @@ A Kubernetes admission controller controls user access to change this field for
4242
dependent resources, based on the delete permissions of the owner. This control
4343
prevents unauthorized users from delaying owner object deletion.
4444

45+
{{< note >}}
46+
Cross-namespace owner references are disallowed by design.
47+
Namespaced dependents can specify cluster-scoped or namespaced owners.
48+
A namespaced owner **must** exist in the same namespace as the dependent.
49+
If it does not, the owner reference is treated as absent, and the dependent
50+
is subject to deletion once all owners are verified absent.
51+
52+
Cluster-scoped dependents can only specify cluster-scoped owners.
53+
In v1.20+, if a cluster-scoped dependent specifies a namespaced kind as an owner,
54+
it is treated as having an unresolvable owner reference, and is not able to be garbage collected.
55+
56+
In v1.20+, if the garbage collector detects an invalid cross-namespace `ownerReference`,
57+
or a cluster-scoped dependent with an `ownerReference` referencing a namespaced kind, a warning Event
58+
with a reason of `OwnerRefInvalidNamespace` and an `involvedObject` of the invalid dependent is reported.
59+
You can check for that kind of Event by running
60+
`kubectl get events -A --field-selector=reason=OwnerRefInvalidNamespace`.
61+
{{< /note >}}
62+
4563
## Ownership and finalizers
4664

4765
When you tell Kubernetes to delete a resource, the API server allows the

0 commit comments

Comments
 (0)