CRD-Operator与扩展机制深度解析
你用 Deployment 部署了一套 MySQL 主从集群。主节点挂了,你手动切换从节点、更新配置、重建副本——凌晨三点,每次都是同样的流程。Deployment 能帮你重启 Pod,但它不懂 MySQL 的主从切换逻辑。能不能让 K8s 自动处理这些 Day-2 运维操作?
Operator 模式的本质:把人类运维专家的决策逻辑写成代码,让 K8s 自动执行 Day-2 运维操作。本篇从 CRD 到 Controller 到完整的 Operator 开发,逐步拆解扩展机制。
1. 为什么 K8s 被设计为可扩展平台?
K8s 核心只提供最基础的容器编排——Pod、Service、Deployment。但现实世界的需求远不止这些:
- 你想用 K8s 管理 MySQL 集群,需要自动 Failover、备份恢复——Deployment 做不到
- 你想用 K8s 管理 TLS 证书,需要自动签发、续期——K8s 原生没有这个能力
- 你想让 K8s 感知 GPU 设备并智能调度——默认 Scheduler 不认识 GPU
K8s 的解决方案不是把所有功能都塞进核心——那会让核心无限膨胀。而是提供扩展点,让社区和厂商通过"插件"的方式添加能力。
这些扩展点覆盖了 K8s 的每一层:
| 层级 | 扩展机制 | 典型案例 |
|---|---|---|
| API 层 | CRD + Controller | Prometheus Operator、cert-manager |
| 行为注入 | Admission Webhook | Istio sidecar 注入、OPA/Gatekeeper 策略 |
| 调度层 | Scheduling Framework Plugin | GPU 调度、拓扑感知调度 |
| 网络层 | CNI Plugin | Calico、Cilium、Flannel |
| 存储层 | CSI Driver | AWS EBS CSI、Ceph CSI |
| 运行时层 | CRI + Device Plugin | containerd、NVIDIA GPU Plugin |
其中最常用、最强大的扩展方式是 CRD + Controller(即 Operator 模式)。这也是本文的核心。
2. CRD:教 K8s 认识新的资源类型
2.1 从问题出发
假设你在用 K8s 部署 MySQL 集群。你希望像管理 Deployment 一样管理 MySQL:
kubectl get mysql
kubectl describe mysql production-db
kubectl delete mysql production-db
但 K8s 不认识 MySQL 这个资源类型。你可以用 ConfigMap 存储 MySQL 配置,用 StatefulSet 运行 MySQL Pod——但这样管理起来很分散,而且 K8s 不理解 MySQL 的语义(什么是主从复制?什么时候该 Failover?)。
CRD(Custom Resource Definition)让你向 K8s API 注册新的资源类型——注册后,MySQL 就成了一等公民,和 Deployment、Service 一样可以 CRUD。
2.2 一个完整的 CRD 定义
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
name: applications.app.example.com
spec:
group: app.example.com # API 组
scope: Namespaced # Namespace 级别的资源
names:
plural: applications # kubectl get applications
singular: application
kind: Application
shortNames: [app] # kubectl get app
categories: [all] # kubectl get all 会包含
versions:
- name: v1alpha1
served: true # 是否提供此版本的 API
storage: true # 是否用此版本存储到 etcd
schema:
openAPIV3Schema:
type: object
properties:
spec:
type: object
required: [image, replicas]
properties:
image:
type: string
replicas:
type: integer
minimum: 1
maximum: 100
status:
type: object
properties:
availableReplicas:
type: integer
conditions:
type: array
items:
type: object
properties:
type: { type: string }
status: { type: string }
lastTransitionTime: { type: string, format: date-time }
subresources:
status: {} # 启用 /status 子资源
scale: # 启用 /scale 子资源(HPA 可以伸缩它)
specReplicasPath: .spec.replicas
statusReplicasPath: .status.availableReplicas
additionalPrinterColumns: # kubectl get 时显示的额外列
- name: Replicas
type: integer
jsonPath: .spec.replicas
- name: Available
type: integer
jsonPath: .status.availableReplicas
- name: Age
type: date
jsonPath: .metadata.creationTimestamp
注册后:
kubectl apply -f my-app.yaml # 创建 Application 实例
kubectl get app # 短名称
kubectl get all # 也会包含 Application
但此时 CRD 只是一个"数据存储"——你创建了 Application 对象,etcd 里存了一条记录,仅此而已。没有任何程序在看着它、根据它创建 Deployment 或 Service。
CRD 需要搭配 Controller 才有生命——Controller 监听 Application 对象的变化,创建/更新/删除对应的底层资源。这就是 Operator 模式。
2.3 Finalizers:安全的删除保护
当你删除一个 Application 对象时,可能需要先清理外部资源(如删除云上的负载均衡器、清理 DNS 记录)。如果 K8s 直接从 etcd 删除对象,Controller 来不及做清理——外部资源就泄漏了。
Finalizer 机制:在对象上标记一个"删除保护锁",对象被删除时不会立即消失,而是等 Controller 完成清理后移除锁,对象才真正被删除。
graph TD
A["kubectl delete app my-app"] --> B["apiserver 设置 deletionTimestamp
对象进入 Terminating 状态"]
B --> C["Controller Reconcile 被触发
检测到 deletionTimestamp 不为空"]
C --> D["执行清理逻辑
删除外部 LB、清理 DNS"]
D --> E["Controller 移除 Finalizer"]
E --> F["apiserver 发现 Finalizers 为空
真正从 etcd 删除对象"]常见问题:如果 Controller 崩溃了,Finalizer 永远不会被移除,资源卡在 Terminating 状态。手动修复:
kubectl patch app my-app -p '{"metadata":{"finalizers":[]}}' --type=merge
2.4 CRD 多版本演进
你的 CRD 从 v1alpha1 开始,功能稳定后想发布 v1beta1,最终发布 v1。怎么做到旧版本客户端和新版本客户端同时工作?
spec:
versions:
- name: v1
served: true
storage: true # v1 是存储版本——etcd 里存的是 v1 格式
- name: v1beta1
served: true
storage: false # 旧版本仍可访问
conversion:
strategy: Webhook # 版本之间的转换通过 Webhook 完成
webhook:
clientConfig:
service:
name: my-conversion-webhook
namespace: default
path: /convert
当客户端请求 v1beta1 版本的资源时:apiserver 从 etcd 读取 v1 版本 → 调用 Conversion Webhook 转换为 v1beta1 → 返回给客户端。客户端完全感知不到底层的版本变化。
2.5 CRD vs API Aggregation
| 特性 | CRD | API Aggregation |
|---|---|---|
| 复杂度 | 低(YAML + Controller) | 高(写完整的 API Server) |
| 存储 | 用 K8s 的 etcd | 可以用自己的存储后端 |
| API 行为 | 标准 CRUD | 完全自定义(如 exec、WebSocket) |
| 典型用例 | 绝大多数 Operator | metrics-server、custom-metrics |
90% 的场景选 CRD。只有需要自定义存储后端、特殊 API 行为(如 WebSocket 流)、或超大数据量时才考虑 API Aggregation。
3. Controller 模式:Operator 的灵魂
3.1 Level-triggered vs Edge-triggered:为什么选"笨"的方式
Controller 的核心是 Reconcile 循环(调和循环)。有两种设计哲学:
Edge-triggered(边沿触发):事件驱动——"Pod 被删除了 → 执行创建新 Pod 的操作"
优点:精确,只在事件发生时动作
缺点:如果事件丢失怎么办?如果 Controller 在事件到来时正好崩溃了呢?
没有收到"Pod 被删除"的事件 → 永远不会创建新 Pod → 状态偏离
Level-triggered(电平触发):状态驱动——"期望 3 个 Pod,实际 2 个 → 创建 1 个"
优点:不依赖事件——即使丢失了所有事件,下次检查时仍然能发现"实际 2 ≠ 期望 3"并修复
缺点:看起来"笨"——每次都要检查全量状态
K8s 选择了 Level-triggered,并用 Watch 事件作为触发器来避免"笨轮询"。Watch 事件只负责"提醒 Controller 该跑一次 Reconcile 了",而 Reconcile 逻辑本身基于状态对比,不依赖事件的内容。
这就是为什么 K8s Controller 如此健壮——你可以杀掉 Controller,10 分钟后再启动它,它会自动发现所有状态偏差并修复。
3.2 幂等性:Reconcile 可能被调用任意多次
Reconcile 函数可能因为各种原因被重复调用——Watch 事件重复、Resync、重试、Controller 重启后重新处理。因此 Reconcile 必须是幂等的:调用一次和调用十次的结果一样。
// 错误示范:非幂等——每次调用都创建新 Pod,10 次调用 = 10 个 Pod
func (r *Reconciler) Reconcile(ctx context.Context, req Request) (Result, error) {
r.client.Create(ctx, newPod())
return Result{}, nil
}
// 正确示范:幂等——先检查是否存在,存在就不创建
func (r *Reconciler) Reconcile(ctx context.Context, req Request) (Result, error) {
pod := &corev1.Pod{}
err := r.client.Get(ctx, types.NamespacedName{Name: "my-pod", Namespace: "default"}, pod)
if errors.IsNotFound(err) {
return Result{}, r.client.Create(ctx, newPod())
}
return Result{}, err
}
更好的方式是使用 controllerutil.CreateOrUpdate——它内部已经处理了"先 Get,不存在就 Create,存在就 Update"的逻辑。
3.3 client-go Informer:Controller 怎么高效地感知资源变化?
Kubernetes 架构与核心概念深度解析已经详细讲过 Informer 的设计。这里从 Controller 开发者的视角回顾关键点:
graph TD
A["apiserver"] -->|"Watch"| B["Reflector
List & Watch + 自动重连"]
B --> C["DeltaFIFO
存增量事件"]
C --> D["Indexer
本地缓存"]
C --> E["EventHandler
OnAdd/OnUpdate/OnDelete"]
E -->|"key: namespace/name"| F["Work Queue
去重 + 限速 + 指数退避"]
F --> G["Reconciler
读 Indexer、比较状态、执行动作"]开发者需要关注的关键点:
-
读操作用 Indexer(缓存),写操作直接请求 apiserver。
client.Get()先查 Informer 本地缓存——毫秒级响应。client.Create/Update/Delete()直接请求 apiserver——确保写入成功。 -
Work Queue 的去重:如果一个 Pod 在 1 秒内被更新了 5 次,Queue 中只有 1 个 key——Reconcile 只跑 1 次(检查最新状态就够了,不需要知道中间变化了几次)。
-
SharedInformerFactory:10 个 Controller 都 Watch Pod?只需要 1 个 Informer 实例。SharedInformerFactory 为每种资源类型维护唯一的 Informer,避免重复 Watch。
-
Resync:定期(如每 30 秒)把 Indexer 中所有对象的 key 重新放入 Work Queue,让 Reconcile 有机会"兜底检查"——弥补可能丢失的事件。
3.4 Watch 多种资源
一个 Controller 通常需要 Watch 多个资源。比如一个 Application Controller 创建了 Deployment 和 Service——当 Deployment 的状态变化时(比如 Pod Ready 数变了),也需要触发 Application 的 Reconcile 来更新 Status。
func (r *AppReconciler) SetupWithManager(mgr ctrl.Manager) error {
return ctrl.NewControllerManagedBy(mgr).
For(&appv1.Application{}). // 主资源:Application 变化触发 Reconcile
Owns(&appsv1.Deployment{}). // 子资源:Deployment 变化也触发 Reconcile
Owns(&corev1.Service{}). // 子资源:Service 变化也触发 Reconcile
Watches( // 自定义 Watch
&corev1.ConfigMap{},
handler.EnqueueRequestsFromMapFunc(r.findAppsForConfigMap),
).
Complete(r)
}
Owns 的工作原理:Deployment 的 metadata.ownerReferences 指向 Application。当 Deployment 变化时,controller-runtime 从 ownerRef 中找到父 Application,把父 Application 的 key 放入 Work Queue——触发 Application 的 Reconcile,而不是 Deployment 的。
4. Operator 模式:把运维知识编码为软件
4.1 Operator = CRD + Controller + 领域知识
Operator 不是一个新概念——它就是 CRD + Controller 模式的应用。但 Operator 的独特之处在于它编码了人类运维专家的领域知识。
举例说明差异:
| 场景 | 没有 Operator(人工运维) | 有 Operator(自动化) |
|---|---|---|
| MySQL Master 宕机 | DBA 凌晨被叫醒 → 登录集群 → 手动 Failover → 重配 Slave | Operator 自动检测 → 提升 Slave 为 Master → 重配其他 Slave → 发告警通知 |
| TLS 证书即将过期 | 运维设日历提醒 → 手动续期 → 更新 Secret → 重启 Pod | cert-manager 自动续期 → 更新 Secret → 触发 Pod 重启 |
| Kafka 扩容 | 手动添加 Broker → 手动 reassign partition → 等待同步完成 | Strimzi Operator 自动添加 Broker → 自动 rebalance → 监控同步进度 |
Operator 成熟度模型
| 级别 | 能力 | 典型行为 |
|---|---|---|
| Level 1 | 自动安装 | 通过 CR 声明配置,Operator 创建对应的 Deployment/StatefulSet/ConfigMap |
| Level 2 | 无缝升级 | 支持版本升级/回滚,处理 Schema 迁移 |
| Level 3 | 全生命周期 | 自动备份恢复、故障转移(Failover) |
| Level 4 | 深度监控 | 集成 Prometheus Metrics、自定义告警规则 |
| Level 5 | 自动驾驶 | 自动调优参数、自动伸缩、自动修复——完全不需要人介入 |
Operator vs Helm Chart
| 维度 | Helm Chart | Operator |
|---|---|---|
| 本质 | 模板化的 YAML 包管理器 | 持续运行的控制循环 |
| Day-1(安装部署) | 擅长 | 同样支持 |
| Day-2(日常运维) | 部署完就不管了 | 持续监控、自动修复、自动升级 |
| 领域逻辑 | 无法编码 | 可以实现任意复杂的运维逻辑 |
| 复杂度 | 低 | 高(需要写 Go 代码) |
简单说:Helm 管安装,Operator 管运维。很多成熟的 Operator 同时提供 Helm Chart 作为安装方式——Helm 负责安装 Operator 本身,Operator 负责管理目标应用的完整生命周期。
4.2 完整的 Reconcile 循环 Walkthrough
让我们从头到尾走一遍一个 Application Operator 的 Reconcile 过程。不是看孤立的代码片段,而是跟踪一个真实请求的完整流程。
场景:用户创建了一个 Application:
apiVersion: app.example.com/v1alpha1
kind: Application
metadata:
name: web-app
namespace: production
spec:
image: nginx:1.25
replicas: 3
用户按下 kubectl apply 后发生了什么?
1. apiserver 收到请求
│ Authentication → Authorization → Admission → 写入 etcd
│ Application 对象被创建
│
▼
2. Informer 检测到变化
│ Operator 进程内的 Informer 通过 Watch 收到 Added 事件
│ EventHandler 把 key "production/web-app" 放入 Work Queue
│
▼
3. Worker Goroutine 从 Queue 取出 key
│ 调用 Reconcile(ctx, Request{NamespacedName: "production/web-app"})
│
▼
4. Reconcile 第一步:获取 Application 对象
│
│ app := &appv1.Application{}
│ r.Get(ctx, req.NamespacedName, app)
│ → 从 Informer 缓存中读取(不请求 apiserver)
│
▼
5. 检查是否正在被删除
│
│ if !app.DeletionTimestamp.IsZero() {
│ // 执行清理逻辑,移除 Finalizer
│ return r.handleDeletion(ctx, app)
│ }
│ → DeletionTimestamp 为零——不是删除场景,继续
│
▼
6. 确保 Finalizer 存在
│
│ if !controllerutil.ContainsFinalizer(app, "app.example.com/cleanup") {
│ controllerutil.AddFinalizer(app, "app.example.com/cleanup")
│ r.Update(ctx, app) // 写 apiserver
│ }
│ → 第一次 Reconcile,Finalizer 不存在 → 添加
│ → 这次 Update 会触发 Watch 事件,导致 Reconcile 再次被调用
│ → 但没关系——第二次调用时 Finalizer 已存在,跳过这步
│
▼
7. 调和 Deployment
│
│ // 构建期望的 Deployment
│ deploy := &appsv1.Deployment{
│ ObjectMeta: metav1.ObjectMeta{
│ Name: app.Name,
│ Namespace: app.Namespace,
│ },
│ }
│
│ // 设置 OwnerReference(Application → Deployment)
│ controllerutil.SetControllerReference(app, deploy, r.Scheme)
│
│ // 幂等地创建或更新
│ result, err := controllerutil.CreateOrUpdate(ctx, r.Client, deploy, func() error {
│ // 这个函数定义了 Deployment 的"期望状态"
│ deploy.Spec.Replicas = &app.Spec.Replicas
│ deploy.Spec.Selector = &metav1.LabelSelector{
│ MatchLabels: map[string]string{"app": app.Name},
│ }
│ deploy.Spec.Template = corev1.PodTemplateSpec{
│ ObjectMeta: metav1.ObjectMeta{
│ Labels: map[string]string{"app": app.Name},
│ },
│ Spec: corev1.PodSpec{
│ Containers: []corev1.Container{{
│ Name: "app",
│ Image: app.Spec.Image,
│ }},
│ },
│ }
│ return nil
│ })
│
│ → CreateOrUpdate 内部逻辑:
│ 1. Get Deployment → 不存在 → 调用 mutate 函数 → Create
│ 2. Get Deployment → 已存在 → 调用 mutate 函数 → 对比是否有变化 → 有变化才 Update
│
│ → 第一次 Reconcile:Deployment 不存在 → 创建
│ → 后续 Reconcile:Deployment 已存在且状态一致 → 什么都不做
│
▼
8. 调和 Service
│
│ svc := &corev1.Service{...}
│ controllerutil.SetControllerReference(app, svc, r.Scheme)
│ controllerutil.CreateOrUpdate(ctx, r.Client, svc, func() error {
│ svc.Spec.Ports = []corev1.ServicePort{{Port: 80, TargetPort: intstr.FromInt(80)}}
│ svc.Spec.Selector = map[string]string{"app": app.Name}
│ return nil
│ })
│
▼
9. 更新 Status
│
│ // 从 Informer 缓存读取 Deployment 的最新状态
│ r.Get(ctx, types.NamespacedName{Name: app.Name, Namespace: app.Namespace}, deploy)
│ app.Status.AvailableReplicas = deploy.Status.AvailableReplicas
│
│ // 设置 Condition
│ meta.SetStatusCondition(&app.Status.Conditions, metav1.Condition{
│ Type: "Ready",
│ Status: metav1.ConditionTrue,
│ Reason: "ReconcileSuccess",
│ Message: "All resources are ready",
│ LastTransitionTime: metav1.Now(),
│ })
│
│ // 注意:用 Status().Update(),不是 Update()
│ // 因为 status 是子资源,有独立的 API 端点
│ r.Status().Update(ctx, app)
│
▼
10. 返回
│
│ return ctrl.Result{}, nil
│ → nil error = 成功,不重新入队
│ → 如果返回 error,controller-runtime 自动重新入队并指数退避重试
│ → 如果返回 Result{RequeueAfter: 30s},30 秒后再 Reconcile 一次
现在用户修改了 Application 的 image:
kubectl patch app web-app -n production -p '{"spec":{"image":"nginx:1.26"}}'
1. apiserver 更新 etcd 中的 Application 对象
2. Informer 收到 Updated 事件 → key 入队
3. Reconcile 被调用
4. 步骤 7 中 CreateOrUpdate 发现 Deployment 的 image 是 nginx:1.25
但期望是 nginx:1.26 → Update Deployment
5. Deployment Controller 检测到 Pod Template 变化 → 触发滚动更新
6. 滚动更新过程中,Deployment 的 Status 不断变化
→ Informer 通过 Owns 捕获 Deployment 变化 → 触发 Application 的 Reconcile
→ 步骤 9 更新 Application 的 Status.AvailableReplicas
7. 最终所有 Pod 更新完成,Application Status 反映最新状态
这就是 Operator 的核心价值:用户只需声明"我要 nginx:1.26",Operator 自动完成从声明到实际的所有工作。
4.3 错误处理策略
Reconcile 中的错误分三类,处理方式不同:
func (r *Reconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
// ...
// 1. 临时错误(网络超时、apiserver 暂时不可用)
// → 返回 error,controller-runtime 自动重试(指数退避:5ms → 10ms → 20ms → ... → 最大 16 分钟)
if isTransientError(err) {
return ctrl.Result{}, err
}
// 2. 预期的等待(比如等 Pod Ready、等证书签发)
// → 返回 RequeueAfter,过一段时间再检查
if !isReady(resource) {
return ctrl.Result{RequeueAfter: 30 * time.Second}, nil
}
// 3. 永久错误(配置错误、无法恢复)
// → 更新 Status 记录错误,发 Event,返回 nil(不重试——重试也没用)
if isPermanentError(err) {
app.Status.Phase = "Failed"
app.Status.Message = err.Error()
r.Status().Update(ctx, app)
r.Recorder.Eventf(app, corev1.EventTypeWarning, "ReconcileFailed", err.Error())
return ctrl.Result{}, nil
}
return ctrl.Result{}, nil
}
5. Operator 开发实战
5.1 Kubebuilder:官方推荐的开发框架
Kubebuilder 是 K8s SIG 维护的 Operator 开发框架,用脚手架生成项目结构:
# 初始化项目
kubebuilder init --domain example.com --repo github.com/example/app-operator
# 创建 API(CRD + Controller 骨架代码)
kubebuilder create api --group app --version v1alpha1 --kind Application
# 创建 Webhook(可选)
kubebuilder create webhook --group app --version v1alpha1 --kind Application \
--defaulting --programmatic-validation
生成的项目结构:
├── api/v1alpha1/
│ ├── application_types.go ← CRD 类型定义(你写)
│ ├── application_webhook.go ← Webhook 逻辑(你写)
│ └── zz_generated.deepcopy.go ← 自动生成
├── internal/controller/
│ └── application_controller.go ← Reconciler 逻辑(你写)
├── config/
│ ├── crd/ ← CRD YAML(从 types.go 自动生成)
│ ├── rbac/ ← RBAC 规则(从 marker 注解自动生成)
│ └── manager/ ← Operator 自身的 Deployment
└── cmd/main.go ← 入口
5.2 Marker 注解系统
Kubebuilder 用 Go 注释中的 marker 来自动生成 CRD Schema 和 RBAC 配置——你不需要手写那些冗长的 YAML:
// +kubebuilder:object:root=true
// +kubebuilder:subresource:status
// +kubebuilder:printcolumn:name="Replicas",type="integer",JSONPath=".spec.replicas"
// +kubebuilder:printcolumn:name="Available",type="integer",JSONPath=".status.availableReplicas"
// +kubebuilder:printcolumn:name="Age",type="date",JSONPath=".metadata.creationTimestamp"
type Application struct {
metav1.TypeMeta `json:",inline"`
metav1.ObjectMeta `json:"metadata,omitempty"`
Spec ApplicationSpec `json:"spec,omitempty"`
Status ApplicationStatus `json:"status,omitempty"`
}
type ApplicationSpec struct {
// +kubebuilder:validation:Required
// +kubebuilder:validation:MinLength=1
Image string `json:"image"`
// +kubebuilder:validation:Minimum=1
// +kubebuilder:validation:Maximum=100
// +kubebuilder:default=1
Replicas int32 `json:"replicas,omitempty"`
}
运行 make manifests 后,Kubebuilder 根据这些 marker 自动生成完整的 CRD YAML。
RBAC 权限也通过 marker 声明:
// +kubebuilder:rbac:groups=app.example.com,resources=applications,verbs=get;list;watch;create;update;patch;delete
// +kubebuilder:rbac:groups=app.example.com,resources=applications/status,verbs=get;update;patch
// +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=events,verbs=create;patch
func (r *ApplicationReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
// ...
}
make manifests 会根据这些 marker 生成 RBAC ClusterRole YAML。
5.3 Operator SDK 与 Kubebuilder 的关系
Operator SDK 是 Red Hat 维护的框架,底层使用 Kubebuilder:
Operator SDK
├── Go Operator(基于 Kubebuilder)← 推荐,功能最强
├── Ansible Operator(YAML 驱动)← 适合 Ansible 用户
└── Helm Operator(Helm Chart 包装)← 最简单,适合 Day-1 场景
Operator SDK 在 Kubebuilder 基础上额外提供:
- OLM(Operator Lifecycle Manager):管理 Operator 的安装、升级、依赖
- Scorecard 测试框架
- Bundle 格式 用于发布到 OperatorHub
5.4 controller-runtime 核心架构
Kubebuilder 和 Operator SDK 共用的核心库是 controller-runtime。理解它的架构对 Operator 开发至关重要:
graph TD
M["Manager(进程级别,唯一)"]
M --> Ca["Cache
SharedInformer 封装
所有 Controller 共享"]
M --> Cl["Client
Reader: 从 Cache 读
Writer: 直接写 apiserver"]
M --> Co["Controller(可多个)"]
M --> WH["Webhook Server(可选)
Mutating / Validating"]
M --> LE["Leader Election
多副本只有一个 Leader"]
Co --> S["Source(Watch 事件源)"]
S --> P["Predicate(过滤)"]
P --> WQ["Work Queue"]
WQ --> R["Reconciler"]Predicate 过滤器——减少不必要的 Reconcile:
ctrl.NewControllerManagedBy(mgr).
For(&appv1.Application{}).
WithEventFilter(predicate.Funcs{
UpdateFunc: func(e event.UpdateEvent) bool {
// 只有 Generation 变化(即 Spec 变化)时才 Reconcile
// Status 变化、annotation 变化不触发
return e.ObjectOld.GetGeneration() != e.ObjectNew.GetGeneration()
},
}).
Complete(r)
为什么需要过滤?因为 Status 更新也会触发 Watch 事件。如果你在 Reconcile 中更新了 Status,这次 Status 更新又触发 Reconcile,Reconcile 又更新 Status... 无限循环。用 GenerationChangedPredicate 可以过滤掉这种情况——Status 更新不改变 Generation。
5.5 测试策略
// 集成测试使用 envtest(内嵌 apiserver + etcd,不需要真集群)
var _ = Describe("Application Controller", func() {
ctx := context.Background()
It("should create Deployment when Application is created", func() {
app := &appv1.Application{
ObjectMeta: metav1.ObjectMeta{
Name: "test-app",
Namespace: "default",
},
Spec: appv1.ApplicationSpec{
Image: "nginx:1.25",
Replicas: 3,
},
}
Expect(k8sClient.Create(ctx, app)).To(Succeed())
// Eventually:轮询等待 Reconcile 完成
deploy := &appsv1.Deployment{}
Eventually(func() error {
return k8sClient.Get(ctx, types.NamespacedName{
Name: "test-app", Namespace: "default",
}, deploy)
}, timeout, interval).Should(Succeed())
Expect(*deploy.Spec.Replicas).To(Equal(int32(3)))
Expect(deploy.Spec.Template.Spec.Containers[0].Image).To(Equal("nginx:1.25"))
})
})
| 测试类型 | 工具 | 覆盖什么 |
|---|---|---|
| 单元测试 | Go testing + mock | Reconciler 业务逻辑 |
| 集成测试 | envtest(内嵌 apiserver) | Controller + apiserver 交互 |
| E2E 测试 | Kind/k3d + Ginkgo | 完整集群环境 |
6. Admission Webhook
6.1 为什么需要 Webhook?
RBAC 能控制"谁能创建 Pod",但不能控制"创建的 Pod 长什么样"。你需要更细粒度的策略:
- "所有 Pod 必须设置 resource limits"
- "镜像只能来自
myregistry.example.com" - "自动给所有 Pod 注入监控 sidecar"
这些是 Admission Webhook 的领域。
6.2 Mutating vs Validating
Mutating Admission Webhook——可以修改资源:
func (w *ApplicationWebhook) Default(ctx context.Context, obj runtime.Object) error {
app := obj.(*appv1.Application)
// 设置默认值
if app.Spec.Replicas == 0 {
app.Spec.Replicas = 1
}
// 注入标准 labels
if app.Labels == nil {
app.Labels = map[string]string{}
}
app.Labels["managed-by"] = "app-operator"
return nil
}
最经典的 Mutating Webhook 案例:Istio sidecar 注入——你提交一个普通 Pod,Webhook 自动在 Pod spec 中添加 Envoy sidecar 容器和 Init Container。
Validating Admission Webhook——只能拒绝或放行,不能修改:
func (w *ApplicationWebhook) ValidateCreate(ctx context.Context, obj runtime.Object) (admission.Warnings, error) {
app := obj.(*appv1.Application)
// 验证镜像来源
if !strings.HasPrefix(app.Spec.Image, "myregistry.example.com/") {
return nil, fmt.Errorf("image must be from myregistry.example.com, got: %s", app.Spec.Image)
}
return nil, nil
}
6.3 Webhook 的关键配置
apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
metadata:
name: my-webhook
webhooks:
- name: validate.app.example.com
failurePolicy: Fail # Webhook 不可用时拒绝请求
# failurePolicy: Ignore # Webhook 不可用时放行(更宽松但更危险)
timeoutSeconds: 5 # 超时时间
sideEffects: None # 声明无副作用
namespaceSelector: # 排除系统 Namespace
matchExpressions:
- key: kubernetes.io/metadata.name
operator: NotIn
values: [kube-system, kube-public]
最佳实践:
- 性能:Webhook 在每个 API 请求的关键路径上——保持逻辑简单(<100ms),避免外部 API 调用
- 高可用:至少 2 个副本 + PodAntiAffinity 分散到不同 Node
- failurePolicy:生产环境建议
Fail(安全优先)。但如果 Webhook 不可用会导致整个集群无法创建资源——所以高可用是前提 - 证书管理:Webhook 需要 TLS 证书。推荐用 cert-manager 自动管理
7. 其他扩展机制
7.1 Scheduling Framework
K8s 调度器通过 Scheduling Framework 提供插件化扩展——不需要替换整个 Scheduler,只需在特定阶段注入自定义逻辑。
调度一个 Pod 经过这些扩展点:
PreEnqueue → QueueSort → PreFilter → Filter → PostFilter
→ PreScore → Score → NormalizeScore → Reserve → Permit
→ PreBind → Bind → PostBind
每个阶段都可以注册自定义插件。比如 GPU 调度插件在 Filter 阶段检查"Node 上是否有 Pod 要求的 GPU 型号":
func (p *GPUPlugin) Filter(ctx context.Context, state *framework.CycleState,
pod *v1.Pod, nodeInfo *framework.NodeInfo) *framework.Status {
requiredGPU := pod.Annotations["required-gpu"]
if requiredGPU == "" {
return framework.NewStatus(framework.Success)
}
node := nodeInfo.Node()
if node.Labels["gpu-type"] != requiredGPU {
return framework.NewStatus(framework.Unschedulable, "GPU type mismatch")
}
return framework.NewStatus(framework.Success)
}
也可以部署多个 Scheduler,Pod 通过 spec.schedulerName 指定使用哪个。
7.2 Device Plugin
Device Plugin 让 kubelet 能感知和调度特殊硬件设备(GPU、FPGA、SR-IOV 网卡等)。
工作流程:
1. Device Plugin 启动 → 向 kubelet 注册自己
"我管理 nvidia.com/gpu 资源,当前 Node 有 4 个"
2. kubelet 定期调用 ListAndWatch → Device Plugin 返回当前可用设备列表
kubelet 把设备数量上报给 apiserver → Node 的 Capacity 中出现 nvidia.com/gpu: 4
3. Pod 请求 GPU:
resources:
limits:
nvidia.com/gpu: 2
4. Scheduler 感知到 Pod 需要 2 个 GPU → 选择有足够 GPU 的 Node
5. kubelet 调用 Device Plugin 的 Allocate RPC
→ Device Plugin 返回需要挂载的设备文件、环境变量等
→ kubelet 把这些传给 CRI,容器启动时就能看到 GPU 设备
7.3 CSI 和 CNI 插件开发
CSI Driver 需要实现三个 gRPC 服务(Identity / Controller / Node),K8s 提供了多个 Sidecar 容器简化开发:
| Sidecar | 职责 |
|---|---|
external-provisioner | 监听 PVC,调用 CreateVolume |
external-attacher | 监听 VolumeAttachment,调用 ControllerPublish |
external-snapshotter | 处理 VolumeSnapshot |
external-resizer | 处理 Volume 扩容 |
node-driver-registrar | 向 kubelet 注册 CSI 驱动 |
CNI Plugin 是一个二进制文件,通过 stdin/stdout 和环境变量与 containerd 交互:
# containerd 调用 CNI 插件:
CNI_COMMAND=ADD \
CNI_CONTAINERID=xxx \
CNI_NETNS=/var/run/netns/xxx \
CNI_IFNAME=eth0 \
/opt/cni/bin/my-cni-plugin < /etc/cni/net.d/10-my-cni.conf
插件通过 stdout 返回 JSON 格式的网络配置结果(IP、网关、路由等)。
8. 知名 Operator 案例
| Operator | 管理对象 | 核心能力 | 学习价值 |
|---|---|---|---|
| Prometheus Operator | Prometheus/Alertmanager | ServiceMonitor CRD 简化监控配置 | CRD 设计、多资源管理 |
| cert-manager | TLS 证书 | 自动签发/续期,支持 Let's Encrypt | Webhook、多 Issuer 架构 |
| Crossplane | 云基础设施 | 用 K8s API 管理云资源(RDS/S3/VPC) | Provider 架构、XRD 组合 |
| Strimzi | Kafka 集群 | 自动化部署/扩缩容/滚动更新 | 复杂有状态应用管理 |
| CloudNativePG | PostgreSQL | 自动 Failover、备份恢复、连接池 | 数据库 Operator 典范 |
学习 Operator 开发的最好方式不是看教程——而是阅读这些成熟 Operator 的源码,看它们如何处理 Reconcile 逻辑、错误恢复、状态机转换。
9. 参考资料
| 资源 | 链接 | 说明 |
|---|---|---|
| Custom Resources | kubernetes.io | CRD 与 AA 概述 |
| Operator Pattern | kubernetes.io | Operator 模式概述 |
| Admission Controllers | kubernetes.io | Webhook 配置 |
| Scheduling Framework | kubernetes.io | 调度器扩展 |
| Device Plugins | kubernetes.io | 设备插件 |
| client-go | GitHub | Informer、Work Queue 源码 |
| Kubebuilder | book.kubebuilder.io | Operator 开发教程(官方推荐) |
| Operator SDK | sdk.operatorframework.io | Red Hat Operator 框架 |
| controller-runtime 源码 | GitHub | 核心库 |
| API Conventions | GitHub | API 设计规范(必读) |
| Writing Controllers | GitHub | 官方 Controller 开发指南 |
| Programming Kubernetes | Hausenblas & Schimanski | client-go/CRD/Operator 必读 |
| Kubernetes Operators | Dobies & Wood | Operator 从入门到实战 |
| Kubernetes Patterns (2nd Ed) | Ibryam & Huß | Controller 和 Operator 模式 |
本文基于 Kubernetes v1.30+、Kubebuilder v3+、controller-runtime v0.17+ 撰写。