From 8d96fcb42354b6cd70594f828ae4af7c4881a04b Mon Sep 17 00:00:00 2001
From: Jordan Liggitt <liggitt@google.com>
Date: Tue, 17 Nov 2020 17:38:06 -0500
Subject: [PATCH] Update GC cross-namespace note

---
 .../controllers/garbage-collection.md         | 21 ++++++++++++++-----
 1 file changed, 16 insertions(+), 5 deletions(-)

diff --git a/content/en/docs/concepts/workloads/controllers/garbage-collection.md b/content/en/docs/concepts/workloads/controllers/garbage-collection.md
index 93a3c912fb..0e9b4f746a 100644
--- a/content/en/docs/concepts/workloads/controllers/garbage-collection.md
+++ b/content/en/docs/concepts/workloads/controllers/garbage-collection.md
@@ -59,11 +59,22 @@ metadata:
 ```
 
 {{< note >}}
-Cross-namespace owner references are disallowed by design. This means:
-1) Namespace-scoped dependents can only specify owners in the same namespace,
-and owners that are cluster-scoped.
-2) Cluster-scoped dependents can only specify cluster-scoped owners, but not
-namespace-scoped owners.
+Cross-namespace owner references are disallowed by design.
+
+Namespaced dependents can specify cluster-scoped or namespaced owners.
+A namespaced owner **must** exist in the same namespace as the dependent.
+If it does not, the owner reference is treated as absent, and the dependent
+is subject to deletion once all owners are verified absent.
+
+Cluster-scoped dependents can only specify cluster-scoped owners.
+In v1.20+, if a cluster-scoped dependent specifies a namespaced kind as an owner,
+it is treated as having an unresolveable owner reference, and is not able to be garbage collected.
+
+In v1.20+, if the garbage collector detects an invalid cross-namespace `ownerReference`,
+or a cluster-scoped dependent with an `ownerReference` referencing a namespaced kind, a warning Event 
+with a reason of `OwnerRefInvalidNamespace` and an `involvedObject` of the invalid dependent is reported.
+You can check for that kind of Event by running
+`kubectl get events -A --field-selector=reason=OwnerRefInvalidNamespace`.
 {{< /note >}}
 
 ## Controlling how the garbage collector deletes dependents