When exactly do I set an ownerReference's controller field to true?

Question

I am writing a Kubernetes controller.

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

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

ownerReferences:
- kind: <kind from custom resource>
  apiVersion: <apiVersion from custom resource>
  uid: <uid from custom resource>
  controller: <???>

I'm unclear on whether this is case where I would set controller to true.

The Kubernetes reference documentation says (in its entirety):

If true, this reference points to the managing controller.

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

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

Is that correct?

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

Answer 1

ownerReferences has two purposes:

• Garbage collection: Refer to the answer of ymmt2005. Essentially all owners are considered for GC. Contrary to the accepted answer the controller field has no impact on GC.
• Adoption: The controller 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 controller to true. If a resource already has a controller it will not be adopted by another controller. Details are in the design proposal.

TLDR: The field controller is only used for adoption and not GC.

Answer 2

According to the source code of Kubernetes, the object will be garbage collected only after all objects in ownerReferences field are deleted.

https://github.com/kubernetes/apimachinery/blob/15d95c0b2af3f4fcf46dce24105e5fbb9379af5a/pkg/apis/meta/v1/types.go#L240-L247

// List of objects depended by this object. If ALL objects in the list have
// been deleted, this object will be garbage collected. If this object is managed by a controller,
// then an entry in this list will point to this controller, with the controller field set to true.
// There cannot be more than one managing controller.