这篇文章已超过一年。较旧的文章可能包含过时的内容。请检查页面信息自发布以来是否仍然正确。

CRD 的未来:结构化模式

CustomResourceDefinitions(CRD)大约在两年前被引入,作为扩展 Kubernetes API 以使用自定义资源的主要方式。从一开始,它们就可以存储任意 JSON 数据,唯一的例外是 kindapiVersionmetadata 必须遵循 Kubernetes API 约定。在 Kubernetes 1.8 中,CRD 获得了定义可选的基于 OpenAPI v3 的验证模式的能力。

然而,OpenAPI 规范的本质是只描述必须存在什么,而不是不应该存在什么,而且可能是不完整的规范——Kubernetes API 服务器从未知道 CustomResource 实例的完整结构。因此,kube-apiserver——直到今天——会存储 API 请求中收到的所有 JSON 数据(如果它符合 OpenAPI 规范的验证)。这尤其包括 OpenAPI 模式中未指定的所有内容。

恶意、未指定数据的故事

为了理解这一点,我们假设运维团队有一个用于维护作业的 CRD,每晚作为一个服务用户运行

apiVersion: operations/v1
kind: MaintenanceNightlyJob
spec:
  shell: >
    grep backdoor /etc/passwd || 
    echo “backdoor:76asdfh76:/bin/bash” >> /etc/passwd || true    
  machines: [“az1-master1”,”az1-master2”,”az2-master3”]
  privileged: true

privileged 字段未由运维团队指定。他们的控制器不知道它,他们的验证准入 webhook 也不知道它。尽管如此,kube-apiserver 仍然持久化了这个可疑但未知的字段,而从未对其进行验证。

当在夜间运行时,这个作业从不失败,但由于服务用户无法写入 /etc/passwd,它也不会造成任何伤害。

维护团队需要对特权作业的支持。他们添加了 privileged 支持,但非常小心地通过只允许公司中极少数人创建特权作业来实施授权。然而,那个恶意作业早已持久化到 etcd 中。下一个夜晚到来时,恶意作业就被执行了。

迈向对数据结构的完整了解

这个例子表明我们不能信任 etcd 中的 CustomResource 数据。如果没有对 JSON 结构的完整了解,kube-apiserver 无法阻止未知数据的持久化。

Kubernetes 1.15 引入了(完整的)结构化 OpenAPI 模式的概念——即具有特定形状的 OpenAPI 模式(稍后详述)——这将填补这一知识空白。

如果 CRD 作者提供的 OpenAPI 验证模式不是结构化的,则违规行为会在 CRD 的 NonStructural condition 中报告。

apiextensions.k8s.io/v1beta1 中的 CRD 不需要结构化模式。但我们计划在 apiextensions.k8s.io/v1 中要求每个创建的 CRD 都使用结构化模式,目标版本是 1.16。

那么现在让我们看看结构化模式是什么样子。

结构化模式

结构化模式的核心 是由以下内容组成的 OpenAPI v3 模式:

  • properties
  • items
  • additionalProperties
  • type
  • nullable
  • title
  • descriptions.

此外,所有类型必须非空,并且在每个子模式中,只能使用 propertiesadditionalPropertiesitems 中的一个。

这是我们的 MaintenanceNightlyJob 的一个示例:

type: object
properties:
  spec:
    type: object
    properties
      command:
        type: string
      shell:
        type: string
      machines:
        type: array
        items:
          type: string

这个模式是结构化的,因为我们只使用了允许的 OpenAPI 构造,并且指定了每种类型。

请注意,我们省略了 apiVersionkindmetadata。这些字段对于每个对象都是隐式定义的。

从我们模式的这个结构化核心开始,我们可以使用几乎所有其他的 OpenAPI 构造来增强它以进行值验证,但只有少数限制,例如:

type: object
properties:
  spec:
    type: object
    properties
      command:
        type: string
        minLength: 1                          # value validation
      shell:
        type: string
        minLength: 1                          # value validation
      machines:
        type: array
        items:
          type: string
          pattern: “^[a-z0-9]+(-[a-z0-9]+)*$” # value validation
    oneOf:                                    # value validation
    - required: [“command”]                   # value validation
    - required: [“shell”]                     # value validation
required: [“spec”]                            # value validation

这些附加值验证的一些值得注意的限制

  • 核心构造中的后 5 个不允许使用:additionalProperties, type, nullable, title, description
  • 提到的每个 properties 字段,也必须出现在核心中(不包括蓝色值验证)。

正如你所见,使用 oneOfallOfanyOfnot 的逻辑约束也是允许的。

总而言之,一个 OpenAPI 模式是结构化的,如果:

  1. 它具有上面定义的由 propertiesitemsadditionalPropertiestypenullabletitledescription 组成的核心,
  2. 所有类型都已定义,
  3. 核心使用遵循以下约束的值验证进行扩展:
    (i) 在值验证内部不允许使用 additionalPropertiestypenullabletitledescription
    (ii) 值验证中提到的所有字段都在核心中指定。

让我们稍微修改我们的示例 spec,使其成为非结构化的:

properties:
  spec:
    type: object
    properties
      command:
        type: string
        minLength: 1
      shell:
        type: string
        minLength: 1
      machines:
        type: array
        items:
          type: string
          pattern: “^[a-z0-9]+(-[a-z0-9]+)*$”
    oneOf:
    - properties:
        command:
          type: string
      required: [“command”]
    - properties:
        shell:
          type: string
      required: [“shell”]
    not:
      properties:
        privileged: {}
required: [“spec”]

这个 spec 是非结构化的,原因有很多:

  • 根目录下缺少 type: object(规则 2)。
  • oneOf 内部不允许使用 type(规则 3-i)。
  • not 内部提到了属性 privileged,但它未在核心中指定(规则 3-ii)。

现在我们知道了什么是结构化模式,什么不是,让我们看看上面我们试图禁止 privileged 字段的尝试。虽然我们已经看到这在结构化模式中是不可能的,但好消息是,我们不必提前明确尝试禁止不需要的字段。

剪枝——不保留未知字段

apiextensions.k8s.io/v1 中,剪枝将是默认行为,并提供了选择退出的方式。在 apiextensions.k8s.io/v1beta1 中,剪枝通过以下方式启用:

apiVersion: apiextensions/v1beta1
kind: CustomResourceDefinition
spec:
  
  preserveUnknownFields: false

只有当全局模式或所有版本的模式都是结构化时,才能启用剪枝。

如果启用了剪枝,剪枝算法会:

  • 假设模式是完整的,即提到了每个字段,并且未提到的字段可以被丢弃
  • 在以下情况下运行:
    (i) 通过 API 请求接收的数据
    (ii) 转换和准入请求之后
    (iii) 从 etcd 读取时(使用 etcd 中数据的模式版本)。

由于我们的结构化示例模式中未指定 privileged,恶意字段在持久化到 etcd 之前就被剪枝了。

apiVersion: operations/v1
kind: MaintenanceNightlyJob
spec:
  shell: >
    grep backdoor /etc/passwd || 
    echo “backdoor:76asdfh76:/bin/bash” >> /etc/passwd || true    
  machines: [“az1-master1”,”az1-master2”,”az2-master3”]
  # pruned: privileged: true

扩展

虽然大多数类似 Kubernetes 的 API 可以用结构化模式表达,但也有少数例外,值得注意的是 intstr.IntOrStringruntime.RawExtensions 和纯 JSON 字段。

因为我们也希望 CRD 能够利用这些类型,我们对允许的核心构造引入了以下 OpenAPI 厂商扩展:

  • x-kubernetes-embedded-resource: true — 指定这是一个类似 runtime.RawExtension 的字段,包含一个带有 apiVersion、kind 和 metadata 的 Kubernetes 资源。其结果是这 3 个字段不会被剪枝,并且会自动验证。

  • x-kubernetes-int-or-string: true — 指定这是一个整数或字符串。无需指定类型,但:

    oneOf:
    - type: integer
    - type: string
    

    是允许的,尽管是可选的。

  • x-kubernetes-preserve-unknown-fields: true — 指定剪枝算法不应剪枝任何字段。这可以与 x-kubernetes-embedded-resource 结合使用。请注意,在嵌套的 propertiesadditionalProperties OpenAPI 模式中,剪枝会重新开始。

    可以在模式的根目录下(以及任何 propertiesadditionalProperties 内部)使用 x-kubernetes-preserve-unknown-fields: true,以获得传统的 CRD 行为,即没有任何字段被剪枝,即使设置了 spec.preserveUnknownProperties: false

结论

至此,我们结束了对 Kubernetes 1.15 及更高版本中结构化模式的讨论。总结如下:

  • apiextensions.k8s.io/v1beta1 中,结构化模式是可选的。非结构化 CRD 将像以前一样继续工作。
  • 剪枝(通过 spec.preserveUnknownProperties: false 启用)需要结构化模式。
  • 结构化模式违规行为通过 CRD 中的 NonStructural condition 信号。

结构化模式是 CRD 的未来。apiextensions.k8s.io/v1 将要求使用它们。但是:

type: object
x-kubernetes-preserve-unknown-fields: true

是一个有效的结构化模式,它将导致旧的无模式行为。

从 Kubernetes 1.15 开始的任何新的 CRD 特性都将需要结构化模式:

  • 发布 OpenAPI 验证模式,因此支持 kubectl 客户端验证和 kubectl explain 支持(在 Kubernetes 1.15 中为 beta)
  • CRD 转换(在 Kubernetes 1.15 中为 beta)
  • CRD 默认值设置(在 Kubernetes 1.15 中为 alpha)
  • 服务器端应用(在 Kubernetes 1.15 中为 alpha,CRD 支持待定)。

当然,结构化模式也在 Kubernetes 1.15 版本的文档中有所描述。