Controller Runtime Bytes #1 (Ownership)

This is a series of mini blogs for documenting some of the controller runtime features.

In Kubernetes, some objects are owner of other objects. For example, a ReplicaSet is the owner of a set of Pods. These owned objects are dependents of their owners. The dependents objects has references to all owners objects under metadata.ownerReferences field. Read more about owners and dependents

A kubernetes custom resources can set itself as owner of the other resources, it creates as part of it’s reconciliation logic. controller-runtime has two utility methods to set owner references on an object.

• func SetControllerReference(owner, controlled metav1.Object, scheme *runtime.Scheme, ...) error

SetControllerReference sets owner as a Controller OwnerReference on controlled. This is used for garbage collection of the controlled object and for reconciling the owner object on changes to controlled (with a Watch + EnqueueRequestForOwner). Since only one OwnerReference can be a controller, it returns an error if there is another OwnerReference with Controller flag set.

• func SetOwnerReference(owner, object metav1.Object, scheme *runtime.Scheme, ...) error

SetOwnerReference is a helper method to make sure the given object contains an object references to the object provided. This allows you to declare that owner has a dependency on the object without specifying it as a controller.

When you need to declare a dependency on an object without reconciling changes from the owner when the dependent changes, use SetOwnerReference. If you need to reconcile the owner for changes in the dependent object or to garbage collect the dependent when the owner is deleted, use SetControllerReference.

To establish controller ownership on a Deployment object created by the custom resource MyCustomApp

// Set the controller ownerRef for the Deployment
myApp := MyCustomApp{...}
if err := ctrl.SetControllerReference(myApp, dep, r.Scheme); err != nil {
    return nil, err
}

Setting the controller owner reference will automatically manage the garbage collection of the dependent resources, but it won’t trigger reconciliation of the owner object when the dependent resources change. To observe the changes on the dependent resource, we need add Owns when setting up conrtoller with the controller manager.

// SetupWithManager sets up the controller with the Manager.
// Note that the Deployment will be also watched in order to ensure its
// desirable state on the cluster
func (r *MemcachedReconciler) SetupWithManager(mgr ctrl.Manager) error {
    return ctrl.NewControllerManagedBy(mgr).
    For(&examplecomv1alpha1.MyCustomApp{}). ## Create watches for the MyCustomApp Kind
    Owns(&appsv1.Deployment{}). ## Create watches for the Deployment which has its controller owned reference
    Complete(r)
}