前言

名词解释中已经解释了什么是Controller，那么ControllerRef就是对Controller的引用。在单进程编程中引用一般等同于指针(指针是对象的唯一标识)，但是分布式系统中引用一般是对象的唯一键，这个唯一键可能是多维度的（以K8S为例：NS、Name、Kind等）。ControllerRefManager从名词上理解就是管理对象的Controller引用，而本文的Controller指的是对象的父对象（Owner），所以ControllerRefManager用来管理对象的Onwer引用的。比如某个Pod的Owner是ReplicaSet，同时该ReplicaSet的Owner是一个Deployment，所以ControllerRefManager用来管理Pod的父对象ReplicaSet和ReplicaSet的父对象Deployment。

本文应用源码为kubernetes的release-1.21分支。

OwnerReference

现在我们来看看Kubernetes里对于Owner引用的定义，源码链接：https://github.com/kubernetes/apimachinery/blob/release-1.21/pkg/apis/meta/v1/types.go#L306

type OwnerReference struct {
    // 拥有者的API version，例如ReplicaSet对应的APIVersion可以是apps/v1
    APIVersion string `json:"apiVersion" protobuf:"bytes,5,opt,name=apiVersion"`
    // 拥有者的API Kind，复用上面的例子，Kind就是ReplicaSet
    Kind string `json:"kind" protobuf:"bytes,1,opt,name=kind"`
    // 拥有者的名字，复用上面的例子就是ReplicaSet的名字。
    // 有没有发现没有NS？这是为什么？不是NS/Name才是唯一键么？道理很简单，父对象和子对象在同一个NS下，所以没有NS。
    Name string `json:"name" protobuf:"bytes,3,opt,name=name"`
    // 拥有者的UID，复用上面的例子就是ReplicaSet的UID，对象删除又创建会造成NS/Name相同但UID不同
    UID types.UID `json:"uid" protobuf:"bytes,4,opt,name=uid,casttype=k8s.io/apimachinery/pkg/types.UID"`
    // 如果为true，表示拥有者是Controller类型，比如Deployment、ReplicaSet、Job等
    Controller *bool `json:"controller,omitempty" protobuf:"varint,6,opt,name=controller"`
    // 如果为true，并且拥有者通过foreground(例如kubectl delete xxx)删除时，只有该引用被删除时拥有者对象才能删除。
    BlockOwnerDeletion *bool `json:"blockOwnerDeletion,omitempty" protobuf:"varint,7,opt,name=blockOwnerDeletion"`
}

ControllerRefManager

BaseControllerRefManager

BaseControllerRefManager是XxxControllerRefManager的基类，此处Xxx就是需要设置拥有者的对象类型，比如Pod或者ReplicaSet(后文会有介绍)。源码链接: https://github.com/kubernetes/kubernetes/blob/release-1.20/pkg/controller/controller_ref_manager.go#L35。

type BaseControllerRefManager struct {
    // Controller(Owner)的meta
    Controller metav1.Object
    // Controller匹配子对象的Selector，很好理解，很为我们经常在yaml中写Label和Selector。
    Selector   labels.Selector

    // 判断是否可以接纳子对象的函数，函数由外部传入，并且只会调用一次，后面介绍PodControllerRefManager的时候会详细说明，此处先忽略。
    // 什么是接纳？这要从没有ControllerRef的对象说起，这些对象对于Controller来说是‘孤儿’，只要是XxxController创建的子对象都会设置ControllerRef。
    // 如果通过子对象的标签匹配选择器，就可以考虑是否接纳这个子对象，即为这个子对象设置ControllerRef。当然，接纳孤儿没有那么简单，后面会详细说明。
    // 笔者将adopt翻译为‘接纳’，寓意为本身不属于Controller的子对象，经过各种匹配后才会被接纳，即获得子对象的拥有权。
    canAdoptErr  error
    canAdoptOnce sync.Once
    CanAdoptFunc func() error
}

// CanAdopt()将canAdoptErr、canAdoptOnce、CanAdoptFunc组合成判断能否可以接纳对象的函数。
// 为什么只调用一次，这个在具体使用的地方说明更加合适，此处只需要知道只调用一次即可。
// 至少知道一点，能否能够接纳与具体的对象无关，因为函数不传入任何参数，所以可以推测应该与Controller的状态有关。
func (m *BaseControllerRefManager) CanAdopt() error {
    m.canAdoptOnce.Do(func() {
        if m.CanAdoptFunc != nil {
            m.canAdoptErr = m.CanAdoptFunc()
        }
    })
    return m.canAdoptErr
}

// ClaimObject()尝试获取对象(obj)的拥有权，match是匹配函数，adopt和release是接纳和释放obj拥有权的函数。
// 1. 如果match()返回true，则接纳孤儿；
// 2. 如果match()返回false，则释放对象的拥有权；
// 那么问题来了，已经有选择器了，为什么还要传入匹配函数？匹配什么呢？这个笔者在调用该函数的地方再说明。
func (m *BaseControllerRefManager) ClaimObject(obj metav1.Object, match func(metav1.Object) bool, adopt, release func(metav1.Object) error) (bool, error) {
    // 感兴趣的读者可以阅读GetControllerOfNoCopy()函数源码，笔者在此简单描述一下这个函数的功能：
    // 遍历obj.OwnerReferences，找到第一个*obj.OwnerReferences[i].Controller == true的引用。
    // 此处也可以得出一个结论：子对象只能有一个Controller类型的拥有者，否则不会发现第一个ControllerRef就返回。
    controllerRef := metav1.GetControllerOfNoCopy(obj)
    // 如果controllerRef不为空，说明obj已经有一个Controller的父对象
    if controllerRef != nil {
        // Owner是自己么？
        if controllerRef.UID != m.Controller.GetUID() {
            // 对象的拥有者不是自己，返回失败，毕竟对象已经有ControllerRef。
            return false, nil
        }
        // 匹配对象
        if match(obj) {
            // 已经拥有对象并且匹配成功，返回成功
            return true, nil
        }
        // 拥有对象但是匹配失败，如果Controller正在删除则不用释放，因为Controller删除会释放对象拥有权
        if m.Controller.GetDeletionTimestamp() != nil {
            return false, nil
        }
        // 拥有对象但是匹配失败，释放对象拥有权。前面提到孤儿的时候并没有解释孤儿怎么产生，此处就是产生孤儿的一种情况。
        // 即Controller与子对象不匹配，此时将释放子对象的拥有权。
        if err := release(obj); err != nil {
            // Pod不存在，等同于释放成功
            if errors.IsNotFound(err) {
                return false, nil
            }
            // 释放失败
            return false, err
        }
        // 释放成功
        return false, nil
    }

    // 因为obj没有ControllerRef，所以它是一个孤儿对象，如果Controller正在被删除亦或是匹配失败，则无法接纳它
    if m.Controller.GetDeletionTimestamp() != nil || !match(obj) {
        return false, nil
    }
    // 不能接纳一个正在删除的孤儿对象
    if obj.GetDeletionTimestamp() != nil {
        return false, nil
    }
    // 匹配成功，尝试接纳孤儿
    if err := adopt(obj); err != nil {
        // 对象不存在，接纳失败，这并不是错误，因为对象已经被删除了
        if errors.IsNotFound(err) {
            return false, nil
        }
        // 接纳错误
        return false, err
    }
    // 接纳成功
    return true, nil
}

PodControllerRefManager

PodControllerRefManager用于管理Pod的ControllerRef，也就是说PodControllerRefManager.ClaimObject()函数传入的对象都是Pod，源码链接: https://github.com/kubernetes/kubernetes/blob/release-1.20/pkg/controller/controller_ref_manager.go#L123。

type PodControllerRefManager struct {
    // 继承了BaseControllerRefManager，因为BaseControllerRefManager用于管理通用对象的ControllerRef
    BaseControllerRefManager
    // ControllerRef的Group、Version、Kind三元组，比如apps、v1、ReplicaSet
    controllerKind schema.GroupVersionKind
    // PodControlInterface用于创建/删除/更新Pod，详情查看：https://github.com/jindezgm/k8s-src-analysis/blob/master/controller/PodControl.md
    podControl     PodControlInterface
}

// NewPodControllerRefManager()是PodControllerRefManager的构造函数，由kube-controller-manager调用。
func NewPodControllerRefManager(
    podControl PodControlInterface,
    controller metav1.Object,
    selector labels.Selector,
    controllerKind schema.GroupVersionKind,
    canAdopt func() error,
) *PodControllerRefManager {
    // PodControllerRefManager所有参数基本都是外部传入的...
    return &PodControllerRefManager{
        BaseControllerRefManager: BaseControllerRefManager{
            Controller:   controller,
            Selector:     selector,
            CanAdoptFunc: canAdopt,
        },
        controllerKind: controllerKind,
        podControl:     podControl,
    }
}

// ClaimPods()尝试获取一组Pod的拥有权，同时传入了一组过滤函数(想必是给BaseControllerRefManager.ClaimObject()的匹配函数使用的)。
func (m *PodControllerRefManager) ClaimPods(pods []*v1.Pod, filters ...func(*v1.Pod) bool) ([]*v1.Pod, error) {
    var claimed []*v1.Pod
    var errlist []error

    // 终于看到匹配函数了，Pod的匹配函数是标签匹配同时通过所有过滤器，标签选择器好理解，过滤器到底过滤了啥就得看XxxController的具体实现了。
    match := func(obj metav1.Object) bool {
        pod := obj.(*v1.Pod)
        if !m.Selector.Matches(labels.Set(pod.Labels)) {
            return false
        }
        for _, filter := range filters {
            if !filter(pod) {
                return false
            }
        }
        return true
    }
    // 接纳Pod和释放Pod拥有权的函数，下面有这两个函数的注释
    adopt := func(obj metav1.Object) error {
        return m.AdoptPod(obj.(*v1.Pod))
    }
    release := func(obj metav1.Object) error {
        return m.ReleasePod(obj.(*v1.Pod))
    }

    // 遍历Pod，逐个获得/释放Pod拥有权
    for _, pod := range pods {
        // 尝试获取Pod的拥有权
        ok, err := m.ClaimObject(pod, match, adopt, release)
        if err != nil {
            errlist = append(errlist, err)
            continue
        }
        if ok {
            claimed = append(claimed, pod)
        }
    }
    // 返回获得拥有权的Pod以及没有获得拥有权的错误
    return claimed, utilerrors.NewAggregate(errlist)
}

// AdoptPod()发送Patch更新请求到apieserver来获得Pod的拥有权，将ControllerRef合并到Pod.OwnerReferences.
func (m *PodControllerRefManager) AdoptPod(pod *v1.Pod) error {
    // 还记得CanAdopt()是一个只会真正调用一次的函数么？此处需要知道PodControllerRefManager.ClaimPods()传入的是多个Pod。
    // 也就是说这些Pod如果有多个Pod需要校验CanAdopt()，则第一个Pod决定了后面所有的Pod，即要么都能接纳，要么都不能接纳。
    // 这更加证明了能否接纳子对象看Controller的状态而不是子对象的状态。
    if err := m.CanAdopt(); err != nil {
        return fmt.Errorf("can't adopt Pod %v/%v (%v): %v", pod.Namespace, pod.Name, pod.UID, err)
    }
    
    // ownerRefControllerPatch()会生成ControllerRef的补丁，读者可以自己看一下，非常简单
    patchBytes, err := ownerRefControllerPatch(m.Controller, m.controllerKind, pod.UID)
    if err != nil {
        return err
    }
    // Patch更新Pod。
    return m.podControl.PatchPod(pod.Namespace, pod.Name, patchBytes)
}

// ReleasePod()发送Patch更新请求到apiserver来释放Pod拥有权，从Pod.OwnerReferences中通过UID删除ControllerRef。
func (m *PodControllerRefManager) ReleasePod(pod *v1.Pod) error {
    klog.V(2).Infof("patching pod %s_%s to remove its controllerRef to %s/%s:%s",
        pod.Namespace, pod.Name, m.controllerKind.GroupVersion(), m.controllerKind.Kind, m.Controller.GetName())
    // deleteOwnerRefStrategicMergePatch()会生成一个删除指定UID的OwnerReference的补丁。
    // 关于Patch更新的实现笔者会有单独的文章介绍，此处只需要知道Patch更新能够删除指定Pod(UID)的指定OwnerReferences(UID)即可。
    patchBytes, err := deleteOwnerRefStrategicMergePatch(pod.UID, m.Controller.GetUID())
    if err != nil {
        return err
    }
    // Patch更新Pod
    err = m.podControl.PatchPod(pod.Namespace, pod.Name, patchBytes)
    if err != nil {
        if errors.IsNotFound(err) {
            // 如果Pod不存在，跟已经释放Pod拥有权是一样的
            return nil
        }
        if errors.IsInvalid(err) {
            // 返回Invalid错误有两种可能：
            // 1. Pod没有OwnerReferences，即为nil；
            // 2. 补丁包中PodUID不存在，即Pod被删除后又创建
            // 这两种可能造成的错误都可以忽略，因为Controller就没有Pod的拥有权，所以返回成功
            return nil
        }
    }
    return err
}

ReplicaSetControllerRefManager

了解PodControllerRefManager，那么ReplicaSetControllerRefManager就非常容易了，它是用来管理ReplicaSet的ControllerRef的。那么问题来了，谁的的子对象会是ReplicaSet？答案是Deployment，所以此处得到一个结论：Deployment对Pod的控制是通过ReplicaSet实现的，那么Deployment控制什么？这个可以参看DeploymentController。

因为有了PodControllerRefManager的铺垫，笔者不会对ReplicaSetControllerRefManager做比较详细的注释，源码链接: https://github.com/kubernetes/kubernetes/blob/release-1.21/pkg/controller/controller_ref_manager.go#L261。

// ReplicaSetControllerRefManager基本上与PodControllerRefManager相同，只是资源类型的不同。
type ReplicaSetControllerRefManager struct {
    BaseControllerRefManager
    controllerKind schema.GroupVersionKind
    rsControl      RSControlInterface
}

// ReplicaSetControllerRefManager的构造函数，与PodControllerRefManager基本相同，不多解释
func NewReplicaSetControllerRefManager(
    rsControl RSControlInterface,
    controller metav1.Object,
    selector labels.Selector,
    controllerKind schema.GroupVersionKind,
    canAdopt func() error,
) *ReplicaSetControllerRefManager {
    return &ReplicaSetControllerRefManager{
        BaseControllerRefManager: BaseControllerRefManager{
            Controller:   controller,
            Selector:     selector,
            CanAdoptFunc: canAdopt,
        },
        controllerKind: controllerKind,
        rsControl:      rsControl,
    }
}

// ClaimReplicaSets()尝试获取一组ReplicaSet的拥有权，比ClaimPods()少了过滤函数。
func (m *ReplicaSetControllerRefManager) ClaimReplicaSets(sets []*apps.ReplicaSet) ([]*apps.ReplicaSet, error) {
    var claimed []*apps.ReplicaSet
    var errlist []error

    // 匹配函数就是用标签选择器实现的，笔者认为标签选择器实现的匹配函数应该实现在BaseControllerRefManager中，子类直接继承使用。
    match := func(obj metav1.Object) bool {
        return m.Selector.Matches(labels.Set(obj.GetLabels()))
    }
    // 接纳/释放ReplicaSet拥有权的函数。
    adopt := func(obj metav1.Object) error {
        return m.AdoptReplicaSet(obj.(*apps.ReplicaSet))
    }
    release := func(obj metav1.Object) error {
        return m.ReleaseReplicaSet(obj.(*apps.ReplicaSet))
    }

    // 一个接一个的获取ReplicaSet的拥有权
    for _, rs := range sets {
        ok, err := m.ClaimObject(rs, match, adopt, release)
        if err != nil {
            errlist = append(errlist, err)
            continue
        }
        if ok {
            claimed = append(claimed, rs)
        }
    }
    // 返回已经获取拥有权的ReplicaSet和获取拥有权失败的错误
    return claimed, utilerrors.NewAggregate(errlist)
}

// AdoptReplicaSet()和ReleaseReplicaSet()与前面的AdoptPod()和ReleasePod()基本一样，笔者不在重复注释了
func (m *ReplicaSetControllerRefManager) AdoptReplicaSet(rs *apps.ReplicaSet) error {
    if err := m.CanAdopt(); err != nil {
        return fmt.Errorf("can't adopt ReplicaSet %v/%v (%v): %v", rs.Namespace, rs.Name, rs.UID, err)
    }
    patchBytes, err := ownerRefControllerPatch(m.Controller, m.controllerKind, rs.UID)
    if err != nil {
        return err
    }
    return m.rsControl.PatchReplicaSet(rs.Namespace, rs.Name, patchBytes)
}

func (m *ReplicaSetControllerRefManager) ReleaseReplicaSet(replicaSet *apps.ReplicaSet) error {
    klog.V(2).Infof("patching ReplicaSet %s_%s to remove its controllerRef to %s/%s:%s",
        replicaSet.Namespace, replicaSet.Name, m.controllerKind.GroupVersion(), m.controllerKind.Kind, m.Controller.GetName())
    patchBytes, err := deleteOwnerRefStrategicMergePatch(replicaSet.UID, m.Controller.GetUID())
    if err != nil {
        return err
    }
    err = m.rsControl.PatchReplicaSet(replicaSet.Namespace, replicaSet.Name, patchBytes)
    if err != nil {
        if errors.IsNotFound(err) {
            return nil
        }
        if errors.IsInvalid(err) {
            return nil
        }
    }
    return err
}

ControllerRevisionControllerRefManager

ControllerRevisionControllerRefManager笔者留给读者自己阅读，因为ReplicaSetControllerRefManager已经有大量的重复内容了。