如何使用 KubeBuilder 开发一个 Operator

2023年 1月 4日 35.5k 0

通过 Operator 的方案,可以对 Kubernetes 的功能进行友好地扩展。Operatpr = CRD + Controller。首先通过 yaml 定义,生成 CRD ,然后 Controller 不断地监听 etcd 中的数据,执行相应动作。开发 Operator 时,有很多繁琐且重复的事情。KubeBuilder 可以帮助我们快速生成骨架代码,开发一个 Kubernetes 的扩展功能, 更多介绍可以参考文档:Kubernetes 复杂有状态应用管理框架 – Operator 。本篇文档,主要是尝试使用 KubeBuilder 开发一个 Operator 。

1. 环境准备

  • Go 开发环境
  • 远程 Kubernetes 环境

我准备的是,单节点 Kubernetes 1.15.3 。

  • 本地 Kubectl 访问远程集群的权限

将集群 /etc/kubernetes/admin.conf 拷贝到本地 ~/.kube/config 即可。

2. Hello,Kubebuilder

2.1 安装 kubebuilder、kustomize

以 OS X 为例,当前 kubebuilder 版本为 2.x :

1
2
brew install kubebuilder
brew install kustomize

2.2 初始化项目

1
2
3
4
export GOPATH=$(go env GOPATH)
mkdir -p $GOPATH/src/github.com/kube-api
cd $GOPATH/src/github.com/kube-api
kubebuilder init --domain k8s.chenshaowen.com --license apache2 --owner "chenshaowen"

初始化工程之后,KubeBuilder 会生成一系列配置和代码框架。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
tree -L 3
.
├── Dockerfile
├── Makefile
├── PROJECT
├── bin
│   └── manager
├── config
│   ├── certmanager
│   │   ├── certificate.yaml
│   │   ├── kustomization.yaml
│   │   └── kustomizeconfig.yaml
│   ├── default
│   │   ├── kustomization.yaml
│   │   ├── manager_auth_proxy_patch.yaml
│   │   ├── manager_prometheus_metrics_patch.yaml
│   │   ├── manager_webhook_patch.yaml
│   │   └── webhookcainjection_patch.yaml
│   ├── manager
│   │   ├── kustomization.yaml
│   │   └── manager.yaml
│   ├── rbac
│   │   ├── auth_proxy_role.yaml
│   │   ├── auth_proxy_role_binding.yaml
│   │   ├── auth_proxy_service.yaml
│   │   ├── kustomization.yaml
│   │   ├── leader_election_role.yaml
│   │   ├── leader_election_role_binding.yaml
│   │   └── role_binding.yaml
│   └── webhook
│       ├── kustomization.yaml
│       ├── kustomizeconfig.yaml
│       └── service.yaml
├── go.mod
├── go.sum
├── hack
│   └── boilerplate.go.txt
└── main.go
8 directories, 28 files

2.3. 新增 API

1
2
3
4
5
6
kubebuilder create api --group groupa --version v1beta1 --kind ApiExampleA
Create Resource [y/n]
y
Create Controller [y/n]
y
......

KubeBuilder 会将 CRD 和 Controller 添加到工程中。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
tree -L 3
.
├── Dockerfile
├── Makefile
├── PROJECT # 新增 resources 部分
├── api 
│   └── v1beta1 # 新增 API 描述
│       ├── apiexamplea_types.go
│       ├── groupversion_info.go
│       └── zz_generated.deepcopy.go
├── bin
│   └── manager
├── config
│   ├── certmanager
│   │   ├── certificate.yaml
│   │   ├── kustomization.yaml
│   │   └── kustomizeconfig.yaml
│   ├── crd # 新增 CRD 定义
│   │   ├── kustomization.yaml
│   │   ├── kustomizeconfig.yaml
│   │   └── patches
│   ├── default
│   │   ├── kustomization.yaml
│   │   ├── manager_auth_proxy_patch.yaml
│   │   ├── manager_prometheus_metrics_patch.yaml
│   │   ├── manager_webhook_patch.yaml
│   │   └── webhookcainjection_patch.yaml
│   ├── manager
│   │   ├── kustomization.yaml
│   │   └── manager.yaml
│   ├── rbac
│   │   ├── auth_proxy_role.yaml
│   │   ├── auth_proxy_role_binding.yaml
│   │   ├── auth_proxy_service.yaml
│   │   ├── kustomization.yaml
│   │   ├── leader_election_role.yaml
│   │   ├── leader_election_role_binding.yaml
│   │   └── role_binding.yaml
│   ├── samples # 新增创建 CRD 对象示例
│   │   └── groupa_v1beta1_apiexamplea.yaml
│   └── webhook
│       ├── kustomization.yaml
│       ├── kustomizeconfig.yaml
│       └── service.yaml
├── controllers # 新增 Controller
│   ├── apiexamplea_controller.go
│   └── suite_test.go
├── go.mod # 新增依赖包
├── go.sum
├── hack
│   └── boilerplate.go.txt
└── main.go # 新增处理逻辑
14 directories, 36 files

2.4 修改配置,适配国内环境

在容器中进行编译时,由于国内网络问题,会导致拉取不到 Go 依赖包和依赖镜像,需要修改 Dockerfile 文件。

  • 增加 GO 代理
  • 修改镜像源
1
git diff Dockerfile 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
@@ -7,7 +7,7 @@ COPY go.mod go.mod
 COPY go.sum go.sum
 # cache deps before building and copying source so that we don't need to re-download as much
 # and so that source changes don't invalidate our downloaded layer
-RUN go mod download
+RUN GOPROXY=https://gocenter.io go mod download

 # Copy the go source
 COPY main.go main.go
@@ -19,7 +19,7 @@ RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 GO111MODULE=on go build -a -o manager

 # Use distroless as minimal base image to package the manager binary
 # Refer to https://github.com/GoogleContainerTools/distroless for more details
-FROM gcr.io/distroless/static:latest
+FROM gcr.azk8s.cn/distroless/static:latest
 WORKDIR /
 COPY --from=builder /workspace/manager .
 ENTRYPOINT ["/manager"]

2.5. 构建并推送镜像测试

  • 本地构建并推送镜像
  • 由于使用的是远程 Kubernetes 环境,需要借助镜像仓库进行部署。

    • 修改镜像名称
    1
    
    git diff Makefile
    
    1
    2
    3
    4
    5
    6
    7
    
    @@ -1,6 +1,6 @@
    
     # Image URL to use all building/pushing image targets
    -IMG ?= controller:latest
    +IMG ?= docker.io/shaowenchen/controller:latest
     # Produce CRDs that work back to Kubernetes 1.11 (no version conversion)
     CRD_OPTIONS ?= "crd:trivialVersions=true"
    
    • 登陆 docker.io 的镜像仓库
    1
    2
    3
    
    docker login docker.io -u shaowenchen
    Password:
    Login Succeeded
    
    • 构建并推送镜像
    1
    
    make docker-build & make docker-push
    

    也可以通过,在执行 make docker-build 等命令时,增加 IMG 变量修改镜像名称。

  • 部署到 Kubernetes
    • 安装 kustomize
    1
    
    brew install kustomize
    
    • 部署 CRD
    1
    
    make install
    
    • 查看 CRD
    1
    2
    3
    
    kubectl get crd
    NAME                                      CREATED AT
    apiexampleas.groupa.k8s.chenshaowen.com   2019-09-24T07:24:45Z
    
    • 部署 Controller
    1
    
    make deploy
    
    • 查看 deployment
    1
    2
    3
    
    kubectl get deploy  -n kube-api-system
    NAME                          READY   UP-TO-DATE   AVAILABLE   AGE
    kube-api-controller-manager   1/1     1            1           46s
    
    • 创建 CRD 对象
    1
    
    kubectl apply -f config/samples/groupa_v1beta1_apiexamplea.yaml
    
    • 查看 CRD 对象
    1
    2
    3
    4
    
    kubectl get apiexampleas.groupa.k8s.chenshaowen.com
    
    NAME                 AGE
    apiexamplea-sample   61s
    
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    
    kubectl get apiexampleas.groupa.k8s.chenshaowen.com apiexamplea-sample  -o yaml
    
    apiVersion: groupa.k8s.chenshaowen.com/v1beta1
    kind: ApiExampleA
    metadata:
      annotations:
        kubectl.kubernetes.io/last-applied-configuration: |
          {"apiVersion":"groupa.k8s.chenshaowen.com/v1beta1","kind":"ApiExampleA","metadata":{"annotations":{},"name":"apiexamplea-sample","namespace":"default"},"spec":{"foo":"bar"}}
      creationTimestamp: "2019-09-24T07:29:16Z"
      generation: 1
      name: apiexamplea-sample
      namespace: default
      resourceVersion: "635450"
      selfLink: /apis/groupa.k8s.chenshaowen.com/v1beta1/namespaces/default/apiexampleas/apiexamplea-sample
      uid: 05398ab4-7d4a-4f2e-af30-b59e61680c7e
    spec:
      foo: bar
    

    3. 在 Project 中写入逻辑

    通过上面的操作,我们新增了 Kubernetes 对象类型 apiexampleas.groupa.k8s.chenshaowen.comApiExampleA),并实例化对象进行操作。这些操作仅仅只是对 etcd 数据的操作,没有触发有效动作。下面,尝试往工程中注入一点自定义逻辑。实现一个简单的功能:给自定义的 CRD 增加两个字段,FirstName、SecondName ;创建对象时,在 Controller 中获取这两个字段,并输出到日志中。

  • 修改代码
    • 增加 CRD 字段

    api/v1beta1/apiexamplea_types.go 文件 ApiExampleASpec 结构体中增加两个字段:

    1
    2
    3
    4
    5
    6
    
    type ApiExampleASpec struct {
    	// INSERT ADDITIONAL SPEC FIELDS - desired state of cluster
    	// Important: Run "make" to regenerate code after modifying this file
    	FirstName  string `json:"firstname"` // add
    	SecondName string `json:"secondname"` // add
    }
    
    • 增加 Controller 逻辑

    首先在 import 中新增 log 包:

    1
    2
    3
    
    import (
      "log" // add 
      ...
    

    然后在 Reconcile 函数中,处理逻辑

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    
    func (r *ApiExampleAReconciler) Reconcile(req ctrl.Request) (ctrl.Result, error) {
    	// _ = context.Background()
    	// _ = r.Log.WithValues("apiexamplea", req.NamespacedName)
    
    	// // your logic here
    
    	// return ctrl.Result{}, nil
    	ctx := context.Background()
    	_ = r.Log.WithValues("apiexamplea", req.NamespacedName)
    
    	obja := &groupav1beta1.ApiExampleA{}
    	if err := r.Get(ctx, req.NamespacedName, obja); err != nil {
    		log.Println(err, "unable to fetch New Object")
    	} else {
    		log.Println("fetch New Object:", obja.Spec.FirstName, obja.Spec.SecondName)
    	}
    
    	return ctrl.Result{}, nil
    }
    
  • 修改镜像 tag
  • 修改镜像 tag 是为了远程 Kubernetes 集群远程部署 Deployment 时,能够重新拉取镜像,使用指定的镜像进行部署。修改 Makefile 文件中的变量 IMG 为:IMG ?= docker.io/shaowenchen/controller:1

  • 构建发布
  • 1
    
    make & make docker-build & make docker-push
    
  • 部署
  • 1
    
    make deploy
    
  • 生成一个 CRD 对象实例
  • config/samples/groupa_v1beta1_apiexamplea.yaml 文件中修改 name 值,并在 spec 字段新增两个字段:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    
    apiVersion: groupa.k8s.chenshaowen.com/v1beta1
    kind: ApiExampleA
    metadata:
      name: apiexamplea-sample2
    spec:
      # Add fields here
      # foo: bar
      firstname: shaowen
      secondname: chen
    

    创建 CRD 对象

    1
    
    kubectl create -f config/samples/groupa_v1beta1_apiexamplea.yaml
    

    查看 Controller 的 Pod Name

    1
    2
    3
    
    kubectl get pod -n kube-api-system
    NAME                                           READY   STATUS    RESTARTS   AGE
    kube-api-controller-manager-7d8bb9fc6f-8bmg9   2/2     Running   0          22m
    

    查看创建日志

    1
    2
    3
    4
    5
    6
    7
    8
    9
    
    kubectl logs kube-api-controller-manager-7d8bb9fc6f-8bmg9 -c manager -n kube-api-system
    2019-09-25T07:09:51.124Z	INFO	controller-runtime.metrics	metrics server is starting to listen	{"addr": "127.0.0.1:8080"}
    2019-09-25T07:09:51.216Z	INFO	controller-runtime.controller	Starting EventSource	{"controller": "apiexamplea", "source": "kind source: /, Kind="}
    2019-09-25T07:09:51.217Z	INFO	setup	starting manager
    2019-09-25T07:09:51.217Z	INFO	controller-runtime.manager	starting metrics server	{"path": "/metrics"}
    2019-09-25T07:10:08.111Z	INFO	controller-runtime.controller	Starting Controller	{"controller": "apiexamplea"}
    2019-09-25T07:10:08.111Z	DEBUG	controller-runtime.manager.events	Normal	{"object": {"kind":"ConfigMap","namespace":"kube-api-system","name":"controller-leader-election-helper","uid":"bf307b9a-829f-478e-9306-68b6c47671fa","apiVersion":"v1","resourceVersion":"871886"}, "reason": "LeaderElection", "message": "kube-api-controller-manager-7d8bb9fc6f-8bmg9_77815cc0-df63-11e9-b8c4-e6f6cfac380f became leader"}
    2019-09-25T07:10:08.211Z	INFO	controller-runtime.controller	Starting workers	{"controller": "apiexamplea", "worker count": 1}
    2019/09/25 07:10:08 fetch New Object: shaowen chen
    

    4. 参考

    • https://book.kubebuilder.io/

    相关文章

    KubeSphere 部署向量数据库 Milvus 实战指南
    探索 Kubernetes 持久化存储之 Longhorn 初窥门径
    征服 Docker 镜像访问限制!KubeSphere v3.4.1 成功部署全攻略
    那些年在 Terraform 上吃到的糖和踩过的坑
    无需 Kubernetes 测试 Kubernetes 网络实现
    Kubernetes v1.31 中的移除和主要变更

    发布评论