加强Kubernetes能力：利用CRD定义多版本资源的实现方式

姚灿武，Rancher 中国研发工程师，拥有 7 年云计算领域经验，热衷开源技术，在云原生相关技术领域拥有丰富的开发和实践经验。

CRD，也就是自定义资源定义（Custom Resource Definition），堪称Kubernetes API里一个极为强大的扩展机制。凭借CRD，用户能够定义属于自己的资源类型，以此来拓展Kubernetes的API以及资源类型。值得一提的是，CRD定义能够用于创建多个版本的资源，这在Kubernetes集群的演变与升级过程中，有着不可小觑的作用。

接下来，我们要聊聊Kubernetes CRD的版本概念及其用法，探讨如何在CRD中定义多版本资源，以及资源数据存储和转换的实现方式。最后，我们还会介绍如何开发CRD webhook，让Kubernetes实现CRD版本兼容。

多版本 CRD

多版本 CRD 是指在 CRD 中定义多个版本的 API，每个版本的 API 可以有自己的规则，这样就可以在不影响旧版本应用程序的情况下，对新版本应用程序进行更新和升级。

要创建多版本 CRD，我们需要定义一个 Custom Resource Definition 对象，该对象包含多个 version 字段。每个 version 字段都有一个 schema，其中包含了自定义资源的属性和规则。

通过一个例子来说明，以下是一个单版本 CRD 示例：

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: foos.sample.webhook.io
spec:
  conversion:
    strategy: None
  group: sample.webhook.io
  names:
    kind: Foo
    listKind: FooList
    plural: foos
    shortNames:
    - foo
    - foos
    singular: foo
  scope: Namespaced
  versions:
  - name: v1
    schema:
      openAPIV3Schema:
        properties:
          apiVersion:
            type: string
          kind:
            type: string
          metadata:
            type: object
        type: object
    served: true
    storage: true

文件中规定版本信息以及资源的名称、类型等信息。通过 kubectl apply 命令，可以将该 CRD 文件应用到 Kubernetes 集群中，从而在集群中创建一个新的资源类型 Foo，例如：

apiVersion: sample.webhook.io/v1
kind: Foo
metadata:
  name: foo-sample

上述自定义资源 Foo 只有一个 v1 版本，如果我们需要更新自定义资源中的某个字段，就需要更新 Foo 的版本，例如更新为 v2 版本，就要在 CRD 文件中添加 v2 版本的定义，例如：

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
    name: foos.sample.webhook.io
spec:
    versions:
    - name: v1
      schema:
        openAPIV3Schema:
          properties:
            apiVersion:
              type: string
            kind:
              type: string
            metadata:
              type: object
          type: object
      served: true
      storage: false
    - name: v2
      schema:
        openAPIV3Schema:
          properties:
            alias:
              type: string
            apiVersion:
              type: string
            kind:
              type: string
            metadata:
              type: object
          type: object
      served: true
      storage: true

在上述 CRD 文件中，我们定义了两个版本，v1 和 v2。v2 相比 v1 新增了一个 alias 字段。

资源数据存储

为确保 Kubernetes 能够正确地将自定义资源持久化到存储中，并且能够正确地从存储中读取和还原自定义资源。CRD 中定义了 spec.versions.storage 字段，用于指示使用哪个版本的 CRD 持久化到存储中。在一个 CRD 定义中，只能有一个版本的 storage 字段的值为 true。

上述例子中，我们定义了两个版本，v1 和 v2。v1 版本 storage 字段为 false，v2 版本 storage 字段为 true，这表明 Kubernetes etcd 中存储的是 v2 版本的资源数据。

那么对于未被选定的版本的数据如何存储呢？以上面foo-sample为例，我们来看下 etcd 中是怎么存储的，结果如下：

/registry/sample.webhook.io/foos/default/foo-sample
{"apiVersion":"sample.webhook.io/v2","kind":"Foo","metadata":{"annotations":{"kubectl.kubernetes.io/last-applied-configuration":"{"apiVersion":"sample.webhook.io/v1","kind":"Foo","metadata":{"annotations":{},"name":"foo-sample","namespace":"default"}}n"},"creationTimestamp":"2023-05-22T09:49:03Z","generation":1,"managedFields":[{"apiVersion":"sample.webhook.io/v1","fieldsType":"FieldsV1","fieldsV1":{"f:metadata":{"f:annotations":{".":{},"f:kubectl.kubernetes.io/last-applied-configuration":{}}}},"manager":"kubectl-client-side-apply","operation":"Update","time":"2023-05-22T09:49:03Z"}],"name":"foo-sample","namespace":"default","uid":"3360f129-31f7-4a3f-8991-7694524d9a78"}}

第一行是foo-sample的 key，第二行是foo-samplejson 格式表示的内容，其中apiVersion为sample.webhook.io/v2，这表明即便 v1 版本的资源也以 v2 版本的格式存储。

数据转换

当自定义资源支持多个版本时，因为只能以某一个版本的格式进行存储，所以需要在存储的版本和提供的版本之间进行转换，实现多版本兼容。

• 如果转换涉及模式变更， 并且需要自定义逻辑，则应该使用 Webhook 来完成。在 CRD 中配置 webhook 示例如下：

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
...
spec:
  conversion:
      strategy: Webhook
      webhook:
          clientConfig:
            caBundle: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUJ2akNDQVdPZ0F3SUJBZ0lCQURBS0JnZ3Foa2pPUFFRREFqQkdNUnd3R2dZRFZRUUtFeE5rZVc1aGJXbGoKYkdsemRHVnVaWEl0YjNKbk1TWXdKQVlEVlFRRERCMWtlVzVoYldsamJHbHpkR1Z1WlhJdFkyRkFNVFk0TkRjegpPRGswTXpBZUZ3MHlNekExTWpJd056QXlNak5hRncwek16QTFNVGt3TnpBeU1qTmFNRVl4SERBYUJnTlZCQW9UCkUyUjVibUZ0YVdOc2FYTjBaVzVsY2kxdmNtY3hKakFrQmdOVkJBTU1IV1I1Ym1GdGFXTnNhWE4wWlc1bGNpMWoKWVVBeE5qZzBOek00T1RRek1Ga3dFd1lIS29aSXpqMENBUVlJS29aSXpqMERBUWNEUWdBRUZYWDQzaEZRdjRyOApKelR1UkJ0b3lqUmRtWjhIRkExbWZnOXJnTWVlNnVXZ20wMXBNR3lSRnFna3Z1RHF5RUlMTUtCRDduQ2IrVFp3CitBR3loVWhTV0tOQ01FQXdEZ1lEVlIwUEFRSC9CQVFEQWdLa01BOEdBMVVkRXdFQi93UUZNQU1CQWY4d0hRWUQKVlIwT0JCWUVGRzg2VnpCcW1wRUcrUWlrS0d1SGNIQlJwS2R3TUFvR0NDcUdTTTQ5QkFNQ0Ewa0FNRVlDSVFDaQp5SFFyeGNXN3dUM0dwRWhyNklQQWpXWDVJOSt4Y0dkUGQzQURKS0hwZ2dJaEFJQmhTc00xd1hxMU80VUlaWWZwCkNWVkxwaCtvUVMvMzI5OHMwS0VqWW9FTAotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCg==
            service:
                name: webhook-sample
                namespace: default
                path: /v1/webhook/conversion
                port: 443
              conversionReviewVersions:
              - v1

• 如果没有模式变更，则可使用默认的None转换策略，为不同版本提供服务时只有apiVersion字段会被改变。

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
...
spec:
  ...
  conversion:
    strategy: None

CRD webhook 开发

与Admission Webhook一样，CRD webhook 也是一个 HTTP 回调，webhook service 就是一个 HTTP 服务。接口结构如下：

// ConversionReview describes a conversion request/response.
type ConversionReview struct {
    meta v1.TypeMeta `json:",inline"`
    // request describes the attributes for the conversion request.
    // +optional
    Request *ConversionRequest `json:"request,omitempty" protobuf:"bytes,1,opt,name=request"`
    // response describes the attributes for the conversion response.
    // +optional
    Response *ConversionResponse `json:"response,omitempty" protobuf:"bytes,2,opt,name=response"`
}

Harvester 项目组在harvester webhook框架中增加了 CRD webhook 的支持，开发者只需要实现Converter接口并把它注册到 webhook server 中，然后启动 webhook server 即可。

// Converter is a interface to convert object to the desired version
type Converter interface {
    GroupResource() schema.GroupResource
    Convert(Object *unstructured.Unstructured, desiredAPIVersion string) (*unstructured.Unstructured, error)
}

具体开发细节请参考示例webhook sample。

总 结

在实际产品进化演变过程中，多版本兼容一直是一个重要的问题。Kubernetes CRD 采用选定某一个版本进行持久化，并使用 webhook 实现多版本数据转换的策略来解决多版本兼容性问题。在 Kubernetes 外的其他项目中，这种策略也值得学习借鉴。

参 考

Versions in Custom Resource Definitions：https://kubernetes.io/zh-cn/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning