Skip to main content
Think of owner references as the family tree Kubernetes uses to automatically clean up related resources. Imagine a parent WebApp named site with three children: a Deployment named site, a Service named site, and a ConfigMap named site-config. Each child points back to the parent. What happens if you delete the parent?
If the children aren’t linked to the parent, they remain in the cluster as orphaned resources. Orphans continue to occupy names, Service endpoints, and configuration even though the WebApp that depended on them no longer exists.
The image depicts orphaned objects from a WebApp, labeled as "site" and "site-config," all marked as "Orphaned." It indicates they are still consuming resources without an explanation.
Kubernetes owner references solve this cleanup problem. An owner reference is metadata on a child object that points back to its parent resource. In this example, the parent is the WebApp and the children are the Deployment, Service, and ConfigMap. The key detail: the reference points to the parent’s UID, not only its name. A UID is Kubernetes’ unique identity for an object, so using the UID ensures the cluster can distinguish two objects that share a name but are different instances. Example owner reference snippet:
Because the UID is unique, deleting a WebApp and later creating another WebApp with the same name will not confuse the garbage collector—the UIDs differ, so Kubernetes treats them as distinct objects. In the Go operator world, the common helper is controllerutil.SetControllerReference from the controller-runtime project. You pass the parent object (the WebApp), the child object you will create, and the controller Scheme (the registry that maps Go types to Kubernetes API kinds). Call the helper before creating the child so the owner reference is set at creation time:
When the WebApp is deleted, Kubernetes garbage collection can automatically remove owned children. This means you usually do not need to write manual delete logic for simple child resources—the cluster garbage collector handles cleanup when owner references are set correctly. Example deletion flow:
When the controller is configured to watch owned Deployments, Services, and ConfigMaps, controller-runtime will receive events for those children and enqueue the parent WebApp for reconciliation when changes occur.
The image illustrates a process where a controller watches for changes in owned children, such as Deployment, Service, and ConfigMap, and re-queues the parent when a change is detected.
This gives your reconciler another chance to repair missing or modified children during subsequent reconciliation loops. Best practices summary
Set the controller reference for every child the WebApp creates before you call the API to create that child. This avoids orphaned resources and makes ownership visible with kubectl inspection.
Owner references have important constraints: owners and dependents must be in the same namespace unless the owner is cluster-scoped. Also, be cautious when setting ownerReferences for resources created by users outside the operator—you may unintentionally enable deletion of user-managed objects.
For this lesson, follow this simple rule: every child the WebApp creates should get a controller reference to the WebApp before creation. Doing so prevents orphaned resources, enables automatic garbage collection, and integrates child-change events into the parent’s reconciliation lifecycle.
The image provides a rule for setting a controller reference for every child created by a web application before it gets created to prevent orphaned resources.
Links and references

Watch Video

Practice Lab