Kubernetes Operator 开发教程

一. Operator 概述

Kubernetes Operator 是一种封装、部署和管理复杂有状态应用的高级方法。它通过扩展 Kubernetes API 和控制器模式，将运维领域的知识（如备份、扩缩容、故障恢复）编码到自定义逻辑中，使应用可以像管理原生 Kubernetes 资源（如 Deployment、Service）一样自动化运行。

Operator 的核心思想：通过声明式 API + 控制循环（Control Loop）实现应用的全生命周期管理。

二. 什么是 Operator？

Operator = 自定义资源（Custom Resource, CR） + 自定义控制器（Custom Controller）

自定义资源（CR）

  • 定义一种新的 Kubernetes 资源类型（例如 MySQLCluster），描述应用的期望状态。

  • 示例：通过 YAML 声明一个 MySQL 集群的配置：

    apiVersion: mysql.example.com/v1
kind: MySQLCluster
metadata:
  name: my-mysql
spec:
  replicas: 3
  storageSize: 100Gi

自定义控制器（Controller）

  • 持续监控 CR 的实际状态，并驱动系统向期望状态调整（如创建 Pod、配置副本）。
  • 实现原理：监听 Kubernetes API 的事件（Create/Update/Delete），触发 Reconcile 调谐逻辑。

三. Operator 开发模式的好处

  1. 自动化复杂操作
    • 自动处理备份、恢复、升级等运维任务（例如：Etcd Operator 自动处理节点故障恢复）。
  2. 封装领域知识
    • 将运维经验编码到代码中，降低对人工操作的依赖。
  3. 统一管理界面
    • 通过 kubectl 和 Kubernetes API 管理应用，与原生资源无缝集成。
  4. 减少人为错误
    • 通过声明式配置和自动化控制，避免手动操作的失误。

四. 构建 Operator 的两种方式

1. 使用 Kubebuilder

Kubebuilder 是由 Kubernetes SIG 维护的 Operator 框架，适合熟悉 Kubernetes API 结构的开发者。

开发流程

步骤 1：安装 Kubebuilder

# 下载二进制文件（以 Linux 为例）
curl -L -o kubebuilder "https://go.kubebuilder.io/dl/latest/$(go env GOOS)/$(go env GOARCH)"
chmod +x kubebuilder && mv kubebuilder /usr/local/bin/

步骤 2：初始化项目

mkdir my-operator && cd my-operator && go mod init github.com/rxg456/my-operator
kubebuilder init --domain example.com

步骤 3：创建 API（定义 CRD）

kubebuilder create api --group webapp --version v1 --kind Guestbook

生成的 CRD 结构定义文件位于 api/v1/guestbook_types.go，需在此文件中定义资源的 Spec 和 Status 字段。例如：

type GuestbookSpec struct {
    // 定义用户期望状态（Operator YAML 中填写的字段）
    Replicas  int32  `json:"replicas"`  // 对应 YAML 的 `spec.replicas`
    Image     string `json:"image"`     // 对应 YAML 的 `spec.image`
    Port      int32  `json:"port"`      // 应用监听的端口
}

type GuestbookStatus struct {
    // 定义实际状态（由 Operator 控制器更新）
    AvailableReplicas int32 `json:"availableReplicas"` // 实际运行的副本数
    Conditions        []metav1.Condition `json:"conditions,omitempty"` 
}

对应的 YAML 示例：

apiVersion: webapp.example.com/v1
kind: Guestbook
metadata:
  name: my-guestbook
spec:
  replicas: 3
  image: nginx:latest
  port: 8080

步骤 4：实现业务逻辑

在 controllers/guestbook_controller.go 的 Reconcile 方法中编写调谐逻辑，使用 controllerutil 工具简化资源管理：

func (r *GuestbookReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
	logger := log.FromContext(ctx)
	// 获取 CR 实例
	guestbook := webappv1.Guestbook{}
	if err := r.Get(ctx, req.NamespacedName, &guestbook); err != nil {
		if apierrors.IsNotFound(err) {
            // 资源已被物理删除，无需处理
			return ctrl.Result{}, nil
		}
		return ctrl.Result{}, err
	}

	labels := map[string]string{
		"app": guestbook.Name,
	}

	deployment := &appsv1.Deployment{
		ObjectMeta: metav1.ObjectMeta{
			Name:      guestbook.Name,
			Namespace: guestbook.Namespace,
		},
	}

	if err := controllerutil.SetControllerReference(&guestbook, deployment, r.Scheme); err != nil {
		return ctrl.Result{}, err
	}
	
    // 关键操作 ：CreateOrUpdate
    // 如果 Deployment 不存在则创建，存在则更新到最新状态
	result, err := controllerutil.CreateOrUpdate(ctx, r.Client, deployment, func() error {
		// 示例：创建或更新一个 Deployment
        // 在此函数中更新 Deployment 的期望状态
		deployment.Spec = appsv1.DeploymentSpec{
			Replicas: &guestbook.Spec.Replicas,
			Selector: &metav1.LabelSelector{
				MatchLabels: labels,
			},
			Template: corev1.PodTemplateSpec{
				ObjectMeta: metav1.ObjectMeta{
					Labels: labels,
				},
				Spec: corev1.PodSpec{
					Containers: []corev1.Container{
						{
							Name:  guestbook.Name,
							Image: guestbook.Spec.Image,
							Ports: []corev1.ContainerPort{
								{
									ContainerPort: guestbook.Spec.Port,
								},
							},
						},
					},
				},
			},
		}
		
        // 关键操作：设置 OwnerReference
    	// 确保删除 Guestbook CR 时，自动清理关联的 Deployment
		if err := controllerutil.SetControllerReference(&guestbook, deployment, r.Scheme); err != nil {
			return err
		}

		return nil
	})

	if err != nil {
		logger.Error(err, "Failed to create or update Deployment")
		guestbook.Status.AvailableReplicas = 0
		return ctrl.Result{}, err
	}

	logger.Info("Deployment操作结果", "result", result)

	return ctrl.Result{}, nil
}

步骤 5：部署到本地集群测试

make manifests  # 生成 CRD YAML
make install    # 部署 CRD 本地集群
make run        # 本地运行 Operator

步骤6：本地启动测试

apiVersion: webapp.example.com/v1
kind: Guestbook
metadata:
  name: my-guestbook
spec:
  replicas: 3
  image: nginx:latest
  port: 8080

步骤 7：生产环境部署

本地开发测试完成后，需将 Operator 打包为容器镜像并部署到集群：

  1. 构建镜像
    修改 Makefile 中的 IMG 变量，指定镜像仓库地址：

    IMG = your-registry.example.com/my-operator:v1

    执行构建并推送镜像：

    make docker-build docker-push

  2. 生成Operator Deploy文件

make build-installer
  1. 部署到集群

dist/install.yaml即可在任何k8s集群安装

kubectl apply -f dist/install.yaml

kubebuilder目录结构

/cmd

  • Operator 主程序入口，执行 kubebuilder init 时生成。

/api

  • API 资源定义，用户需要修改 *_types.go 文件实现自定义 CRD，其他文件自动生成。
  • 执行 kubebuilder create api 时生成。

/internal/controller

  • 控制器，用户需要修改 *_controller.go 文件实现自定义 Reconcile 逻辑。
  • 执行 kubebuilder create api 时生成。

/config

  • CRD 相关对象，自动生成，包含：
    • /config/crd
    • /config/rbac
    • /config/sample

Makefile

  • 自动生成，包含构建、测试、运行和部署控制器的规则

2. 使用 Operator SDK

Operator SDK 是 Red Hat 维护的工具，支持 Go/Ansible/Helm 多种开发方式（推荐使用 Go）。

步骤 1：安装 Operator SDK

export ARCH=$(uname -m)
export OS=$(uname | awk '{print tolower($0)}')
curl -LO "https://github.com/operator-framework/operator-sdk/releases/latest/download/operator-sdk_${OS}_${ARCH}"
mv operator-sdk_${OS}_${ARCH} operator-sdk
chmod +x operator-sdk && mv operator-sdk /usr/local/bin/

步骤 2：初始化项目

mkdir my-operator && cd my-operator && go mod init github.com/rxg456/my-operator
operator-sdk init --domain example.com

步骤 3：创建 API(定义 CRD)

operator-sdk create api --group webapp --version v1 --kind Guestbook --resource --controller

这将生成：

  • api/v1/guestbook_types.go → 自定义 CRD 结构
  • controllers/guestbook_controller.go → 控制器逻辑

修改 api/v1/guestbook_types.go：

type GuestbookSpec struct {
    Replicas  int32  `json:"replicas"`
    Image     string `json:"image"`
    Port      int32  `json:"port"`
}

type GuestbookStatus struct {
    AvailableReplicas int32 `json:"availableReplicas"`
    Conditions        []metav1.Condition `json:"conditions,omitempty"`
}

生成 CRD：

make manifests

步骤4：实现业务逻辑

修改 controllers/guestbook_controller.go：

func (r *GuestbookReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
	logger := log.FromContext(ctx)

	guestbook := webappv1.Guestbook{}
	if err := r.Get(ctx, req.NamespacedName, &guestbook); err != nil {
		if apierrors.IsNotFound(err) {
			return ctrl.Result{}, nil
		}
		return ctrl.Result{}, err
	}

	labels := map[string]string{
		"app": guestbook.Name,
	}

	deployment := &appsv1.Deployment{
		ObjectMeta: metav1.ObjectMeta{
			Name:      guestbook.Name,
			Namespace: guestbook.Namespace,
		},
	}

	if err := controllerutil.SetControllerReference(&guestbook, deployment, r.Scheme); err != nil {
		return ctrl.Result{}, err
	}

	result, err := controllerutil.CreateOrUpdate(ctx, r.Client, deployment, func() error {

		deployment.Spec = appsv1.DeploymentSpec{
			Replicas: &guestbook.Spec.Replicas,
			Selector: &metav1.LabelSelector{
				MatchLabels: labels,
			},
			Template: corev1.PodTemplateSpec{
				ObjectMeta: metav1.ObjectMeta{
					Labels: labels,
				},
				Spec: corev1.PodSpec{
					Containers: []corev1.Container{
						{
							Name:  guestbook.Name,
							Image: guestbook.Spec.Image,
							Ports: []corev1.ContainerPort{
								{
									ContainerPort: guestbook.Spec.Port,
								},
							},
						},
					},
				},
			},
		}

		if err := controllerutil.SetControllerReference(&guestbook, deployment, r.Scheme); err != nil {
			return err
		}

		return nil
	})

	if err != nil {
		logger.Error(err, "Failed to create or update Deployment")
		guestbook.Status.AvailableReplicas = 0
		return ctrl.Result{}, err
	}

	logger.Info("Deployment操作结果", "result", result)

	return ctrl.Result{}, nil
}

步骤5：测试 Operator

本地运行

make install
make run

测试 CRD

创建 config/samples/webapp_v1_guestbook.yaml：

apiVersion: webapp.example.com/v1
kind: Guestbook
metadata:
  name: my-guestbook
spec:
  replicas: 3
  image: nginx:latest
  port: 8080

kubectl apply -f config/samples/webapp_v1_guestbook.yaml

步骤6：部署 Operator

修改 Makefile：

IMG=your-registry.example.com/my-operator:v1

构建并推送镜像：

make docker-build docker-push

步骤7：生成 Install YAML

make build-installer

步骤8：应用

kubectl apply -f dist/install.yaml

3. CRD 版本兼容性

CRD（Custom Resource Definitions） 的 apiVersion 可能受 Kubernetes 版本影响：

  • 旧版本使用 apiextensions.k8s.io/v1beta1（Kubernetes 1.15 及更早）
  • Kubernetes 1.16+ 之后推荐使用 apiextensions.k8s.io/v1
  • 1.22+ 移除 了 apiextensions.k8s.io/v1beta1

检查 install.yaml CRD 版本

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition

如果 install.yaml 里有 apiextensions.k8s.io/v1beta1，则 不兼容 Kubernetes 1.22+，需要手动升级。

4. API 资源的版本

Kubernetes 每个版本 都会废弃或移除旧 API，如果 install.yaml 里使用了废弃 API，可能无法在较新版本上运行。

常见 API 变更：

API 资源 旧版本（已废弃） 新版本（推荐使用） 移除版本
Ingress extensions/v1beta1 networking.k8s.io/v1 1.22+
Deployment apps/v1beta1 / extensions/v1beta1 apps/v1 1.16+
RBAC rbac.authorization.k8s.io/v1beta1 rbac.authorization.k8s.io/v1 1.17+

检查 install.yaml API 版本

kubectl apply --dry-run=client -f dist/install.yaml

如果输出 警告 或 报错，需要升级 install.yaml 中的 API 版本。

五. Kubebuilder vs Operator SDK

特性 Kubebuilder Operator SDK
维护方 Kubernetes SIG Red Hat
语言支持 Go Go/Ansible/Helm
项目结构 更贴近 Kubernetes API 风格 提供更多脚手架工具
适用场景 需要深度定制 Kubernetes 功能 快速构建标准化 Operator

六. 总结

  1. 选择工具：Kubebuilder 适合熟悉 K8s API 的开发者，Operator SDK 提供更多开箱即用功能。
  2. 核心思想：Operator = 声明式 API + 控制循环，通过自动化提升运维效率。

__EOF__

本文作者：每天记录一点点，日积月累 - rxg456
本文链接：https://www.cnblogs.com/rxg456/p/18746575.html
关于博主：评论和私信会在第一时间回复。或者直接私信我。
版权声明：本博客所有文章除特别声明外，均采用 BY-NC-SA 许可协议。转载请注明出处！
声援博主：如果您觉得文章对您有帮助，可以点击文章右下角【推荐】一下。您的鼓励是博主的最大动力！
posted @   rxg456  阅读(6)  评论(0)  编辑  收藏  举报
相关博文：
· kubernetes Operator 异步操作方案
· k8s Operator ctrl.Result 深度使用解析
· Operator云原生应用开发——Operator介绍
· 28-面向 K8 编程：如何通过 Operator 扩展 Kubernete API？
· Kubernetes Operator: Operator
阅读排行：
· 被坑几百块钱后，我竟然真的恢复了删除的微信聊天记录！
· 没有Manus邀请码？试试免邀请码的MGX或者开源的OpenManus吧
· 【自荐】一款简洁、开源的在线白板工具 Drawnix
· 园子的第一款AI主题卫衣上架——"HELLO! HOW CAN I ASSIST YOU TODAY
· Docker 太简单，K8s 太复杂？w7panel 让容器管理更轻松！
历史上的今天：
2021-03-02 ansible部署prometheus+node-exporter
2021-03-02 日志采集-k8s容器和nginx
点击右上角即可分享
微信分享提示