Kubernetes Operator开发超详细指南：从零基础到实战部署#

一、前言：什么是Operator？#

1.1 Operator的本质#

想象一下，如果你有一个复杂的应用，比如数据库集群，你需要手动执行很多操作：部署、配置、升级、备份、故障恢复等等。这些操作需要专业的运维知识，而且容易出错。

Operator就是为了解决这个问题而生的。它是一种Kubernetes扩展，能够将特定应用的运维知识编码到软件中，实现应用的自动化管理。

简单来说，Operator = 自定义资源(CRD) + 控制器(Controller) + 应用运维知识

1.2 为什么需要Operator？#

自动化管理：自动执行应用的部署、配置、升级等操作
一致性：确保应用在不同环境中的配置和状态一致
减少人为错误：避免手动操作带来的失误
标准化：将最佳实践编码到软件中，确保应用按照标准方式运行
可扩展性：可以根据应用的特性定制管理逻辑

1.3 Operator的工作原理#

Operator的工作基于Kubernetes的控制器模式，核心是一个调谐循环（Reconcile Loop）：

观察期望状态：读取自定义资源(CR)中定义的期望状态（Spec）
观察实际状态：检查集群中应用的实际状态
调谐：如果实际状态与期望状态不一致，执行操作使它们一致

这个过程会持续运行，确保应用始终保持在期望的状态。

二、准备工作：环境搭建#

2.1 安装必要工具#

参考开发环境搭建进行依赖工具的安装：

go: Operator开发使用Go语言，需要安装Go 1.20或更高版本。
kubectl: Kubernetes的命令行工具，用于与集群交互。
kind: 用于在本地运行Kubernetes集群的工具，非常适合开发和测试。
kubebuilder: 用于构建Kubernetes API扩展和控制器的框架，是开发Operator的必备工具。

2.2 创建本地Kubernetes集群#

参考基于kind搭建测试集群创建一个本地高可用Kubernetes集群，用于开发和测试。

集群配置：

1
kind: Cluster
2
apiVersion: kind.x-k8s.io/v1alpha4
3
networking:
4
  apiServerAddress: "192.168.1.13"
5
nodes:
6
- role: control-plane
7
  extraPortMappings:
8
  - containerPort: 6443
9
    hostPort: 6443
10
    listenAddress: "192.168.1.13"
11
    protocol: tcp
12
- role: control-plane
13
- role: control-plane
14
- role: worker
15
  extraPortMappings:
16
  - containerPort: 80
17
    hostPort: 7080
18
    listenAddress: "0.0.0.0"
19
    protocol: tcp
20
  - containerPort: 443
21
    hostPort: 7443
22
    listenAddress: "0.0.0.0"
23
    protocol: tcp
24
- role: worker
25
  extraPortMappings:
26
  - containerPort: 80
27
    hostPort: 8080
28
    listenAddress: "0.0.0.0"
29
    protocol: tcp
30
  - containerPort: 443
31
    hostPort: 8443
32
    listenAddress: "0.0.0.0"
33
    protocol: tcp
34
- role: worker
35
  extraPortMappings:
36
  - containerPort: 80
37
    hostPort: 9080
38
    listenAddress: "0.0.0.0"
39
    protocol: tcp
40
  - containerPort: 443
41
    hostPort: 9443
42
    listenAddress: "0.0.0.0"
43
    protocol: tcp

创建高可用集群命令：

1
sudo kind create cluster --config=huari.yaml --name huari-test --image kindest/node:v1.34.0 --retain; sudo kind export logs --name huari-test

切换kubectl上下文：

1
sudo kubectl cluster-info --context kind-huari-test

查看信息：

1
# 查看集群节点
2
sudo kubectl get nodes
3

4
# 查看集群全部的pod
5
sudo kubectl get pods -A -owide

删除集群：

1
sudo kind delete cluster --name huari-test

2.3 配置Go环境变量#

为了确保依赖下载顺畅，设置Go的代理：

1
go env -w GO111MODULE=on
2
go env -w GOPROXY=https://goproxy.cn,direct

三、项目初始化：创建Operator项目#

3.1 初始化项目结构#

首先，创建一个目录来存放我们的Operator项目，并使用kubebuilder初始化项目：

1
# 创建项目目录
2
mkdir -p ~/workspace/operator/myapp-operator
3
cd ~/workspace/operator/myapp-operator
4

5
# 初始化项目
6
kubebuilder init --domain example.com --repo myapp-operator

执行这个命令后，kubebuilder会创建一个基础的项目结构，并下载必要的依赖。你会看到类似以下输出：

1
INFO Writing kustomize manifests for you to edit...
2
INFO Writing scaffold for you to edit...
3
INFO Get controller runtime
4
INFO Update dependencies
5
Next: define a resource with:
6
$ kubebuilder create api

3.2 查看项目结构#

初始化完成后，让我们查看一下项目的结构：

1
ls -la

你会看到类似以下的目录结构：

1
.
2
├── cmd/                # 命令行入口
3
├── config/             # 配置文件
4
├── hack/               # 脚本文件
5
├── test/               # 测试文件
6
├── Dockerfile          # Docker构建文件
7
├── Makefile            # 构建脚本
8
├── PROJECT             # 项目元数据
9
├── README.md           # 项目说明
10
├── go.mod              # Go模块文件
11
└── go.sum              # Go依赖校验文件

3.3 创建API和控制器#

现在，让我们使用kubebuilder创建一个API资源和对应的控制器：

1
kubebuilder create api --group apps --version v1 --kind MyApp

执行这个命令时，kubebuilder会提示你是否创建资源和控制器，都选择y：

1
INFO Create Resource [y/n]
2
y
3
INFO Create Controller [y/n]
4
y
5
INFO Writing kustomize manifests for you to edit...
6
INFO Writing scaffold for you to edit...
7
INFO api/v1/myapp_types.go
8
INFO api/v1/groupversion_info.go
9
INFO internal/controller/suite_test.go
10
INFO internal/controller/myapp_controller.go
11
INFO internal/controller/myapp_controller_test.go
12
INFO Update dependencies
13
INFO Running make
14
mkdir -p /Users/king/workspace/operator/myapp-operator/bin
15
Downloading sigs.k8s.io/controller-tools/cmd/controller-gen@v0.19.0
16
/Users/king/workspace/operator/myapp-operator/bin/controller-gen object:headerFile="hack/boilerplate.go.txt" paths="./..."
17
Next: implement your new API and generate the manifests (e.g. CRDs,CRs) with:
18
$ make manifests

3.4 查看更新后的项目结构#

创建API和控制器后，项目结构会更新，让我们查看一下：

1
ls -la
2
ls -la api/v1/
3
ls -la internal/controller/

你会看到新增了以下文件：

api/v1/myapp_types.go：定义了MyApp资源的类型
api/v1/groupversion_info.go：定义了API组和版本信息
internal/controller/myapp_controller.go：实现了MyApp资源的控制器逻辑
internal/controller/myapp_controller_test.go：控制器的测试文件

四、CRD定义：定义自定义资源#

4.1 理解CRD结构#

CRD（Custom Resource Definition）是自定义资源的定义，它扩展了Kubernetes API，允许我们创建和管理自定义资源。

在api/v1/myapp_types.go文件中，我们可以看到MyApp资源的定义：

1
package v1
2

3
import (
4
   metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
5
)
6

7
// EDIT THIS FILE!  THIS IS SCAFFOLDING FOR YOU TO OWN!
8
// NOTE: json tags are required.  Any new fields you add must have json tags for the fields to be serialized.
9

10
// MyAppSpec defines the desired state of MyApp
11
type MyAppSpec struct {
12
   // INSERT ADDITIONAL SPEC FIELDS - desired state of cluster
13
   // Important: Run "make" to regenerate code after modifying this file
14
   // The following markers will use OpenAPI v3 schema to validate the value
15
   // More info: https://book.kubebuilder.io/reference/markers/crd-validation.html
16

17
   // foo is an example field of MyApp. Edit myapp_types.go to remove/update
18
   // +optional
19
   Foo *string `json:"foo,omitempty"`
20
}
21

22
// MyAppStatus defines the observed state of MyApp.
23
type MyAppStatus struct {
24
   // INSERT ADDITIONAL STATUS FIELD - define observed state of cluster
25
   // Important: Run "make" to regenerate code after modifying this file
26

27
   // For Kubernetes API conventions, see:
28
   // https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#typical-status-properties
29

30
   // conditions represent the current state of the MyApp resource.
31
   // Each condition has a unique type and reflects the status of a specific aspect of the resource.
32
   //
33
   // Standard condition types include:
34
   // - "Available": the resource is fully functional
35
   // - "Progressing": the resource is being created or updated
36
   // - "Degraded": the resource failed to reach or maintain its desired state
37
   //
38
   // The status of each condition is one of True, False, or Unknown.
39
   // +listType=map
40
   // +listMapKey=type
41
   // +optional
42
   Conditions []metav1.Condition `json:"conditions,omitempty"`
43
}
44

45
// +kubebuilder:object:root=true
46
// +kubebuilder:subresource:status
47

48
// MyApp is the Schema for the myapps API
49
type MyApp struct {
50
   metav1.TypeMeta `json:",inline"`
51

52
   // metadata is a standard object metadata
53
   // +optional
54
   metav1.ObjectMeta `json:"metadata,omitempty,omitzero"`
55

56
   // spec defines the desired state of MyApp
57
   // +required
58
   Spec MyAppSpec `json:"spec"`
59

60
   // status defines the observed state of MyApp
61
   // +optional
62
   Status MyAppStatus `json:"status,omitempty,omitzero"`
63
}
64

65
// +kubebuilder:object:root=true
66

67
// MyAppList contains a list of MyApp
68
type MyAppList struct {
69
   metav1.TypeMeta `json:",inline"`
70
   metav1.ListMeta `json:"metadata,omitempty"`
71
   Items           []MyApp `json:"items"`
72
}
73

74
func init() {
75
   SchemeBuilder.Register(&MyApp{}, &MyAppList{})
76
}

4.2 修改CRD定义#

现在，让我们修改MyApp资源的定义，添加一些实际的字段。我们将创建一个简单的应用管理资源，用于部署和管理Nginx应用。

编辑api/v1/myapp_types.go文件：

1
// MyAppSpec defines the desired state of MyApp
2
type MyAppSpec struct {
3
  // 应用名称
4
  AppName string `json:"appName,omitempty"`
5

6
  // 副本数
7
  Replicas int32 `json:"replicas,omitempty"`
8

9
  // 镜像信息
10
  Image string `json:"image,omitempty"`
11

12
  // 端口信息
13
  Port int32 `json:"port,omitempty"`
14
}
15

16
// MyAppStatus defines the observed state of MyApp
17
type MyAppStatus struct {
18
  // 部署状态
19
  Status string `json:"status,omitempty"`
20

21
  // 可用副本数
22
  AvailableReplicas int32 `json:"availableReplicas,omitempty"`
23

24
  // 服务URL
25
  ServiceURL string `json:"serviceURL,omitempty"`
26
}

4.3 生成代码#

修改完CRD定义后，我们需要运行make generate命令来生成相关的代码：

1
make generate

这个命令会生成DeepCopy方法的实现，确保资源对象可以正确地进行深拷贝操作。

4.4 生成CRD清单#

现在，让我们运行make manifests命令来生成CRD的清单文件：

1
make manifests

这个命令会生成以下文件：

CRD定义文件（在config/crd/bases/目录下）
RBAC规则文件（在config/rbac/目录下）
Webhook配置文件（如果启用了Webhook）

五、控制器开发：编写调谐逻辑#

5.1 理解控制器结构#

控制器是Operator的核心，它负责监控自定义资源的变化，并执行调谐逻辑，确保实际状态与期望状态一致。

在internal/controller/myapp_controller.go文件中，我们可以看到MyApp控制器的结构：

1
package controller
2

3
import (
4
   "context"
5

6
   "k8s.io/apimachinery/pkg/runtime"
7
   ctrl "sigs.k8s.io/controller-runtime"
8
   "sigs.k8s.io/controller-runtime/pkg/client"
9
   logf "sigs.k8s.io/controller-runtime/pkg/log"
10

11
   appsv1 "myapp-operator/api/v1"
12
)
13

14
// MyAppReconciler reconciles a MyApp object
15
type MyAppReconciler struct {
16
   client.Client
17
   Scheme *runtime.Scheme
18
}
19

20
// +kubebuilder:rbac:groups=apps.example.com,resources=myapps,verbs=get;list;watch;create;update;patch;delete
21
// +kubebuilder:rbac:groups=apps.example.com,resources=myapps/status,verbs=get;update;patch
22
// +kubebuilder:rbac:groups=apps.example.com,resources=myapps/finalizers,verbs=update
23

24
// Reconcile is part of the main kubernetes reconciliation loop which aims to
25
// move the current state of the cluster closer to the desired state.
26
// TODO(user): Modify the Reconcile function to compare the state specified by
27
// the MyApp object against the actual cluster state, and then
28
// perform operations to make the cluster state reflect the state specified by
29
// the user.
30
//
31
// For more details, check Reconcile and its Result here:
32
// - https://pkg.go.dev/sigs.k8s.io/controller-runtime@v0.22.1/pkg/reconcile
33
func (r *MyAppReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
34
   _ = logf.FromContext(ctx)
35

36
   // TODO(user): your logic here
37

38
   return ctrl.Result{}, nil
39
}
40

41
// SetupWithManager sets up the controller with the Manager.
42
func (r *MyAppReconciler) SetupWithManager(mgr ctrl.Manager) error {
43
   return ctrl.NewControllerManagedBy(mgr).
44
      For(&appsv1.MyApp{}).
45
      Named("myapp").
46
      Complete(r)
47
}

5.2 编写调谐逻辑#

现在，让我们实现Reconcile函数的逻辑。我们的目标是：

当创建MyApp资源时，自动创建对应的Deployment和Service
当更新MyApp资源时，自动更新对应的Deployment和Service
当删除MyApp资源时，自动删除对应的Deployment和Service
更新MyApp资源的状态，反映实际的部署情况

编辑internal/controller/myapp_controller.go文件：

1
import (
2
  "context"
3
  "fmt"
4
  "time"
5

6
  "k8s.io/apimachinery/pkg/api/errors"
7
  metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
8
  "k8s.io/apimachinery/pkg/runtime"
9
  "k8s.io/apimachinery/pkg/types"
10
  appsv1 "k8s.io/api/apps/v1"
11
  corev1 "k8s.io/api/core/v1"
12
  ctrl "sigs.k8s.io/controller-runtime"
13
  "sigs.k8s.io/controller-runtime/pkg/client"
14
  "sigs.k8s.io/controller-runtime/pkg/log"
15

16
  apps "myapp-operator/api/v1"
17
)
18

19
// Reconcile is part of the main kubernetes reconciliation loop which aims to
20
// move the current state of the cluster closer to the desired state.
21
func (r *MyAppReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
22
  logger := log.FromContext(ctx)
23
  logger.Info("开始处理MyApp资源", "name", req.Name, "namespace", req.Namespace)
24

25
  // 1. 获取MyApp资源
26
  var myapp apps.MyApp
27
  if err := r.Get(ctx, req.NamespacedName, &myapp); err != nil {
28
    if errors.IsNotFound(err) {
29
      logger.Info("MyApp资源不存在，可能已被删除", "name", req.Name, "namespace", req.Namespace)
30
      return ctrl.Result{}, nil
31
    }
32
    logger.Error(err, "获取MyApp资源失败", "name", req.Name, "namespace", req.Namespace)
33
    return ctrl.Result{}, err
34
  }
35

36
  // 2. 处理Deployment
37
  deploymentName := fmt.Sprintf("%s-deployment", myapp.Name)
38
  deployment := &appsv1.Deployment{
39
    ObjectMeta: metav1.ObjectMeta{
40
      Name:      deploymentName,
41
      Namespace: myapp.Namespace,
42
      Labels: map[string]string{
43
        "app": myapp.Name,
44
      },
45
    },
46
    Spec: appsv1.DeploymentSpec{
47
      Replicas: &myapp.Spec.Replicas,
48
      Selector: &metav1.LabelSelector{
49
        MatchLabels: map[string]string{
50
          "app": myapp.Name,
51
        },
52
      },
53
      Template: corev1.PodTemplateSpec{
54
        ObjectMeta: metav1.ObjectMeta{
55
          Labels: map[string]string{
56
            "app": myapp.Name,
57
          },
58
        },
59
        Spec: corev1.PodSpec{
60
          Containers: []corev1.Container{
61
            {
62
              Name:  myapp.Name,
63
              Image: myapp.Spec.Image,
64
              Ports: []corev1.ContainerPort{
65
                {
66
                  ContainerPort: myapp.Spec.Port,
67
                },
68
              },
69
            },
70
          },
71
        },
72
      },
73
    },
74
  }
75

76
  // 设置OwnerReference，确保Deployment随MyApp资源一起删除
77
  if err := ctrl.SetControllerReference(&myapp, deployment, r.Scheme); err != nil {
78
    logger.Error(err, "设置Deployment的OwnerReference失败")
79
    return ctrl.Result{}, err
80
  }
81

82
  // 检查Deployment是否存在
83
  var existingDeployment appsv1.Deployment
84
  err := r.Get(ctx, types.NamespacedName{Name: deploymentName, Namespace: myapp.Namespace}, &existingDeployment)
85
  if err != nil {
86
    if errors.IsNotFound(err) {
87
      // Deployment不存在，创建它
88
      logger.Info("创建Deployment", "name", deploymentName, "namespace", myapp.Namespace)
89
      if err := r.Create(ctx, deployment); err != nil {
90
        logger.Error(err, "创建Deployment失败")
91
        return ctrl.Result{}, err
92
      }
93
    } else {
94
      logger.Error(err, "获取Deployment失败")
95
      return ctrl.Result{}, err
96
    }
97
  } else {
98
    // Deployment存在，更新它
99
    logger.Info("更新Deployment", "name", deploymentName, "namespace", myapp.Namespace)
100
    existingDeployment.Spec = deployment.Spec
101
    if err := r.Update(ctx, &existingDeployment); err != nil {
102
      logger.Error(err, "更新Deployment失败")
103
      return ctrl.Result{}, err
104
    }
105
  }
106

107
  // 3. 处理Service
108
  serviceName := fmt.Sprintf("%s-service", myapp.Name)
109
  service := &corev1.Service{
110
    ObjectMeta: metav1.ObjectMeta{
111
      Name:      serviceName,
112
      Namespace: myapp.Namespace,
113
      Labels: map[string]string{
114
        "app": myapp.Name,
115
      },
116
    },
117
    Spec: corev1.ServiceSpec{
118
      Selector: map[string]string{
119
        "app": myapp.Name,
120
      },
121
      Ports: []corev1.ServicePort{
122
        {
123
          Port:     myapp.Spec.Port,
124
          Protocol: corev1.ProtocolTCP,
125
        },
126
      },
127
      Type: corev1.ServiceTypeClusterIP,
128
    },
129
  }
130

131
  // 设置OwnerReference，确保Service随MyApp资源一起删除
132
  if err := ctrl.SetControllerReference(&myapp, service, r.Scheme); err != nil {
133
    logger.Error(err, "设置Service的OwnerReference失败")
134
    return ctrl.Result{}, err
135
  }
136

137
  // 检查Service是否存在
138
  var existingService corev1.Service
139
  err = r.Get(ctx, types.NamespacedName{Name: serviceName, Namespace: myapp.Namespace}, &existingService)
140
  if err != nil {
141
    if errors.IsNotFound(err) {
142
      // Service不存在，创建它
143
      logger.Info("创建Service", "name", serviceName, "namespace", myapp.Namespace)
144
      if err := r.Create(ctx, service); err != nil {
145
        logger.Error(err, "创建Service失败")
146
        return ctrl.Result{}, err
147
      }
148
    } else {
149
      logger.Error(err, "获取Service失败")
150
      return ctrl.Result{}, err
151
    }
152
  } else {
153
    // Service存在，更新它
154
    logger.Info("更新Service", "name", serviceName, "namespace", myapp.Namespace)
155
    existingService.Spec = service.Spec
156
    if err := r.Update(ctx, &existingService); err != nil {
157
      logger.Error(err, "更新Service失败")
158
      return ctrl.Result{}, err
159
    }
160
  }
161

162
  // 4. 更新MyApp资源的状态
163
  logger.Info("更新MyApp资源状态", "name", myapp.Name, "namespace", myapp.Namespace)
164

165
  // 获取最新的Deployment状态
166
  if err := r.Get(ctx, types.NamespacedName{Name: deploymentName, Namespace: myapp.Namespace}, &existingDeployment); err != nil {
167
    logger.Error(err, "获取Deployment状态失败")
168
    return ctrl.Result{}, err
169
  }
170

171
  // 获取最新的Service状态
172
  if err := r.Get(ctx, types.NamespacedName{Name: serviceName, Namespace: myapp.Namespace}, &existingService); err != nil {
173
    logger.Error(err, "获取Service状态失败")
174
    return ctrl.Result{}, err
175
  }
176

177
  // 构建Service URL
178
  serviceURL := fmt.Sprintf("%s.%s.svc.cluster.local:%d", existingService.Name, existingService.Namespace, myapp.Spec.Port)
179

180
  // 更新状态
181
  myapp.Status.Status = "Running"
182
  myapp.Status.AvailableReplicas = existingDeployment.Status.AvailableReplicas
183
  myapp.Status.ServiceURL = serviceURL
184

185
  if err := r.Status().Update(ctx, &myapp); err != nil {
186
    logger.Error(err, "更新MyApp状态失败")
187
    return ctrl.Result{}, err
188
  }
189

190
  logger.Info("MyApp资源处理完成", "name", myapp.Name, "namespace", myapp.Namespace)
191
  return ctrl.Result{}, nil
192
}

5.3 注册控制器#

确保控制器在Manager中正确注册，编辑cmd/main.go文件：

1
func main() {
2
  // ... 省略前面的代码 ...
3

4
  mgr, err := ctrl.NewManager(ctrl.GetConfigOrDie(), ctrl.Options{
5
    Scheme:                 scheme,
6
    Metrics:                metricsServerOptions,
7
    WebhookServer:          webhookServer,
8
    HealthProbeBindAddress: probeAddr,
9
    LeaderElection:         enableLeaderElection,
10
    LeaderElectionID:       "80807133.example.com",
11
  })
12
  if err != nil {
13
    setupLog.Error(err, "unable to start manager")
14
    os.Exit(1)
15
  }
16

17
  // 注册MyApp控制器
18
  if err = (&controller.MyAppReconciler{
19
    Client: mgr.GetClient(),
20
    Scheme: mgr.GetScheme(),
21
  }).SetupWithManager(mgr); err != nil {
22
    setupLog.Error(err, "unable to create controller", "controller", "MyApp")
23
    os.Exit(1)
24
  }
25

26
  // ... 省略后面的代码 ...
27
}

六、部署和测试：验证Operator功能#

6.1 安装CRD到集群#

首先，让我们将CRD安装到集群中：

1
make install

这个命令会将生成的CRD定义应用到集群中，使Kubernetes能够识别和处理MyApp资源。

6.2 本地运行控制器#

现在，让我们在本地运行控制器，以便于开发和测试：

1
export ENABLE_WEBHOOKS=false
2
make run

这个命令会在本地启动控制器，它会监听集群中MyApp资源的变化，并执行调谐逻辑。

6.3 创建测试资源#

现在，让我们创建一个MyApp资源的实例，来测试我们的Operator：

创建一个myapp-test.yaml文件：

1
apiVersion: apps.example.com/v1
2
kind: MyApp
3
metadata:
4
  name: myapp-test
5
  namespace: default
6
spec:
7
  appName: nginx-test
8
  replicas: 2
9
  image: m.daocloud.io/docker.io/nginx:latest
10
  port: 80

然后，应用这个资源：

1
kubectl apply -f myapp-test.yaml

6.4 验证部署结果#

现在，让我们验证Operator是否正确地创建了Deployment和Service：

1
# 查看MyApp资源
2
kubectl get myapp
3

4
# 查看MyApp资源的详细信息
5
kubectl describe myapp myapp-test
6

7
# 查看Deployment
8
kubectl get deployment
9

10
# 查看Pod
11
kubectl get pods
12

13
# 查看Service
14
kubectl get service

你应该会看到：

MyApp资源状态为”Running”
Deployment被创建，副本数为2
Pod被创建，状态为”Running”
Service被创建，可以通过Service URL访问应用

6.5 更新测试资源#

现在，让我们更新MyApp资源，测试Operator的更新功能：

修改myapp-test.yaml文件，将副本数改为3：

1
apiVersion: apps.example.com/v1
2
kind: MyApp
3
metadata:
4
   name: myapp-test
5
   namespace: default
6
spec:
7
   appName: nginx-test
8
   replicas: 3  # 修改为3
9
   image: m.daocloud.io/docker.io/nginx:latest
10
   port: 80

然后，应用这个更新：

1
kubectl apply -f myapp-test.yaml

等待几秒钟后，验证更新结果：

1
# 查看MyApp资源的详细信息
2
kubectl describe myapp myapp-test
3

4
# 查看Deployment
5
kubectl get deployment
6

7
# 查看Pod
8
kubectl get pods

你应该会看到副本数已经更新为3，并且有3个Pod在运行。

6.6 删除测试资源#

最后，让我们删除MyApp资源，测试Operator的删除功能：

1
kubectl delete -f myapp-test.yaml

然后，验证资源是否被正确删除：

1
# 查看MyApp资源
2
kubectl get myapp
3

4
# 查看Deployment
5
kubectl get deployment
6

7
# 查看Pod
8
kubectl get pods
9

10
# 查看Service
11
kubectl get service

你应该会看到所有相关的资源都被删除了。

七、构建和部署：将Operator部署到集群#

7.1 构建Docker镜像#

现在，让我们将Operator构建为Docker镜像：

1
# 构建镜像
2
make docker-build IMG=myapp-operator:v1.0.0

这个命令会使用项目中的Dockerfile构建一个Docker镜像，标签为myapp-operator:v1.0.0。

7.2 加载镜像到kind集群#

由于我们使用的是kind本地集群，我们需要将构建好的镜像加载到集群中：

1
kind load docker-image myapp-operator:v1.0.0 --name huari-test

7.3 部署Operator到集群#

现在，让我们将Operator部署到集群中：

1
make deploy IMG=myapp-operator:v1.0.0

这个命令会：

更新config/manager/manager.yaml文件中的镜像名称
使用kustomize构建部署清单
使用kubectl将部署清单应用到集群中

7.4 验证Operator部署#

现在，让我们验证Operator是否正确部署：

1
# 查看Deployment
2
kubectl get deployment -n myapp-operator-system
3

4
# 查看Pod
5
kubectl get pods -n myapp-operator-system
6

7
# 查看Service
8
kubectl get service -n myapp-operator-system

你应该会看到Operator的Deployment、Pod和Service都被创建，并且状态正常。

7.5 测试集群中的Operator#

现在，让我们在集群中测试Operator的功能，创建一个MyApp资源：

创建一个myapp-cluster-test.yaml文件：

1
apiVersion: apps.example.com/v1
2
kind: MyApp
3
metadata:
4
  name: myapp-cluster-test
5
  namespace: default
6
spec:
7
  appName: nginx-cluster-test
8
  replicas: 2
9
  image: m.daocloud.io/docker.io/nginx:latest
10
  port: 80

然后，应用这个资源：

1
kubectl apply -f myapp-cluster-test.yaml

验证部署结果：

1
# 查看MyApp资源
2
kubectl get myapp
3

4
# 查看MyApp资源的详细信息
5
kubectl describe myapp myapp-cluster-test
6

7
# 查看Deployment
8
kubectl get deployment
9

10
# 查看Pod
11
kubectl get pods
12

13
# 查看Service
14
kubectl get service

你应该会看到Operator正确地创建了Deployment、Pod和Service。

八、常见问题和解决方案#

8.1 连接集群失败#

错误信息：dial tcp 127.0.0.1:8080: connect: connection refused

解决方案：

确保kubeconfig文件正确配置

对于kind集群，使用以下命令导出kubeconfig：

1
kind export kubeconfig --name=my-operator-test --kubeconfig=$HOME/.kube/config

验证kubectl是否可以连接到集群：
```
1
kubectl cluster-info
```

8.2 CRD注解过长#

错误信息：metadata.annotations: Too long: must have at most 262144 bytes

解决方案：修改Makefile，在manifests命令中添加crd:maxDescLen=0：

1
.PHONY: manifests
2
manifests: controller-gen
3
        $(CONTROLLER_GEN) rbac:roleName=manager-role crd:maxDescLen=0 webhook paths="./..." output:crd:artifacts:config=config/crd/bases

8.3 Webhook证书问题#

错误信息：failed to get webhook server certificate

解决方案：

开发环境中，临时禁用Webhook：
```
1
export ENABLE_WEBHOOKS=false
```

生产环境中，安装cert-manager并正确配置Webhook证书：

1
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.13.0/cert-manager.yaml

8.4 控制器启动失败#

错误信息：unable to create controller

解决方案：

检查控制器代码是否有语法错误
检查依赖是否正确安装
检查RBAC权限是否正确配置

查看详细的日志信息，找出具体的错误原因：

1
kubectl logs -n myapp-operator-system deployment/myapp-operator-controller-manager

十、结语#

10.1 总结#

通过本指南，我们学习了如何从零开始开发一个Kubernetes Operator，包括：

环境搭建和准备
项目初始化和结构创建
CRD定义和控制器开发
部署和测试
常见问题和解决方案

10.2 下一步#

现在，你已经掌握了Operator开发的基本技能，可以尝试开发更复杂的Operator：

数据库Operator：管理数据库的部署、备份、恢复等操作
监控系统Operator：管理监控系统的部署和配置
消息队列Operator：管理消息队列的部署和扩缩容
自定义应用Operator：为你的特定应用开发专用的Operator

10.3 资源推荐#

Kubernetes官方文档：https://kubernetes.io/docs/
Operator SDK文档：https://sdk.operatorframework.io/docs/
Kubebuilder文档：https://book.kubebuilder.io/
Controller Runtime文档：https://pkg.go.dev/sigs.k8s.io/controller-runtime
示例Operator：https://github.com/operator-framework/operator-sdk/tree/master/testdata

Operator开发是一个不断学习和实践的过程，希望本指南能够为你提供一个良好的起点。祝你在Operator开发的道路上越走越远！

花日の博客

Kubernetes Operator开发超详细指南：从零基础到实战部署#

一、前言：什么是Operator？#

1.1 Operator的本质#

1.2 为什么需要Operator？#

1.3 Operator的工作原理#

二、准备工作：环境搭建#

2.1 安装必要工具#

2.2 创建本地Kubernetes集群#

2.3 配置Go环境变量#

三、项目初始化：创建Operator项目#

3.1 初始化项目结构#

3.2 查看项目结构#

3.3 创建API和控制器#

3.4 查看更新后的项目结构#

四、CRD定义：定义自定义资源#

4.1 理解CRD结构#

4.2 修改CRD定义#

4.3 生成代码#

4.4 生成CRD清单#

五、控制器开发：编写调谐逻辑#

5.1 理解控制器结构#

5.2 编写调谐逻辑#

5.3 注册控制器#

六、部署和测试：验证Operator功能#

6.1 安装CRD到集群#

6.2 本地运行控制器#

6.3 创建测试资源#

6.4 验证部署结果#

6.5 更新测试资源#

6.6 删除测试资源#

七、构建和部署：将Operator部署到集群#

7.1 构建Docker镜像#

7.2 加载镜像到kind集群#

7.3 部署Operator到集群#

7.4 验证Operator部署#

7.5 测试集群中的Operator#

八、常见问题和解决方案#

8.1 连接集群失败#

8.2 CRD注解过长#

8.3 Webhook证书问题#

8.4 控制器启动失败#

十、结语#

10.1 总结#

10.2 下一步#

10.3 资源推荐#