加强 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-sample json 格式表示的内容，其中 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 {
    metav1.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