云原生之深入解析Kubernetes Operator的最佳实践和最常见的问题分析

╰つ栺尖篴夢ゞ2023-12-17 14:56

一、Kubernetes Operator 简介

  • Kubernetes Operator 是通过连接主 API 并 watch 时间的一组进程，一般会 watch 有限的资源类型。当相关 watch 的 event 触发的时候，operator 做出响应并执行具体的动作。这可能仅限于与主 API 交互，但通常会涉及在其他一些系统上执行某些操作（可以是集群中或集群外资源）。
  • Kubernetes 操作员是连接到主 API 并监视事件的进程，通常是在有限数量的资源类型上。当相关事件发生时，操作员做出反应并执行特定的操作。
  • 操作符被实现为一组控制器，其中每个控制器监视一个特定的资源类型。当被监视资源上发生相关事件时，将启动一个协调周期。Operators 是控制器的集合，并且每个控制器 watch 指定的资源类型。当被 watched 的资源时间触发的时候，协调周期也将随之启动。在协调周期期间，控制器有责任检查当前状态是否与被 watched 资源描述的期望状态相匹配。有趣的是，根据设计，时间并不会传递到协调周期中，这将会强制地让你去考虑实例的整个状态，这种方法被称为基于水平触发而不是基于边缘触发（level-based, as opposed to edge-based）。这源自于电子电路的设计，水平触发是接收 event（例如中断）并对状态做出反应的理念，而基于边缘的触发是接收 event 并对状态变化做出反应的理念。
  • 水平触发虽说效率较低，因为它强制重新评估完整的状态，而不是仅仅关注改变了什么，但在信号可能丢失或多次重复传输的复杂不可靠环境中，这种方式被认为是更适用的。这种设计的选择会影响我们编写控制器代码的方式。如下提供了一个高层次的总结：
  • 当向API服务器发送请求时，特别是对于创建和删除请求，它们将会经历上述的阶段。需要注意的是，也可以指定 webhook 来执行请求的更改和验证。如果 operator 引入 CRD（custom resource definition），可能还必须定义这些 webhook。一般来说，operator 进程会开放一个端口来来实现 webhook endpoint。
  • 如果 operator 引入了一个新的 CRD，Operator SDK 将会协助你来搭建，为确保 CRD 符合 Kubernetes 扩展 API 的最佳实践，请遵循这些约定。这里所提到的所有的最佳实践都在 operator-utils 代码库中，并以可运行的例子体现。在 operator 项目中，也可以将 operator-utils 以 library 的方式导入，以此提供一些有用的工具。

二、创建 watches

  • 正如我们所说，控制器监视资源上的事件，这是通过对手表的抽象来实现的。watch 是一种接收某种类型（核心类型或 CRD）的机制。一般通过指定以下内容来创建 watch 机制：
    • 想要 watch 的资源类型；
    • handler 将被监视类型上的 events 映射到一个或多个调用协调周期的实例，监视类型和实例类型不必相同；
    • predicate 是一组能够过滤 events 且可自定义的函数。
  • 如下记录了以上提及的内容：
  • 通常来说，同一类型（kind）开启多个 watch 是可行的，因为 watch 是多路复用的。也应该尽可能多地尝试过滤 event，这边有个 predicate 例子，用来过滤 secret 资源上的 event，这里只对类型为 TLS 的 secret 资源 event 感兴趣：
rust 复制代码 
isAnnotatedSecret := predicate.Funcs{
    UpdateFunc: func(e event.UpdateEvent) bool {
        oldSecret, ok := e.ObjectOld.(*corev1.Secret)
        if !ok {
            return false
        }
        newSecret, ok := e.ObjectNew.(*corev1.Secret)
        if !ok {
            return false
        }
        if newSecret.Type != util.TLSSecret {
            return false
        }
        oldValue, _ := e.MetaOld.GetAnnotations()[certInfoAnnotation]
        newValue, _ := e.MetaNew.GetAnnotations()[certInfoAnnotation]
        old := oldValue == "true"
        new := newValue == "true"
        // if the content has changed we trigger if the annotation is there
        if !reflect.DeepEqual(newSecret.Data[util.Cert], oldSecret.Data[util.Cert]) ||
            !reflect.DeepEqual(newSecret.Data[util.CA], oldSecret.Data[util.CA]) {
            return new
        }
        // otherwise we trigger if the annotation has changed
        return old != new
    },
    CreateFunc: func(e event.CreateEvent) bool {
        secret, ok := e.Object.(*corev1.Secret)
        if !ok {
            return false
        }
        if secret.Type != util.TLSSecret {
            return false
        }
        value, _ := e.Meta.GetAnnotations()[certInfoAnnotation]
        return value == "true"
    },
}
  • 一个非常常见的模式是观察创建（和拥有）资源上的 events，并且定期在拥有这些资源的 CR 上执行协调周期 reconcile cycle。为此，可以使用 EnqueueRequestForOwner handler，按照如下方式完成：
rust 复制代码 
err = c.Watch(&source.Kind{Type: &examplev1alpha1.MyControlledType{}}, &handler.EnqueueRequestForOwner{})
  • 另一种不太常用的情况是将一个 events 传播到多个资源上。考虑一种情况，一个控制器注入了 TLS secret 的路由，同一个命名空间中的多个路由可以指向同一个 secret。如果 secret 发生了改变，需要更新所有路由。因此，需要在 secret 类型上创建一种 watch 机制，处理程序如下所示：
rust 复制代码 
type enqueueRequestForReferecingRoutes struct {
        client.Client
}

// trigger a router reconcile event for those routes that reference this secret
func (e *enqueueRequestForReferecingRoutes) Create(evt event.CreateEvent, q workqueue.RateLimitingInterface) {
        routes, _ := matchSecret(e.Client, types.NamespacedName{
                Name:      evt.Meta.GetName(),
                Namespace: evt.Meta.GetNamespace(),
        })
        for _, route := range routes {
                q.Add(reconcile.Request{NamespacedName: types.NamespacedName{
                        Namespace: route.GetNamespace(),
                        Name:      route.GetName(),
                }})
        }
}

// Update implements EventHandler
// trigger a router reconcile event for those routes that reference this secret
func (e *enqueueRequestForReferecingRoutes) Update(evt event.UpdateEvent, q workqueue.RateLimitingInterface) {
        routes, _ := matchSecret(e.Client, types.NamespacedName{
                Name:      evt.MetaNew.GetName(),
                Namespace: evt.MetaNew.GetNamespace(),
        })
        for _, route := range routes {
                q.Add(reconcile.Request{NamespacedName: types.NamespacedName{
                        Namespace: route.GetNamespace(),
                        Name:      route.GetName(),
                }})
        }
}

三、资源 Reconciliation Cycle

  • 协调周期 reconcile cycle 是在被 watch 的 event 传递后框架将控制权转交给我们地方。正如之前所解释的，在该 reconcile cycle 中没有获得相关时间类型的信息，是因为是基于水平触发的方式来工作。
  • 如下是一个管理 CRD 控制器的常见 reconcile cycle 的模型，和其他任何一个模型一样，它不会反映任何特定用例，但希望它将有助于解决编写 operator 时遇到的问题：
  • 从上图中可以看到，主要步骤是：
    • 检索感兴趣的 CR 实例；
    • 确认实例的有效性，不会在不合法实例上做任何事情；
    • 初始化实例：如果实例的某些值没有被初始化，会在这一步进行处理；
    • 判断实例的 deletion 状态，如果实例正在被删除，也需要做一些特殊的清理。
  • 管理控制器的业务逻辑，如果以上步骤均通过，最终可以管理和执行该实例的 reconcile 逻辑，这个逻辑每个控制器都不尽相同。

四、资源验证

  • 这里存在两种类型的校验：
    • 语法校验：通过定义 OpenAPI 规则来验证；
    • 语义校验：可以通过创建 ValidatingAdmissionConfiguration 来完成。
  • 注意：在控制器中不能校验 CR 合法性，一旦 CR 被 API Server 接受了，它就会存在 Etcd 中，CR 存在 Etcd 之后，管理该 CR 资源的控制器就无法拒绝它，如果这个 CR 是不合法的，控制器在尝试使用或处理它的时候将会发生错误。
  • 推荐：由于不能保证 ValidatingAdmissionConfiguration 被创建或正常工作，还是应该在控制器内部去验证 CR，如果 CR 不合法，应该避免创建无限错误循环。

① 语法校验

  • 可以按照Generating CRD的描述添加 OpenAPI 验证规则。
  • 推荐：尽可能多地为自定义资源模型进行语法校验，尽量使用语法校验，因为它相对简单，并且可以防止格式错误的 CR 存储在 etcd 中。

② 语义校验

  • 语义校验是为了确保字段具有合理的值，从而使整个资源记录是有意义的。语义验证业务逻辑取决于 CR 所代表的概念，并且必须由 operator 的开发人员进行编码实现。
  • 如果给定的 CR 需要语义校验，那么 operator 需要暴露一个 webhook，作为 operator deploymen 的一部分，ValidatingAdmissionConfiguration 也应该被创建。
  • 目前存在的局限性：
    • 在 OpenShift 3.11 中，ValidatingAdmissionConfigurations 还处于技术预览阶段（将从 4.1 开始支持）；
    • Operator SDK 不支持脚手架形式的 webhook，可以使用 kubebuilder 来进行实现：
rust 复制代码 
kubebuilder webhook --group crew --version v1 --kind FirstMate --type=mutating --operations=create,update

③ 验证控制器中的资源

  • 最好的方式是直接拒绝一个无效的 CR，而不是接受并保存在 Etcd 中，然后对它进行错误条件处理。当然也有可能的情况是，ValidatingAdmissionConfiguration 并没有被部署或者根本不可用，因此在控制器代码中进行语义校验仍然是一个很好的做法，应该做到的是，可以在 ValidatingAdmissionConfiguration 和控制器之间共享这部分结构化的代码。
  • 控制器中调用验证方法的代码如下所示：
rust 复制代码 
if ok, err := r.IsValid(instance); !ok {
    return r.ManageError(instance, err)
}
  • 请注意，如果验证失败，按照错误管理部分中的描述来管理这个错误。IsValid 函数如下：
rust 复制代码 
func (r *ReconcileMyCRD) IsValid(obj metav1.Object) (bool, error) {
    mycrd, ok := obj.(*examplev1alpha1.MyCRD)
 // validation logic
}

五、资源初始化

  • Kubernetes 的一个很好的惯例是用户只初始化他所需要的资源字段，其他的可以省略。但从编码人员和调试者的角度来说，实际上最好将所有的字段都初始化，这允许在编码的时候不必总是去校验字段是否被定义了，并且可以轻松地排除错误情况。
  • 为了初始化资源，这里有两个选项：
    • 在控制器中定义初始化方法；
    • 定义一个 MutatingAdmissionConfiguration（类似于 ValidatingAdmissionConfiguration 的程序）；
  • 在控制器中定义一个初始化方法，代码应类似于此示例：
rust 复制代码 
if ok := r.IsInitialized(instance); !ok {
    err := r.GetClient().Update(context.TODO(), instance)
    if err != nil {
        log.Error(err, "unable to update instance", "instance", instance)
        return r.ManageError(instance, err)
    }
    return reconcile.Result{}, nil
}
  • 如果 IsInitialized 方法的结果返回 true，更新 instance 并 return，这将会立即出发另一个 reconcile cycle，第二次调用 IsInitialized 方法将会返回 false，代码逻辑将会执行到下一部分。

① 资源 Finalization

  • 如果资源不属于操作员控制的 CR，但在删除该 CR 时需要采取措施，必须使用 finalizer。终结器提供了一种机制来通知 Kubernetes 控制平面，在执行标准 Kubernetes 垃圾收集逻辑之前需要执行一个操作。资源可以有一个或多个 finalizers，每一个控制器应该管理自己的 finalizer 并且忽略其他的。
  • 管理 finalizers 的伪代码算法：
    • 如果需要，在初始化方法中添加 finalizer。
    • 当资源被删除，检查此控制器拥有的 finalizer 是否存在。
      • 清理成功，移除 finalizer 并更新 CR；
      • 如果失败决定是重试还是放弃并可能留下垃圾（在某些情况下这是可以接受的）；
      • 如果不存在，直接 return；
      • 如果存在，执行如下清理逻辑：如果清理逻辑需要添加额外的资源，需要记住的是，无法在正在删除的命名空间中创建其他资源，删除命名空间将会触发 finalizer 并删除其下所有资源。
  • 代码如下所示：
rust 复制代码 
if util.IsBeingDeleted(instance) {
    if !util.HasFinalizer(instance, controllerName) {
        return reconcile.Result{}, nil
    }
    err := r.manageCleanUpLogic(instance)
    if err != nil {
        log.Error(err, "unable to delete instance", "instance", instance)
        return r.ManageError(instance, err)
    }
    util.RemoveFinalizer(instance, controllerName)
    err = r.GetClient().Update(context.TODO(), instance)
    if err != nil {
        log.Error(err, "unable to update instance", "instance", instance)
        return r.ManageError(instance, err)
    }
    return reconcile.Result{}, nil
}

② 资源所有权

  • 资源所有权是 Kubernetes 中的原生概念，它决定了资源如何被删除。默认情况下，当一个资源被删除的时候，它的子资源也也会被删除（可以设置 cascade=false 来关闭这种行为）。这种行为有助于确保资源的正确垃圾收集，尤其是当资源控制多级层次结构中的其他资源时（deployment-> repilcaset->pod）。
  • 建议：如果控制器创建资源并且它的生命周期与其他资源（kubernetes 核心资源或其他 CR）有关联，那么应该将此资源设置为其他资源的所有者，如下所示：
rust 复制代码 
controllerutil.SetControllerReference(owner, obj, r.GetScheme())
  • 有关所有权的其他规则如下：
    • 父子资源必须位于同一命名空间中；
    • 命名空间资源可以拥有集群资源，一个对象可以有一个所有者列表，如果多个命名空间对象拥有相同的集群资源，则每个对象都应声明所有权，而不会覆盖其他对象的所有权；
    • 集群资源不能拥有命名空间资源；
    • 集群资源可以拥有另外一个集群资源。

六、状态管理

  • Status 是资源的一个标准部分，被用于报告资源的状态。在这里将使用 status 报告最后一次执行协调循环的结果，也可以在 Status 中添加更多的信息。
  • 在正常情况下，如果每次执行 reconcile cycle 的时候都要更新资源，这将触发更新时间，进而导致无限触发 reconcile cycle。因此，正如上面描述的那样，应该把 Status 作为子资源。使用这种方法，能够不增加 ResourceGeneration 元数据域的情况下更新资源的状态。
  • 使用如下命令更新状态：
rust 复制代码 
err = r.Status().Update(context.Background(), instance)
  • 现在需要为 watch 机制写一个 predicate，用来丢弃不增加 ResourceGeneration 的更新事件，可以使用 GenerationChangePredicate 来完成此功能。上文提到过，在使用 finalizer 的时候，应该在初始化的时候设置，如果 finalizer 是初始化的唯一项，由于它是元数据项的一部分，因此 ResourceGeneration 不会递增。
  • 为了说明该用例，以下是 predicate 的修改版本：
rust 复制代码 
type resourceGenerationOrFinalizerChangedPredicate struct {
 predicate.Funcs
}

// Update implements default UpdateEvent filter for validating resource version change
func (resourceGenerationOrFinalizerChangedPredicate) Update(e event.UpdateEvent) bool {
 if e.MetaNew.GetGeneration() == e.MetaOld.GetGeneration() && reflect.DeepEqual(e.MetaNew.GetFinalizers(), e.MetaOld.GetFinalizers()) {
  return false
 }
 return true
}
  • 假设 status 如下所示：
rust 复制代码 
type MyCRStatus struct {
 // +kubebuilder:validation:Enum=Success,Failure
 Status     string      `json:"status,omitempty"`
 LastUpdate metav1.Time `json:"lastUpdate,omitempty"`
 Reason     string      `json:"reason,omitempty"`
}
  • 可以写一个函数来管理并保证 reconcile cycle 成功执行：
rust 复制代码 
func (r *ReconcilerBase) ManageSuccess(obj metav1.Object) (reconcile.Result, error) {
 runtimeObj, ok := (obj).(runtime.Object)
 if !ok {
  log.Error(errors.New("not a runtime.Object"), "passed object was not a runtime.Object", "object", obj)
  return reconcile.Result{}, nil
 }
 if reconcileStatusAware, updateStatus := (obj).(apis.ReconcileStatusAware); updateStatus {
  status := apis.ReconcileStatus{
   LastUpdate: metav1.Now(),
   Reason:     "",
   Status:     "Success",
  }
  reconcileStatusAware.SetReconcileStatus(status)
  err := r.GetClient().Status().Update(context.Background(), runtimeObj)
  if err != nil {
   log.Error(err, "unable to update status")
   return reconcile.Result{
    RequeueAfter: time.Second,
    Requeue:      true,
   }, nil
  }
 } else {
  log.Info("object is not RecocileStatusAware, not setting status")
 }
 return reconcile.Result{}, nil
}

七、错误管理

  • 如果控制器进入了一个错误条件，并且在 reconcile 方法中返回了一个错误，operator 将会打印错误日志到标准输出，reconlie event 将会立即再次调度（默认的调度器实际上应该检测是否一遍又一遍地出现相同的错误，并增加相应的调度时间，以经验看来，这并没有发生）。如果错误一直存在，那么也将永远存在错误循环，而且这个错误条件对用户来说是不可见的。
  • 有两种方法可以通知用户发生了错误，它们可以同时使用：
    • 在对象的 status 字段中返回错误；
    • 生成一个 event 描述错误。
  • 此外，如果错误能够自解决，应该在一段周期时间后重新调度 reconcile cycle。通常来说，周期时间是呈指数增长的，因此在每次迭代中，reconcile event 周期会越来越长（例如每次增长时间量的两倍）。
  • 现在构建状态管理来处理错误条件：
rust 复制代码 
func (r *ReconcilerBase) ManageError(obj metav1.Object, issue error) (reconcile.Result, error) {
    runtimeObj, ok := (obj).(runtime.Object)
    if !ok {
        log.Error(errors.New("not a runtime.Object"), "passed object was not a runtime.Object", "object", obj)
        return reconcile.Result{}, nil
    }
    
    var retryInterval time.Duration
    r.GetRecorder().Event(runtimeObj, "Warning", "ProcessingError", issue.Error())
    if reconcileStatusAware, updateStatus := (obj).(apis.ReconcileStatusAware); updateStatus {
        lastUpdate := reconcileStatusAware.GetReconcileStatus().LastUpdate.Time
        lastStatus := reconcileStatusAware.GetReconcileStatus().Status
        status := apis.ReconcileStatus{
            LastUpdate: metav1.Now(),
            Reason:     issue.Error(),
            Status:     "Failure",
        }

        reconcileStatusAware.SetReconcileStatus(status)
        err := r.GetClient().Status().Update(context.Background(), runtimeObj)
        if err != nil {
            log.Error(err, "unable to update status")
            return reconcile.Result{
                RequeueAfter: time.Second,
                Requeue:      true,
            }, nil
        }

        if lastUpdate.IsZero() || lastStatus == "Success" {
            retryInterval = time.Second
        } else {
            retryInterval = status.LastUpdate.Sub(lastUpdate).Round(time.Second)
        }
    } else {
        log.Info("object is not RecocileStatusAware, not setting status")
        retryInterval = time.Second
    }

    return reconcile.Result{
        RequeueAfter: time.Duration(math.Min(float64(retryInterval.Nanoseconds()*2), float64(time.Hour.Nanoseconds()*6))),
        Requeue:      true,
    }, nil
}
  • 注意，此函数会立即发送一个 event，然后使用错误条件更新状态，最后计算何时重新安排下一次 reconcile，该算法尝试将每个循环的时间加倍，最多到六个小时为止。六个小时是一个很好的上限时间，因为 event 大约持续 6 个小时，所以这应该确保始终有一个活动 event 描述当前的错误情况。
相关推荐
YCyjs1 小时前
K8S群集调度二
云原生·容器·kubernetes
Hoxy.R1 小时前
K8s小白入门
云原生·容器·kubernetes
为什么这亚子7 小时前
九、Go语言快速入门之map
运维·开发语言·后端·算法·云原生·golang·云计算
ZHOU西口9 小时前
微服务实战系列之玩转Docker（十八）
分布式·docker·云原生·架构·数据安全·etcd·rbac
牛角上的男孩10 小时前
Istio Gateway发布服务
云原生·gateway·istio
JuiceFS11 小时前
好未来：多云环境下基于 JuiceFS 建设低运维模型仓库
运维·云原生
景天科技苑12 小时前
【云原生开发】K8S多集群资源管理平台架构设计
云原生·容器·kubernetes·k8s·云原生开发·k8s管理系统
wclass-zhengge13 小时前
K8S篇（基本介绍）
云原生·容器·kubernetes
颜淡慕潇13 小时前
【K8S问题系列 |1 】Kubernetes 中 NodePort 类型的 Service 无法访问【已解决】
后端·云原生·容器·kubernetes·问题解决
昌sit！21 小时前
K8S node节点没有相应的pod镜像运行故障处理办法
云原生·容器·kubernetes
热门推荐
01【HarmonyOS】HUAWEI DevEco Studio 下载地址汇总02(欧拉)openEuler系统添加网卡文件配置流程、(欧拉)openEuler系统手动配置ipv6地址流程、(欧拉)openEuler系统网络管理说明03组基轨迹建模 GBTM的介绍与实现（Stata 或 R）04【AIGC】重塑未来的科技巨轮05全面解析：构建基于深度学习的安全帽检测系统（UI界面+YOLO代码+数据集）06【经验分享】Ubuntu22.04安装微信(linux官方版)07基于YOLOv10深度学习的CT扫描图像肾结石智能检测系统【python源码+Pyqt5界面+数据集+训练代码】深度学习实战、目标检测08Ubuntu 20.04使用Livox mid 360 测试 FAST_LIO09RAG 实践- Ollama+RagFlow 部署本地知识库10【TC3xx芯片】TC3xx芯片电源管理系统PMS详解