<p>I am writing a Kubernetes controller.</p>

<p>Someone creates a custom resource via <code>kubectl apply -f custom-resource.yaml</code>.  My controller notices the creation, and then creates a <code>Deployment</code> that pertains to the custom resource in some way.</p>

<p>I am looking for the proper way to set up the <code>Deployment</code>'s <code>ownerReferences</code> field such that a deletion of the custom resource will result in a deletion of the <code>Deployment</code>.  I understand I can do this like so:</p>

<pre><code>ownerReferences:
- kind: &lt;kind from custom resource&gt;
  apiVersion: &lt;apiVersion from custom resource&gt;
  uid: &lt;uid from custom resource&gt;
  controller: &lt;???&gt;
</code></pre>

<p>I'm unclear on whether this is case where I would set <code>controller</code> to <code>true</code>.</p>

<p>The Kubernetes reference documentation says (in its entirety):</p>

<blockquote>
  <p>If true, this reference points to the managing controller.</p>
</blockquote>

<p>Given that a controller is running code, and an owner reference actually references another Kubernetes resource via matching <code>uid</code>, <code>name</code>, <code>kind</code> and <code>apiVersion</code> fields, this statement is nonsensical: a Kubernetes object reference can't "point to" code.</p>

<p>I have a sense that the documentation author is trying to indicate that&mdash;using my example&mdash;because the user didn't directly create the <code>Deployment</code> herself, it should be marked with some kind of flag indicating that a controller created it instead.</p>

<p>Is that correct?</p>

<p>The follow on question here is of course: OK, what behavior changes if <code>controller</code> is set to <code>false</code> here, but the other <code>ownerReference</code> fields are set as above?</p>

<p><code>ownerReferences</code> has two purposes:</p>
<ul>
<li><strong>Garbage collection</strong>: Refer to the answer of <a href="https://stackoverflow.com/a/61673465/1863595">ymmt2005</a>. Essentially all owners are considered for GC. Contrary to the <a href="https://stackoverflow.com/a/51176204/1863595">accepted answer</a> the <code>controller</code> field has no impact on GC.</li>
<li><strong>Adoption</strong>: The <code>controller</code> field prevents fighting over resources which are to be adopted. Consider a replica set. Usually, the replica set controller creates the pods. However, if there is a pod which matches the label selector it will be adopted by the replica set. To prevent two replica sets fighting over the same pod, the latter is given a unique controller by setting the <code>controller</code> to <code>true</code>. If a resource already has a controller it will not be adopted by another controller. Details are in the <a href="https://github.com/kubernetes/design-proposals-archive/blob/acc25e14ca83dfda4f66d8cb1f1b491f26e78ffe/api-machinery/controller-ref.md" rel="nofollow noreferrer">design proposal</a>.</li>
</ul>
<p><strong>TLDR</strong>: The field <code>controller</code> is only used for adoption and not GC.</p>
