CRD 的未来：结构化模式

大约两年前引入的 CustomResourceDefinitions (CRD) 是通过自定义资源扩展 Kubernetes API 的主要方式。从一开始，它们就存储任意 JSON 数据，但有一个例外，即 kind、apiVersion 和 metadata 必须遵循 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

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

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

维护团队需要特权作业的支持。它添加了 privileged 支持，但在实现特权作业授权时非常小心，只允许公司中极少数人创建它们。然而，那个恶意作业早已被持久化到 etcd 中。第二天晚上到来，恶意作业被执行。

迈向数据结构的完整知识

这个例子表明我们不能信任 etcd 中的 CustomResource 数据。如果不知道完整的 JSON 结构，kube-apiserver 无法采取任何措施来阻止未知数据的持久化。

Kubernetes 1.15 引入了（完整）结构化 OpenAPI 模式的概念——一个具有特定形状的 OpenAPI 模式，稍后将详细介绍——它将填补这一知识空白。

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

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

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

结构化模式

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

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

此外，所有类型都必须是非空的，并且在每个子模式中，只能使用 properties、additionalProperties 或 items 中的一个。

这是我们的 MaintenanceNightlyJob 的一个示例

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

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

请注意，我们省略了 apiVersion、kind 和 metadata。这些是为每个对象隐式定义的。

从我们模式的这个结构化核心开始，我们可以使用几乎所有其他 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
• 提及的每个属性字段也必须出现在核心中（不带蓝色值验证）。

如您所见，也允许使用 oneOf、allOf、anyOf、not 的逻辑约束。

总而言之，如果 OpenAPI 模式满足以下条件，则它是结构化的：

1. 它具有上述由 properties、items、additionalProperties、type、nullable、title、description 组成的核心，
   
2. 所有类型都已定义，
   
3. 核心通过遵循约束的值验证进行扩展
   (i) 在值验证内部没有 additionalProperties、type、nullable、title、description
   (ii) 值验证中提及的所有字段都在核心中指定。

让我们稍微修改一下我们的示例规范，使其非结构化

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”]

此规范非结构化的原因有很多

• 根目录缺少 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.IntOrString、runtime.RawExtension 和纯 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 结合使用。请注意，在嵌套的 properties 或 additionalProperties OpenAPI 模式中，修剪会重新开始。

  可以在模式的根部（以及任何 properties、additionalProperties 内部）使用 x-kubernetes-preserve-unknown-fields: true，以获得传统的 CRD 行为，即没有任何内容被修剪，即使设置了 spec.preserveUnknownProperties: false。

结论

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

• 结构化模式在 apiextensions.k8s.io/v1beta1 中是可选的。非结构化 CRD 将继续像以前一样工作。
• 修剪（通过 spec.preserveUnknownProperties: false 启用）需要结构化模式。
• 结构化模式违规通过 CRD 中的 NonStructural 条件进行信号通知。

结构化模式是 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 版本的 Kubernetes 文档中也描述了结构化模式。

• ←上一篇
• 下一篇→