Kubernetes CRD 系列(一)：CRD 介绍

CR（Custom Resource）其实就是在 Kubernetes 中定义一个自己的资源类型，是一个具体的 “自定义 API 资源” 实例，为了能够让 Kubernetes 认识这个 CR，就需要让 Kubernetes 明白这个 CR 的宏观定义是什么，也就是需要创建所谓的 CRD（Custom Resource Definition）来表述。

可能这么说并不是太直观，换个方式表达一下，我们想要创建一个 Pod 的时候，那么会编写一个 YAML 配置，然后前两行一般会这么写：

[root@liqiang.io]# head -2 pod.yaml
apiVersion: v1
kind: Pod

这里的 Resource 就是 Pod，我们可以它通过在 Kubernetes 中创建一个真实的 Pod，但是这个 Pod 要运行哪些 Container？这些 Container 我们要怎么在 pod.yaml 中定义，这个要怎么知道呢？这就需要有个描述文件用来定义 Pod 这个 Resource 需要具有哪些属性，这些属性的类型是什么，结构是怎样的，这个描述文件就是所谓的 CRD。

当然，Pod 作为一个内置资源，是没有这种所谓的 CRD 的，这里是作为一个介绍，当我们要创建一个非内置资源的时候，就需要有这么一个叫做 CRD 的描述文件了。

创建 CRD

在 Kubernetes 中，CRD 本身也是一种资源，它是 Kubernetes 内部 apiextensions-apiserver 提供的 API Group：apiextensions.k8s.io/v1，注意，这里是 v1 版本，在 Kubernetes 1.16 版本中，CRD 转正了，成为了正式版本 CRD GA，但是，在 v1.16 之前以及 v1.7 以及之后，都是以 v1beta1 的版本存在，所以在编写的时候注意一下你的 Kubernetes 版本。

自己定义一个 CRD 也需要编写 YAML 文件，这里是我的一个示例，我通过这个 CRD 来定义我的网站 liqiang.io 的管理员的 CR，当我想添加一个管理员的时候，只需要直接添加一个 CR 就可以了：

---
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: admins.admin.liqiang.io
spec:
  group: admin.liqiang.io
  names:
    kind: Admin
    plural: admins
  scope: Namespaced
  versions:
    - name: v1
      served: true
      storage: true
      schema:
        openAPIV3Schema:
          description: Admin define the admin user for liqiang.io website.
          type: object
          properties:
            spec:
              type: object
              properties:
                username:
                  type: string
                password:
                  type: string
                email:
                  type: string

当写完这个 CRD 的描述文件之后，可以直接通过 kubectl apply 00-admin-crd.yaml 在 Kubernetes 集群中注册 CRD 对象。然后 Kubernetes 中的 kube-apiserver 组件中运行的 apiextensions-apiserver 就会检查对应 CRD 的名字是否合法之类的，当一切检查都 OK 之后，那么就会返回给你创建成功的状态了：

[root@liqiang.io]#  kubectl apply -f 00-admin-crd.yaml
customresourcedefinition.apiextensions.k8s.io/admins.admin.liqiang.io created
k get crds
NAME                            CREATED AT
admins.admin.liqiang.io         2019-11-23T06:52:23Z

内部的流程是这样的：

操作 CRD

现在在 Kubernetes 中已经多了一种新的资源叫做 admins.admin.liqiang.io，可以使用它来定义系统的管理员了，这里我就添加一个：

记得，需要 apply 一下：

[root@liqiang.io]# kubectl apply -f 01-admin-cr.yaml 
admin.admin.liqiang.io/liuliqiang created
[root@liqiang.io]#  kubectl get admins.admin.liqiang.io 
NAME         AGE
liuliqiang   117s

现在就创建成功了。然后，不要了，那就删除掉，删除也是很简单的：

[root@liqiang.io]#  kubectl delete admins.admin.liqiang.io liuliqiang 
admin.admin.liqiang.io "liuliqiang" deleted
[root@liqiang.io]#  kubectl get admins.admin.liqiang.io
No resources found in default namespace.

这个新建和删除 Admin 的过程虽然用得挺简单，但是，事实上，他们除了把 Kubernetes 当作一个 DB 之外，没有太多的实际价值。他们更多的价值体现在我后续介绍的 Controller 和 Operator 之上。所以，管理 CRD 的定义以及使用的基本内容就是这么多了，非常简单。

其他笔记

Kubectl 发现机制

在我创建完 CRD 之后，kubectl 会通过 API 服务器的 discovery information 来查找关于新资源的信息，下面展示当使用 kubectl 获取一个 CR 时，内部的流程：

这个过程是通过 discovery RESTMapper 实现的，关于 RESTMapper 我在后面会继续介绍。

校验 CR

创建资源的时候，肯定不是任由我们随意得编写 YAML 声明文件，当提交给 Kubernetes 之后，Kubernetes 会对我们提交得声明文件进行校验，从前边 CRD 的定义中可以看到，CRD 是基于 OpenAPI v3 schema 进行的。

同时也可以看到，这种校验是比较初级的，比较简略的。如果想要实现更加复杂的校验，那么可以通过 Kubernetes 的 admission webhook 来实现，这个在我介绍 Istio 的时候有介绍过，如果没印象，不妨找来看看。

Adminssion webhook 的内部校验流程是这样的：

简称和属性

当我输入 kubectl api-resources 的时候，可以看到我定义的 CRD 和一些内置的 Resource 还是有一些区别的，例如内置的 Service 有简写： svc，那么 CRD 是否可以有简写，答案是肯定的：

如果通过 kubectl get all 来列举所有的资源，然后会发现并不会看到自己的 CRD，如果想要让自己的 CRD 对应的 CR 出现在 get all 中，那么可以在 CRD 的声明中加入 categories 属性：

自定义列

当我用 kubectl get admins.admin.liqiang.io 查看 CR 的时候，只能看到简单的 NAME 和 AGE，如果需要看到更多该怎么处理：

子资源

We briefly mentioned subresources in “Status Subresources: UpdateStatus”. Subresources are special HTTP endpoints, using a suffix appended to the HTTP path of the normal resource. For example, the pod standard HTTP path is /api/v1/namespace/namespace/pods/name. Pods have a number of subresources, such as /logs, /portforward, /exec, and /status.

Ref

• Programming Kubernetes
• Kubernetes Docs: Extend the Kubernetes API with CustomResourceDefinitions
• Kubernetes Docs: Custom Resources