Kubernetes CRD

在 kubernetes 中有一系列内置的资源，诸如：pod、deployment、configmap、service …… 等等，它们由 k8s 的内部组件管理。而除了这些内置资源之外，k8s 还提供了另外一种方式让用户可以随意地自定义资源，这就是 CRD (全称 CustomResourceDefinitions) 。

例如，我可以通过 CRD 去定义一个 mypod、myjob、myanything 等等资源，一旦注册成功，那么这些自定义资源便会享受与内置资源相同的待遇。具体而言就是：

• • 我们可以像使用 kubectl 增删改查 deployment 一样去操作这些 CRD 自定义资源。

• • CRD 自定义资源的数据跟 pod 等内置资源一样会存储到 k8s 控制平面的 etcd 中。

需要注意的是，CRD 在不同的语境下有不同的含义，有时候可能只是指 k8s 中的 CustomResourceDefinitions 这一种特定的资源，有时候也可能是指用户通过 CRD 所创建出来的自定义资源。

狭义上的 CRD (全称 CustomResourceDefinitions) 是 k8s 中的一种特殊的内置资源，我们可以通过它去创建我们自定义的其它资源。例如，我们可以通过 CRD 去创建一个叫 CronTab 的资源：

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  # 名称必须匹配 <plural>.<group>
  name: crontabs.stable.example.com
spec:
  # group 名称，用于 REST API: /apis/<group>/<version>
  group: stable.example.com
  versions:
    - name: v1
      served: true
      storage: true
      schema:
        openAPIV3Schema:
          type: object
          properties:
            # 定义属性
            spec:
              type: object
              properties:
                cronSpec:
                  type: string
                image:
                  type: string
  # 作用范围可以是 Namespaced 或者 Cluster
  scope: Namespaced
  names:
    # 复数名称，使用于 URL: /apis/<group>/<version>/<plural>
    plural: crontabs
    # 单数名称，可用于 CLI
    singular: crontab
    # 驼峰单数，用于资源清单
    kind: CronTab
    # 名字简写，可用于 CLI
    shortNames:
    - ct

一旦我们 apply 这个 yaml 文件，那么我们的自定义资源 CronTab 也就注册到 k8s 了。这个时候我们就可以任意操作这个自定义资源，比如 my-crontab.yaml:

apiVersion: "stable.example.com/v1"
kind: CronTab
metadata:
  name: my-new-cron-object
spec:
  cronSpec: "* * * * */5"
  image: my-awesome-cron-image

执行 kubectl apply -f my-crontab.yaml 就可以创建我们自定义的 CronTab，执行 kubectl get crontab 就可以查询到我们自定义的 CronTab 列表。

通过 CRD 自定义资源的优点是，我们无需操心自定义资源的数据存储，也无需再额外实现一个 http server 去对外暴露操作这些自定义资源的 API 接口，因为这些 k8s 都帮我们做好了，我们只需要像其它内置资源一样使用自定义资源即可。

但是！只有 CRD 往往是不够的，例如上文中我们执行 kubectl apply -f my-crontab.yaml 创建了一个 crontab 自定义资源，但是这个 crontab 不会有任何执行的内容（不会跑任何程序），而很多场景下我们是希望自定义资源能够执行点什么。这个时候我们就需要 Operator 了。

Operator

Operator 其实就是 custom resource controller（自定义资源的控制器），它干的事情就是监听自定义资源的变更，然后针对性地做一些操作。例如，监听到某个自定义资源被创建后，Operator 可以读取这个自定义资源的属性然后创建一个 pod 去运行具体的程序，并将这个 pod 绑定到自定义资源对象上。

那 Operator 以何种方式存在呢？其实它跟普通的服务一样，可以是 deployment，也可以是 statefuleSet。

至于常说的 Operator pattern 其实就是 CRD + custom controller 这种模式。

Kubebuilder

我们在构建项目时常常希望有一个好用的框架，能够提供一系列工具帮助开发者更轻松地进行创建、测试和部署。而针对 CRD 和 Operator 的场景就有这么一个框架 Kubebuilder。

接下来我将会使用 Kubebuilder 创建一个小项目，其中会创建一个自定义资源 Foo ，并在 controller 中监听这个资源的变更并把它打印出来。

1. 安装

# download kubebuilder and install locally.
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 kubebuilder-test
cd kubebuilder-test

3. 初始化项目

kubebuilder init --domain mytest.domain --repo mytest.domain/foo

4. 定义 CRD

假设我们想要定义一个如下格式的 CRD：

apiVersion: "mygroup.mytest.domain/v1"
kind: Foo
metadata:
  name: xxx
spec:
  image: image
  msg: message

那么我们需要创建一个 CRD（本质上也是创建一个 API ）：

kubebuilder create api --group mygroup --version v1 --kind Foo

执行之后输入 y 确认生成，然后 kubebuilder 会帮我们自动创建一些目录和文件，其中：

• • api/v1/foo_types.go 文件中定义了这个 CRD（也是 API）。

• • internal/controllers/foo_controller.go 文件则是控制 CRD 的业务逻辑。

由于自动生成的文件只是一个基本框架，我们需要按照自己的需求进行相应的修改。

a. 在代码中修改 CRD 的结构

首先，修改 api/v1/foo_types.go 调整 CRD 的结构（注意不要删除 //+kubebuilder 这种注释）：

// FooSpec defines the desired state of Foo
type FooSpec struct {
    Image string `json:"image"`
    Msg   string `json:"msg"`
}

// FooStatus defines the observed state of Foo
type FooStatus struct {
    PodName string `json:"podName"`
}

b. 通过命令自动生成 CRD yaml

执行 make manifests 命令之后，kubebuilder 就会在 config/crd/bases 目录下生成一个 mygroup.mytest.domain_foos.yaml 文件，这个文件就是我们定义 CRD 的 yaml 文件：

---
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  annotations:
    controller-gen.kubebuilder.io/version: v0.13.0
  name: foos.mygroup.mytest.domain
spec:
  group: mygroup.mytest.domain
  names:
    kind: Foo
    listKind: FooList
    plural: foos
    singular: foo
  scope: Namespaced
  versions:
  - name: v1
    schema:
      openAPIV3Schema:
        description: Foo is the Schema for the foos API
        properties:
          apiVersion:
            description: 'APIVersion defines the versioned schema of this representation
              of an object. Servers should convert recognized schemas to the latest
              internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources'
            type: string
          kind:
            description: 'Kind is a string value representing the REST resource this
              object represents. Servers may infer this from the endpoint the client
              submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds'
            type: string
          metadata:
            type: object
          spec:
            description: FooSpec defines the desired state of Foo
            properties:
              image:
                type: string
              msg:
                type: string
            required:
            - image
            - msg
            type: object
          status:
            description: FooStatus defines the observed state of Foo
            properties:
              podName:
                type: string
            required:
            - podName
            type: object
        type: object
    served: true
    storage: true
    subresources:
      status: {}

make manifests 指令执行的具体内容定义在了 Makefile 文件中：

.PHONY: manifests
manifests: controller-gen ## Generate WebhookConfiguration, ClusterRole and CustomResourceDefinition objects.
    $(CONTROLLER_GEN) rbac:roleName=manager-role crd webhook paths="./..." output:crd:artifacts:config=config/crd/bases

从中可以看到其实 kubebuilder 使用了 controller-gen 工具去扫描代码中特定格式的注释（如 //+kubebuilder:...）进而生成的 CRD yaml 文件。

5. 补充 controller 逻辑

假设我们要监听用户创建的自定义资源 Foo 然后把它的属性打印出来。

a. 修改 controller 补充业务逻辑

修改 internal/controllers/foo_controller.go 文件补充我们自己的业务逻辑，如下：

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

    // 补充业务逻辑
    foo := &mygroupv1.Foo{}
    if err := r.Get(ctx, req.NamespacedName, foo); err != nil {
        l.Error(err, "unable to fetch Foo")
        return ctrl.Result{}, client.IgnoreNotFound(err)
    }

    // 打印 Foo 属性
    l.Info("Received Foo", "Image", foo.Spec.Image, "Msg", foo.Spec.Msg)

    return ctrl.Result{}, nil
}

// SetupWithManager sets up the controller with the Manager.
func (r *FooReconciler) SetupWithManager(mgr ctrl.Manager) error {
    return ctrl.NewControllerManagedBy(mgr).
        For(&mygroupv1.Foo{}).
        Complete(r)
}

b. 进行测试

注意：测试需要有本地或远程的 k8s 集群环境，其将会默认使用跟当前 kubectl 一致的环境。

执行 make install 注册 CRD ，从 Makefile 中可以看到其实际执行了如下指令：

.PHONY: install
install: manifests kustomize ## Install CRDs into the K8s cluster specified in ~/.kube/config.
    $(KUSTOMIZE) build config/crd | $(KUBECTL) apply -f -

执行 make run 运行 controller，从 Makefile 中可以看到其实际执行了如下指令：

.PHONY: run
run: manifests generate fmt vet ## Run a controller from your host.
    go run ./cmd/main.go

然后可以看到如下输出：

...
go fmt ./...
go vet ./...
go run ./cmd/main.go
2023-12-19T15:14:18+08:00       INFO    setup   starting manager
2023-12-19T15:14:18+08:00       INFO    controller-runtime.metrics      Starting metrics server
2023-12-19T15:14:18+08:00       INFO    starting server {"kind": "health probe", "addr": "[::]:8081"}
2023-12-19T15:14:18+08:00       INFO    controller-runtime.metrics      Serving metrics server  {"bindAddress": ":8080", "secure": false}
2023-12-19T15:14:18+08:00       INFO    Starting EventSource    {"controller": "foo", "controllerGroup": "mygroup.mytest.domain", "controllerKind": "Foo", "source": "kind source: *v1.Foo"}
2023-12-19T15:14:18+08:00       INFO    Starting Controller     {"controller": "foo", "controllerGroup": "mygroup.mytest.domain", "controllerKind": "Foo"}
2023-12-19T15:14:19+08:00       INFO    Starting workers        {"controller": "foo", "controllerGroup": "mygroup.mytest.domain", "controllerKind": "Foo", "worker count": 1}

我们提交一个 foo.yaml 试试：

apiVersion: "mygroup.mytest.domain/v1"
kind: Foo
metadata:
  name: test-foo
spec:
  image: test-image
  msg: test-message

执行 kubectl apply -f foo.yaml 之后我们就会在 controller 的输出中看到 foo 被打印了出来：

2023-12-19T15:16:00+08:00       INFO    Received Foo    {"controller": "foo", "controllerGroup": "mygroup.mytest.domain", "controllerKind": "Foo", "Foo": {"name":"test-foo","namespace":"aries"}, "namespace": "aries", "name": "test-foo", "reconcileID": "8dfd629e-3081-4d40-8fc6-bcc3e81bbb39", "Image": "test-image", "Msg": "test-message"}

这就是使用 kubebuilder 的一个简单示例。

总结

Kubernetes 的 CRD 和 Operator 机制为用户提供了强大的扩展性。CRD 允许用户自定义资源，而 Operators 则可以管理这些资源。正是这种扩展机制为 Kubernetes 生态系统提供了极大的灵活性和可塑性，使得它可以更广泛的应用于各种场景中。

---

参考资料：

• • https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/

• • https://kubernetes.io/docs/concepts/extend-kubernetes/operator/

• • https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/

• • https://book.kubebuilder.io/introduction