如何用Golang编写Kubernetes Operator 详解controller-runtime框架-Golang-PHP中文网

答案是使用controller-runtime框架开发kubernetes operator能显著简化开发并确保遵循最佳实践。该框架由kubernetes官方维护，提供了manager、controller、reconciler、client和scheme等核心组件，封装了api交互、事件监听、缓存同步等底层细节，开发者只需专注于实现业务逻辑的reconcile方法，且其设计强制幂等性，保障了系统的可靠性与一致性，因此成为go语言下构建operator的事实标准。

如何用Golang编写Kubernetes Operator 详解controller-runtime框架

用Golang编写Kubernetes Operator，并深入理解

controller-runtime

登录后复制

框架，是当前扩展Kubernetes能力、实现自动化运维的有效途径。简单来说，

controller-runtime

登录后复制

提供了一套强大且规范的工具集，大大简化了Operator的开发工作，它抽象了大量底层Kubernetes API交互、事件监听、缓存管理等繁琐细节，让开发者可以专注于核心业务逻辑的实现。

解决方案

Kubernetes Operator本质上是遵循控制器模式的应用程序，它通过扩展Kubernetes API来管理自定义资源（Custom Resources, CRs）。当我们谈论用Go语言编写Operator时，

controller-runtime

登录后复制

框架无疑是首选。它由Kubernetes SIGs维护，是构建Operator的“官方”推荐方式，也是

kubebuilder

登录后复制

工具链的核心。

一个Operator的核心工作流程是：

立即学习“go语言免费学习笔记（深入）”；

定义自定义资源（CRD）：这是你的Operator将要管理的数据结构。
编写控制器（Controller）：这个组件负责监听CRD实例的变化（创建、更新、删除）。
实现协调器（Reconciler）：当控制器检测到变化时，它会触发协调器来执行业务逻辑，使当前状态（Actual State）趋近于期望状态（Desired State）。

controller-runtime

登录后复制

框架为我们提供了以下关键构建块：

Manager (管理器)：这是Operator的“大脑”，它负责启动和管理所有的控制器、Webhook，并提供共享的缓存、API客户端、Scheme等核心服务。它确保了所有组件能够协同工作，并且高效地访问Kubernetes集群状态。
Controller (控制器)：通过
```
controller.Builder
```
登录后复制
模式构建，它定义了要监听的资源类型，以及如何将资源事件映射到Reconcile请求。一个控制器可以监听多种资源，例如，一个
```
MyApplication
```
登录后复制
的控制器可能需要监听
```
MyApplication
```
登录后复制
CR本身，也要监听它创建的
```
Deployment
```
登录后复制
或
```
Service
```
登录后复制
。
Reconciler (协调器)：实现了
```
Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error)
```
登录后复制
方法。这是Operator的业务逻辑所在。当一个资源事件发生时，
```
controller-runtime
```
登录后复制
会将相应的
```
NamespacedName
```
登录后复制
封装成
```
ctrl.Request
```
登录后复制
传递给Reconciler。Reconciler的任务就是获取这个资源，然后根据其当前状态，决定需要进行哪些操作（如创建、更新、删除子资源，或者更新自身状态）。这个方法必须是幂等的，因为Kubernetes会反复调用它来确保状态一致性。
Client (客户端)：
```
controller-runtime
```
登录后复制
提供了一个统一的
```
client.Client
```
登录后复制
接口，用于与Kubernetes API服务器进行交互，执行
```
Get
```
登录后复制
、
```
List
```
登录后复制
、
```
Create
```
登录后复制
、
```
Update
```
登录后复制
、
```
Delete
```
登录后复制
等操作。它通常会利用内部的缓存来提高读取性能。
Scheme (类型注册)：
```
runtime.Scheme
```
登录后复制
负责将Go语言的结构体类型映射到Kubernetes API的GroupVersionKind (GVK)，使得客户端能够正确地序列化和反序列化API对象。

编写一个Operator，我们通常会从定义CRD开始，然后用Go结构体表示这个CRD，接着实现Reconciler的逻辑，最后在

main

登录后复制

函数中配置并启动Manager和Controller。这套流程下来，你会发现很多原本需要手动处理的细节，比如资源的版本兼容性、事件队列、错误重试机制，

controller-runtime

登录后复制

都替你考虑到了。

为什么选择controller-runtime框架开发Kubernetes Operator？

选择

controller-runtime

登录后复制

来开发Kubernetes Operator，在我看来，这几乎是Go语言生态下的一个必然选择，而且是非常明智的。它不仅仅是一个库，更像是一套“开发哲学”和“最佳实践的集合”。

首先，它极大地简化了开发复杂度。回想一下，如果没有这样的框架，你需要自己去处理Kubernetes API的连接、认证、事件监听、缓存同步、领导者选举（leader election），以及更细致的错误处理和重试机制。这些东西本身就是一套复杂的分布式系统编程挑战。

controller-runtime

登录后复制

把这些繁琐且容易出错的“样板代码”都封装好了，你只需要关注你的核心业务逻辑，也就是如何将自定义资源的状态映射到集群中的实际资源。这就像是给你提供了一套预制好的乐高积木，而不是让你从头开始烧制砖块。

其次，它是Kubernetes社区的“亲儿子”。

controller-runtime

登录后复制

是由Kubernetes SIG API Machinery团队维护的，这意味着它与Kubernetes的核心开发保持同步，能够及时采纳最新的API设计和最佳实践。它的设计理念和内部实现，都与Kubernetes自身的控制器模式高度契合。这种“血统纯正”的好处是，你不用担心它会过时或者与未来的Kubernetes版本不兼容。使用它，你站在了巨人的肩膀上，也享受着社区庞大生态系统的支持。

再者，它的模块化和可扩展性做得很好。你可以轻松地添加多个控制器来管理不同的资源，也可以集成Webhook来实现准入控制或验证。这种设计使得大型Operator的开发和维护变得更加有序。比如，我常常会发现，一个复杂的Operator可能需要管理多种自定义资源，或者与多种内置资源交互，

controller-runtime

登录后复制

的模块化设计让这一切变得井井有条，而不是一团乱麻。

最后，它强制你思考“幂等性”。

controller-runtime

登录后复制

的Reconcile循环设计，天然地要求你的业务逻辑是幂等的。这意味着无论Reconcile函数被调用多少次，只要输入相同，输出就应该相同，并且不会产生副作用。这种设计模式，虽然初看起来可能有点反直觉，但却是构建健壮、容错的分布式系统的核心原则。它迫使开发者写出更可靠、更易于调试的代码，减少了因网络抖动、API服务器重启等外部因素导致的不可预测行为。

所以，与其说为什么选择它，不如说，在Go语言生态下开发Kubernetes Operator，

controller-runtime

登录后复制

已经成为了事实上的标准和最稳妥、高效的路径。

理解controller-runtime的核心组件与工作原理

要真正用好

controller-runtime

登录后复制

，理解其核心组件及其背后的工作原理至关重要。这不仅仅是知道API怎么用，更是理解它如何高效、可靠地管理Kubernetes资源。

1. Manager (管理器)

Manager是整个Operator的“管家”。当你的Operator启动时，你首先会创建一个

Manager

登录后复制

实例。它的职责非常广泛：

统一的API客户端：它提供了一个共享的
```
client.Client
```
登录后复制
实例，所有控制器和Webhook都通过它来与Kubernetes API服务器交互。
共享的缓存：Manager内部维护了一个或多个共享的Informer（基于Kubernetes的Informer机制），这些Informer会监听Kubernetes集群中的资源事件，并将资源对象同步到本地缓存中。控制器在读取资源时，通常会从这个缓存中获取，而不是直接查询API服务器，这大大减轻了API服务器的压力，也提高了读取性能。
Scheme注册：它管理着一个
```
runtime.Scheme
```
登录后复制
，确保所有自定义资源和内置Kubernetes资源都能正确地序列化和反序列化。
控制器和Webhook的注册与启动：所有你需要运行的控制器和Webhook，都需要注册到Manager中，然后由Manager统一启动和管理它们的生命周期。
领导者选举：在多副本部署Operator时，Manager可以配置为参与领导者选举，确保只有一个Operator实例在特定时间是“活跃”的，从而避免竞争条件。

2. Controller (控制器) 与 Reconciler (协调器)

知网AI智能写作

知网AI智能写作，写文档、写报告如此简单

查看详情

这是Operator的核心执行单元。

Controller：负责监听特定资源的事件。你可以通过
```
controller.Builder
```
登录后复制
来定义一个控制器要监听哪些资源。例如，
```
For(&v1alpha1.MyResource{})
```
登录后复制
表示它会监听
```
MyResource
```
登录后复制
这个自定义资源的所有事件（创建、更新、删除）。
```
Watches(&source.Kind{Type: &appsv1.Deployment{}}, &handler.EnqueueRequestForOwner{OwnerType: &v1alpha1.MyResource{}, Is </owner>Controller: true})
```
登录后复制
则表示它还会监听由
```
MyResource
```
登录后复制
拥有的
```
Deployment
```
登录后复制
资源，当这些
```
Deployment
```
登录后复制
发生变化时，会将对应的
```
MyResource
```
登录后复制
重新加入到Reconcile队列。
Reconciler：实现了
```
Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error)
```
登录后复制
方法。当控制器检测到其监听的资源发生变化时，它会将一个包含资源
```
NamespacedName
```
登录后复制
的
```
ctrl.Request
```
登录后复制
放入一个工作队列。Reconciler会从队列中取出
```
Request
```
登录后复制
，然后执行
```
Reconcile
```
登录后复制
方法。
- 核心逻辑：在
```
Reconcile
```
  登录后复制
  方法中，你通常会先通过
```
client.Get()
```
  登录后复制
  方法获取到
```
Request
```
  登录后复制
  对应的资源对象。然后，根据这个资源对象的当前状态，判断它是否符合期望状态。如果不符合，就执行相应的操作（比如创建、更新或删除相关的子资源，或者更新自身的
```
Status
```
  登录后复制
  字段）。
- 幂等性：Reconcile函数被设计为幂等的。这意味着无论这个函数被调用多少次，只要它处理的资源状态没有外部变化，它的结果都应该是相同的，不会产生额外的副作用。这是因为Kubernetes的事件驱动模型并不能保证事件只触发一次，或者按照严格的顺序。
- 返回结果：
```
Reconcile
```
  登录后复制
  方法返回一个
```
ctrl.Result
```
  登录后复制
  和一个
```
error
```
  登录后复制
  。
  - ```
  ctrl.Result{Requeue: true}
```
  登录后复制
  ：表示需要立即重新将此
```
  Request
```
  登录后复制
  放入队列，通常用于处理瞬时错误或需要等待外部条件的情况。
- ```
ctrl.Result{RequeueAfter: someDuration}
```
    登录后复制
    ：表示在指定的时间后重新将此
```
Request
```
    登录后复制
    放入队列，常用于轮询外部服务或等待资源达到某种状态。
  - ```
  nil, err
```
  登录后复制
  ：表示处理过程中发生了错误，
```
  controller-runtime
```
  登录后复制
  会根据错误类型进行重试（通常会带指数退避）。
- ```
ctrl.Result{}, nil
```
    登录后复制
    ：表示处理成功，当前资源已达到期望状态，无需立即重试。

3. Client (客户端)

client.Client

登录后复制

是与Kubernetes API服务器交互的主要接口。它提供了一组通用的方法，如

Get

登录后复制

、

List

登录后复制

、

Create

登录后复制

、

Update

登录后复制

、

Delete

登录后复制

等。

controller-runtime

登录后复制

的客户端实现通常会利用Manager提供的共享缓存。这意味着：

读取操作 (Get/List)：默认情况下，
```
client.Client
```
登录后复制
会尝试从本地缓存中读取资源，这速度非常快。只有当缓存中没有，或者你需要获取最新状态（例如，在创建或更新后立即验证）时，才会直接向API服务器发起请求。
写入操作 (Create/Update/Delete)：这些操作会直接发送到API服务器。一旦API服务器确认操作成功，相关的Informer会最终同步这些变化到本地缓存中。

4. Scheme (类型注册)

runtime.Scheme

登录后复制

是Kubernetes API对象和Go结构体之间的桥梁。当你定义了自定义资源（例如

MyResource

登录后复制

），你需要将它的Go类型注册到

Scheme

登录后复制

中。这允许

controller-runtime

登录后复制

知道如何将API服务器返回的JSON数据反序列化成你的Go结构体，以及如何将你的Go结构体序列化成JSON发送给API服务器。它还负责管理API的版本兼容性。

5. Informer/Cache (信息器/缓存)

这是

controller-runtime

登录后复制

高效运行的关键。Manager内部会为每个被监听的资源类型启动一个

SharedInformer

登录后复制

。

Informer：会通过Kubernetes的List-Watch机制，持续监听API服务器上的资源变化。它会维护一个本地的、内存中的资源副本（即缓存）。
Cache：控制器在
```
Reconcile
```
登录后复制
函数中通过
```
client.Get()
```
登录后复制
等方法读取资源时，通常会从这个本地缓存中获取数据。这大大减少了对API服务器的请求次数，降低了API服务器的负载，也提高了Operator的响应速度。缓存是最终一致的，这意味着在极短的时间内，缓存中的数据可能与API服务器上的最新状态有微小延迟。

理解这些组件如何协同工作，能帮助你更好地设计Operator的逻辑，优化性能，并有效地调试问题。当你遇到资源状态与预期不符时，你就会知道是Reconciler的逻辑问题，还是缓存同步延迟，或者更深层次的API通信问题。

编写一个简单的Operator：从CRD到Reconcile逻辑

我们来构建一个非常简单的Operator，它管理一个名为

MyApplication

登录后复制

的自定义资源。当

MyApplication

登录后复制

被创建时，它会确保集群中存在一个同名的

Deployment

登录后复制

。

1. 定义CRD (Custom Resource Definition)

首先，我们需要定义

MyApplication

登录后复制

这个自定义资源。这通常是一个YAML文件。

# config/crd/bases/example.com_myapplications.yaml
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: myapplications.example.com
spec:
  group: example.com
  names:
    kind: MyApplication
    listKind: MyApplicationList
    plural: myapplications
    singular: myapplication
  scope: Namespaced
  versions:
  - name: v1alpha1
    served: true
    storage: true
    schema:
      openAPIV3Schema:
        type: object
        properties:
          spec:
            type: object
            properties:
              image:
                type: string
                description: The container image to deploy.
              replicas:
                type: integer
                format: int32
                description: Number of desired replicas.
                minimum: 1
            required:
              - image
              - replicas
          status:
            type: object
            properties:
              availableReplicas:
                type: integer
                format: int32
                description: Total number of available pods (ready for at least minReadySeconds).
              phase:
                type: string
                description: Current phase of the application (e.g., "Pending", "Running", "Failed").

登录后复制

2. 定义Go类型

接下来，我们需要在Go代码中定义与CRD对应的结构体。

// api/v1alpha1/myapplication_types.go
package v1alpha1

import (
    metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
)

// MyApplicationSpec defines the desired state of MyApplication
type MyApplicationSpec struct {
    Image    string `json:"image"`
    Replicas int32  `json:"replicas"`
}

// MyApplicationStatus defines the observed state of MyApplication
type MyApplicationStatus struct {
    AvailableReplicas int32  `json:"availableReplicas"`
    Phase             string `json:"phase"`
}

//+kubebuilder:object:root=true
//+kubebuilder:subresource:status

// MyApplication is the Schema for the myapplications API
type MyApplication struct {
    metav1.TypeMeta   `json:",inline"`
    metav1.ObjectMeta `json:"metadata,omitempty"`

    Spec   MyApplicationSpec   `json:"spec,omitempty"`
    Status MyApplicationStatus `json:"status,omitempty"`
}

//+kubebuilder:object:root=true

// MyApplicationList contains a list of MyApplication
type MyApplicationList struct {
    metav1.TypeMeta `json:",inline"`
    metav1.ListMeta `json:"metadata,omitempty"`
    Items           []MyApplication `json:"items"`
}

func init() {
    SchemeBuilder.Register(&MyApplication{}, &MyApplicationList{})
}

登录后复制

+kubebuilder:object:root=true

登录后复制

和

+kubebuilder:subresource:status

登录后复制

是

kubebuilder

登录后复制

的标记，它们在生成代码时很有用，但本质上，这些就是Go结构体。

3. 实现Reconciler逻辑

这是Operator的核心。我们需要创建一个

MyApplicationReconciler

登录后复制

结构体，并实现它的

Reconcile

登录后复制

方法。

// internal/controller/myapplication_controller.go
package controller

import (
    "context"
    "fmt"

    appsv1 "k8s.io/api/apps/v1"
    corev1 "k8s.io/api/core/v1"
    "k8s.io/apimachinery/pkg/api/errors"
    metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
    "k8s.io/apimachinery/pkg/types"
    "k8s.io/apimachinery/pkg/util/intstr"
    ctrl "sigs.k8s.io/controller-runtime"
    "sigs.k8s.io/controller-runtime/pkg/client"
    "sigs.k8s.io/controller-runtime/pkg/log"

    examplev1alpha1 "your.domain/my-operator/api/v1alpha1" // 替换为你的模块路径
)

// MyApplicationReconciler reconciles a MyApplication object
type MyApplicationReconciler struct {
    client.Client
    Scheme *runtime.Scheme // 假设这里已经通过 Manager 传入了 Scheme
}

//+kubebuilder:rbac:groups=example.com,resources=myapplications,verbs=get;list;watch;create;update;patch;delete
//+kubebuilder:rbac:groups=example.com,resources=myapplications/status,verbs=get;update;patch
//+kubebuilder:rbac:groups=example.com,resources=myapplications/finalizers,verbs=update
//+kubebuilder:rbac:groups=apps,resources=deployments,verbs=get;list;watch;create;update;patch;delete
//+kubebuilder:rbac:groups="",resources=services,verbs=get;list;watch;create;update;patch;delete
//+kubebuilder:rbac:groups="",resources=pods,verbs=get;list;watch

// Reconcile is part of the main kubernetes reconciliation loop which aims to
// move the current state of the cluster closer to the desired state.
func (r *MyApplicationReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
    logger := log.FromContext(ctx)

    // 1. 获取 MyApplication 实例
    myApp := &examplev1alpha1.MyApplication{}
    err := r.Get(ctx, req.NamespacedName, myApp)
    if err != nil {
        if errors.IsNotFound(err) {
            // MyApplication 对象已被删除，忽略。
            logger.Info("MyApplication resource not found. Ignoring since object must be deleted.")
            return ctrl.Result{}, nil
        }
        // 获取资源时发生错误，重新排队。
        logger.Error(err, "Failed to get MyApplication")
        return ctrl.Result{}, err
    }

    // 2. 定义期望的 Deployment
    desiredDeployment := r.newDeploymentForMyApplication(myApp)

    // 3. 检查 Deployment 是否存在
    foundDeployment := &

登录后复制

以上就是如何用Golang编写Kubernetes Operator 详解controller-runtime框架的详细内容，更多请关注php中文网其它相关文章！