使用 CustomResourceDefinition 扩展 Kubernetes API

本页展示如何使用 CustomResourceDefinition定制资源(Custom Resource) 安装到 Kubernetes API 上。

Before you begin

你必须拥有一个 Kubernetes 的集群,同时你的 Kubernetes 集群必须带有 kubectl 命令行工具。 建议在至少有两个节点的集群上运行本教程,且这些节点不作为控制平面主机。 如果你还没有集群,你可以通过 Minikube 构建一个你自己的集群,或者你可以使用下面任意一个 Kubernetes 工具构建:

Your Kubernetes server must be at or later than version 1.16. To check the version, enter kubectl version.

如果你在使用较老的、仍处于被支持范围的 Kubernetes 版本,请切换到该版本的 文档查看对于的集群而言有用的建议。

创建 CustomResourceDefinition

当你创建新的 CustomResourceDefinition(CRD)时,Kubernetes API 服务器会为你所 指定的每一个版本生成一个 RESTful 的 资源路径。CRD 可以是名字空间作用域的,也可以 是集群作用域的,取决于 CRD 的 scope 字段设置。和其他现有的内置对象一样,删除 一个名字空间时,该名字空间下的所有定制对象也会被删除。CustomResourceDefinition 本身是不受名字空间限制的,对所有名字空间可用。

例如,如果你将下面的 CustomResourceDefinition 保存到 resourcedefinition.yaml 文件:

  1. apiVersion: apiextensions.k8s.io/v1
  2. kind: CustomResourceDefinition
  3. metadata:
  4. # 名字必需与下面的 spec 字段匹配,并且格式为 '<名称的复数形式>.<组名>'
  5. name: crontabs.stable.example.com
  6. spec:
  7. # 组名称,用于 REST API: /apis/<组>/<版本>
  8. group: stable.example.com
  9. # 列举此 CustomResourceDefinition 所支持的版本
  10. versions:
  11. - name: v1
  12. # 每个版本都可以通过 served 标志来独立启用或禁止
  13. served: true
  14. # 其中一个且只有一个版本必需被标记为存储版本
  15. storage: true
  16. schema:
  17. openAPIV3Schema:
  18. type: object
  19. properties:
  20. spec:
  21. type: object
  22. properties:
  23. cronSpec:
  24. type: string
  25. image:
  26. type: string
  27. replicas:
  28. type: integer
  29. # 可以是 Namespaced 或 Cluster
  30. scope: Namespaced
  31. names:
  32. # 名称的复数形式,用于 URL:/apis/<组>/<版本>/<名称的复数形式>
  33. plural: crontabs
  34. # 名称的单数形式,作为命令行使用时和显示时的别名
  35. singular: crontab
  36. # kind 通常是单数形式的帕斯卡编码(PascalCased)形式。你的资源清单会使用这一形式。
  37. kind: CronTab
  38. # shortNames 允许你在命令行使用较短的字符串来匹配资源
  39. shortNames:
  40. - ct

之后创建它:

  1. kubectl apply -f resourcedefinition.yaml

这样一个新的受名字空间约束的 RESTful API 端点会被创建在:

  1. /apis/stable.example.com/v1/namespaces/*/crontabs/...

此端点 URL 自此可以用来创建和管理定制对象。对象的 kind 将是来自你上面创建时 所用的 spec 中指定的 CronTab

创建端点的操作可能需要几秒钟。你可以监测你的 CustomResourceDefinition 的 Established 状况变为 true,或者监测 API 服务器的发现信息等待你的资源出现在 那里。

创建定制对象

在创建了 CustomResourceDefinition 对象之后,你可以创建定制对象(Custom Objects)。定制对象可以包含定制字段。这些字段可以包含任意的 JSON 数据。 在下面的例子中,在类别为 CrontTab 的定制对象中,设置了cronSpecimage 定制字段。类别 CronTab 来自你在上面所创建的 CRD 的规约。

如果你将下面的 YAML 保存到 my-crontab.yaml

  1. apiVersion: "stable.example.com/v1"
  2. kind: CronTab
  3. metadata:
  4. name: my-new-cron-object
  5. spec:
  6. cronSpec: "* * * * */5"
  7. image: my-awesome-cron-image

并执行创建命令:

  1. kubectl apply -f my-crontab.yaml

你就可以使用 kubectl 来管理你的 CronTab 对象了。例如:

  1. kubectl get crontab

应该会输出如下列表:

  1. NAME AGE
  2. my-new-cron-object 6s

使用 kubectl 时,资源名称是大小写不敏感的,而且你既可以使用 CRD 中所定义的单数 形式或复数形式,也可以使用其短名称:

  1. kubectl get ct -o yaml

你可以看到输出中包含了你创建定制对象时在 YAML 文件中指定的定制字段 cronSpecimage

  1. apiVersion: v1
  2. items:
  3. - apiVersion: stable.example.com/v1
  4. kind: CronTab
  5. metadata:
  6. annotations:
  7. kubectl.kubernetes.io/last-applied-configuration: |
  8. {"apiVersion":"stable.example.com/v1","kind":"CronTab","metadata":{"annotations":{},"name":"my-new-cron-object","namespace":"default"},"spec":{"cronSpec":"* * * * */5","image":"my-awesome-cron-image"}}
  9. creationTimestamp: "2021-06-20T07:35:27Z"
  10. generation: 1
  11. name: my-new-cron-object
  12. namespace: default
  13. resourceVersion: "1326"
  14. uid: 9aab1d66-628e-41bb-a422-57b8b3b1f5a9
  15. spec:
  16. cronSpec: '* * * * */5'
  17. image: my-awesome-cron-image
  18. kind: List
  19. metadata:
  20. resourceVersion: ""
  21. selfLink: ""

删除 CustomResourceDefinition

当你删除某 CustomResourceDefinition 时,服务器会卸载其 RESTful API 端点,并删除服务器上存储的所有定制对象。

  1. kubectl delete -f resourcedefinition.yaml
  2. kubectl get crontabs
  1. Error from server (NotFound): Unable to list {"stable.example.com" "v1" "crontabs"}: the server could not find the requested resource (get crontabs.stable.example.com)

如果你在以后创建相同的 CustomResourceDefinition 时,该 CRD 会是一个空的结构。

设置结构化的模式

CustomResource 对象在定制字段中保存结构化的数据,这些字段和内置的字段 apiVersionkindmetadata 等一起存储,不过内置的字段都会被 API 服务器隐式完成合法性检查。有了 OpenAPI v3.0 检查 能力之后,你可以设置一个模式(Schema),在创建和更新定制对象时,这一模式会被用来 对对象内容进行合法性检查。参阅下文了解这类模式的细节和局限性。

apiextensions.k8s.io/v1 版本中,CustomResourceDefinition 的这一结构化模式 定义是必需的。 在 CustomResourceDefinition 的 beta 版本中,结构化模式定义是可选的。

结构化模式本身是一个 OpenAPI v3.0 验证模式,其中:

  1. 为对象根(root)设置一个非空的 type 值(藉由 OpenAPI 中的 type),对每个 object 节点的每个字段(藉由 OpenAPI 中的 propertiesadditionalProperties)以及 array 节点的每个条目(藉由 OpenAPI 中的 items)也要设置非空的 type 值, 除非:
    • 节点包含属性 x-kubernetes-int-or-string: true
    • 节点包含属性 x-kubernetes-preserve-unknown-fields: true
  2. 对于 object 的每个字段或 array 中的每个条目,如果其定义中包含 allOfanyOfoneOfnot,则模式也要指定这些逻辑组合之外的字段或条目(试比较例 1 和例 2)。
  3. allOfanyOfoneOfnot 上下文内不设置 descriptiontypedefaultadditionalProperties 或者 nullable。此规则的例外是 x-kubernetes-int-or-string 的两种模式(见下文)。
  4. 如果 metadata 被设置,则只允许对 metadata.namemetadata.generateName 设置约束。

非结构化的例 1:

  1. allOf:
  2. - properties:
  3. foo:
  4. ...

违反了第 2 条规则。下面的是正确的:

  1. properties:
  2. foo:
  3. ...
  4. allOf:
  5. - properties:
  6. foo:
  7. ...

非结构化的例 2:

  1. allOf:
  2. - items:
  3. properties:
  4. foo:
  5. ...

违反了第 2 条规则。下面的是正确的:

  1. items:
  2. properties:
  3. foo:
  4. ...
  5. allOf:
  6. - items:
  7. properties:
  8. foo:
  9. ...

非结构化的例 3:

  1. properties:
  2. foo:
  3. pattern: "abc"
  4. metadata:
  5. type: object
  6. properties:
  7. name:
  8. type: string
  9. pattern: "^a"
  10. finalizers:
  11. type: array
  12. items:
  13. type: string
  14. pattern: "my-finalizer"
  15. anyOf:
  16. - properties:
  17. bar:
  18. type: integer
  19. minimum: 42
  20. required: ["bar"]
  21. description: "foo bar object"

不是一个结构化的模式,因为其中存在以下违例:

  • 根节点缺失 type 设置(规则 1)
  • foo 的 type 缺失(规则 1)
  • anyOf 中的 bar 未在外部指定(规则 2)
  • bartype 位于 anyOf 中(规则 3)
  • anyOf 中设置了 description (规则 3)
  • metadata.finalizers 不可以被限制 (规则 4)

作为对比,下面的 YAML 所对应的模式则是结构化的:

  1. type: object
  2. description: "foo bar object"
  3. properties:
  4. foo:
  5. type: string
  6. pattern: "abc"
  7. bar:
  8. type: integer
  9. metadata:
  10. type: object
  11. properties:
  12. name:
  13. type: string
  14. pattern: "^a"
  15. anyOf:
  16. - properties:
  17. bar:
  18. minimum: 42
  19. required: ["bar"]

如果违反了结构化模式规则,CustomResourceDefinition 的 NonStructural 状况中 会包含报告信息。

字段剪裁

CustomResourceDefinition 在集群的持久性存储 etcd 中保存经过合法性检查的资源数据。 就像原生的 Kubernetes 资源,例如 ConfigMap, 如果你指定了 API 服务器所无法识别的字段,则该未知字段会在保存资源之前 被 剪裁(Pruned) 掉(删除)。

Note:

apiextensions.k8s.io/v1beta1 转换到 apiextensions.k8s.io/v1 的 CRD 可能没有结构化的模式定义,因此其 spec.preserveUnknownFields 可能为 true

对于使用 apiextensions.k8s.io/v1beta1 且将 spec.preserveUnknownFields 设置为 true 创建的旧 CustomResourceDefinition 对象,有以下表现:

  • 裁剪未启用。
  • 可以存储任意数据。

为了与 apiextensions.k8s.io/v1 兼容,将你的自定义资源定义更新为:

  1. 使用结构化的 OpenAPI 模式。
  2. spec.preserveUnknownFields 设置为 false

如果你将下面的 YAML 保存到 my-crontab.yaml 文件:

  1. apiVersion: "stable.example.com/v1"
  2. kind: CronTab
  3. metadata:
  4. name: my-new-cron-object
  5. spec:
  6. cronSpec: "* * * * */5"
  7. image: my-awesome-cron-image
  8. someRandomField: 42

并创建之:

  1. kubectl create --validate=false -f my-crontab.yaml -o yaml

输出类似于:

  1. apiVersion: stable.example.com/v1
  2. kind: CronTab
  3. metadata:
  4. creationTimestamp: 2017-05-31T12:56:35Z
  5. generation: 1
  6. name: my-new-cron-object
  7. namespace: default
  8. resourceVersion: "285"
  9. uid: 9423255b-4600-11e7-af6a-28d2447dc82b
  10. spec:
  11. cronSpec: '* * * * */5'
  12. image: my-awesome-cron-image

注意其中的字段 someRandomField 已经被剪裁掉。

本例中通过 --validate=false 命令行选项 关闭了客户端的合法性检查以展示 API 服务器的行为, 因为 OpenAPI 合法性检查模式也会发布到 客户端,kubectl 也会检查未知的字段并在对象被发送到 API 服务器之前就拒绝它们。

控制剪裁

默认情况下,定制资源的所有版本中的所有未规定的字段都会被剪裁掉。 通过在结构化的 OpenAPI v3 检查模式定义 中为特定字段的子树添加 x-kubernetes-preserve-unknown-fields: true 属性,可以 选择不对其执行剪裁操作。 例如:

  1. type: object
  2. properties:
  3. json:
  4. x-kubernetes-preserve-unknown-fields: true

字段 json 可以保存任何 JSON 值,其中内容不会被剪裁掉。

你也可以部分地指定允许的 JSON 数据格式;例如:

  1. type: object
  2. properties:
  3. json:
  4. x-kubernetes-preserve-unknown-fields: true
  5. type: object
  6. description: this is arbitrary JSON

通过这样设置,JSON 中只能设置 object 类型的值。

对于所指定的每个属性(或 additionalProperties),剪裁会再次被启用。

  1. type: object
  2. properties:
  3. json:
  4. x-kubernetes-preserve-unknown-fields: true
  5. type: object
  6. properties:
  7. spec:
  8. type: object
  9. properties:
  10. foo:
  11. type: string
  12. bar:
  13. type: string

对于上述定义,如果提供的数值如下:

  1. json:
  2. spec:
  3. foo: abc
  4. bar: def
  5. something: x
  6. status:
  7. something: x

则该值会被剪裁为:

  1. json:
  2. spec:
  3. foo: abc
  4. bar: def
  5. status:
  6. something: x

这意味着所指定的 spec 对象中的 something 字段被剪裁掉,而其外部的内容都被保留。

IntOrString

模式定义中标记了 x-kubernetes-int-or-string: true 的节点不受前述规则 1 约束,因此下面的定义是结构化的模式:

  1. type: object
  2. properties:
  3. foo:
  4. x-kubernetes-int-or-string: true

此外,所有这类节点也不再受规则 3 约束,也就是说,下面两种模式是被允许的 (注意,仅限于这两种模式,不支持添加新字段的任何其他变种):

  1. x-kubernetes-int-or-string: true
  2. anyOf:
  3. - type: integer
  4. - type: string
  5. ...

  1. x-kubernetes-int-or-string: true
  2. allOf:
  3. - anyOf:
  4. - type: integer
  5. - type: string
  6. - ... # zero or more
  7. ...

在以上两种规约中,整数值和字符串值都会被认为是合法的。

合法性检查模式定义的发布时x-kubernetes-int-or-string: true 会被展开为上述两种模式之一。

RawExtension

RawExtensions(就像在 k8s.io/apimachinery 项目中 runtime.RawExtension 所定义的那样) 可以保存完整的 Kubernetes 对象,也就是,其中会包含 apiVersionkind 字段。

通过 x-kubernetes-embedded-resource: true 来设定这些嵌套对象的规约(无论是 完全无限制还是部分指定都可以)是可能的。例如:

  1. type: object
  2. properties:
  3. foo:
  4. x-kubernetes-embedded-resource: true
  5. x-kubernetes-preserve-unknown-fields: true

这里,字段 foo 包含一个完整的对象,例如:

  1. foo:
  2. apiVersion: v1
  3. kind: Pod
  4. spec:
  5. ...

由于字段上设置了 x-kubernetes-preserve-unknown-fields: true,其中的内容不会 被剪裁。不过,在这个语境中,x-kubernetes-preserve-unknown-fields: true 的 使用是可选的。

设置了 x-kubernetes-embedded-resource: true 之后,apiVersionkindmetadata 都是隐式设定并隐式完成合法性验证。

提供 CRD 的多个版本

关于如何为你的 CustomResourceDefinition 提供多个版本的支持,以及如何将你的对象 从一个版本迁移到另一个版本, 详细信息可参阅 定制资源定义的版本

高级主题

Finalizers

Finalizer 能够让控制器实现异步的删除前(Pre-delete)回调。 与内置对象类似,定制对象也支持 Finalizer。

你可以像下面一样为定制对象添加 Finalizer:

  1. apiVersion: "stable.example.com/v1"
  2. kind: CronTab
  3. metadata:
  4. finalizers:
  5. - stable.example.com/finalizer

自定义 Finalizer 的标识符包含一个域名、一个正向斜线和 finalizer 的名称。 任何控制器都可以在任何对象的 finalizer 列表中添加新的 finalizer。

对带有 Finalizer 的对象的第一个删除请求会为其 metadata.deletionTimestamp 设置一个值,但不会真的删除对象。一旦此值被设置,finalizers 列表中的表项 只能被移除。在列表中仍然包含 finalizer 时,无法强制删除对应的对象。

metadata.deletionTimestamp 字段被设置时,监视该对象的各个控制器会 执行它们所能处理的 finalizer,并在完成处理之后将其从列表中移除。 每个控制器负责将其 finalizer 从列表中删除。

metadata.deletionGracePeriodSeconds 的取值控制对更新的轮询周期。

一旦 finalizers 列表为空时,就意味着所有 finalizer 都被执行过, Kubernetes 会最终删除该资源,

合法性检查

定制资源是通过 OpenAPI v3 模式定义 来执行合法性检查的, 你可以通过使用准入控制 Webhook 来添加额外的合法性检查逻辑。

此外,对模式定义存在以下限制:

  • 以下字段不可设置:
    • definitions
    • dependencies
    • deprecated
    • discriminator
    • id
    • patternProperties
    • readOnly
    • writeOnly
    • xml
    • $ref
  • 字段 uniqueItems 不可设置为 true
  • 字段 additionalProperties 不可设置为 false
  • 字段 additionalPropertiesproperties 互斥,不可同时使用

设置默认值特性被启用时,可以设置字段 default。 就 apiextensions.k8s.io/v1 组的 CustomResourceDefinitions,这一条件是满足的。 设置默认值的功能特性从 1.17 开始正式发布。该特性在 1.16 版本中处于 Beta 状态,要求 CustomResourceDefaulting 特性门控 被启用。对于大多数集群而言,Beta 状态的特性门控默认都是自动启用的。

关于对某些 CustomResourceDefinition 特性所必需的限制,可参见 结构化的模式定义小节。

模式定义是在 CustomResourceDefinition 中设置的。在下面的例子中, CustomResourceDefinition 对定制对象执行以下合法性检查:

  • spec.cronSpec 必须是一个字符串,必须是正则表达式所描述的形式;
  • spec.replicas 必须是一个整数,且其最小值为 1、最大值为 10。

将此 CustomResourceDefinition 保存到 resourcedefinition.yaml 文件中:

  1. apiVersion: apiextensions.k8s.io/v1
  2. kind: CustomResourceDefinition
  3. metadata:
  4. name: crontabs.stable.example.com
  5. spec:
  6. group: stable.example.com
  7. versions:
  8. - name: v1
  9. served: true
  10. storage: true
  11. schema:
  12. # openAPIV3Schema is the schema for validating custom objects.
  13. openAPIV3Schema:
  14. type: object
  15. properties:
  16. spec:
  17. type: object
  18. properties:
  19. cronSpec:
  20. type: string
  21. pattern: '^(\d+|\*)(/\d+)?(\s+(\d+|\*)(/\d+)?){4}$'
  22. image:
  23. type: string
  24. replicas:
  25. type: integer
  26. minimum: 1
  27. maximum: 10
  28. scope: Namespaced
  29. names:
  30. plural: crontabs
  31. singular: crontab
  32. kind: CronTab
  33. shortNames:
  34. - ct

并创建 CustomResourceDefinition:

  1. kubectl apply -f resourcedefinition.yaml

对于一个创建 CronTab 类别对象的定制对象的请求而言,如果其字段中包含非法值,则 该请求会被拒绝。 在下面的例子中,定制对象中包含带非法值的字段:

  • spec.cronSpec 与正则表达式不匹配
  • spec.replicas 数值大于 10。

如果你将下面的 YAML 保存到 my-crontab.yaml

  1. apiVersion: "stable.example.com/v1"
  2. kind: CronTab
  3. metadata:
  4. name: my-new-cron-object
  5. spec:
  6. cronSpec: "* * * *"
  7. image: my-awesome-cron-image
  8. replicas: 15

并尝试创建定制对象:

  1. kubectl apply -f my-crontab.yaml

你会看到下面的错误信息:

  1. The CronTab "my-new-cron-object" is invalid: []: Invalid value: map[string]interface {}{"apiVersion":"stable.example.com/v1", "kind":"CronTab", "metadata":map[string]interface {}{"name":"my-new-cron-object", "namespace":"default", "deletionTimestamp":interface {}(nil), "deletionGracePeriodSeconds":(*int64)(nil), "creationTimestamp":"2017-09-05T05:20:07Z", "uid":"e14d79e7-91f9-11e7-a598-f0761cb232d1", "clusterName":""}, "spec":map[string]interface {}{"cronSpec":"* * * *", "image":"my-awesome-cron-image", "replicas":15}}:
  2. validation failure list:
  3. spec.cronSpec in body should match '^(\d+|\*)(/\d+)?(\s+(\d+|\*)(/\d+)?){4}$'
  4. spec.replicas in body should be less than or equal to 10

如果所有字段都包含合法值,则对象创建的请求会被接受。

将下面的 YAML 保存到 my-crontab.yaml 文件:

  1. apiVersion: "stable.example.com/v1"
  2. kind: CronTab
  3. metadata:
  4. name: my-new-cron-object
  5. spec:
  6. cronSpec: "* * * * */5"
  7. image: my-awesome-cron-image
  8. replicas: 5

并创建定制对象:

  1. kubectl apply -f my-crontab.yaml
  2. crontab "my-new-cron-object" created

设置默认值

Note: 要使用设置默认值功能,你的 CustomResourceDefinition 必须使用 API 版本 apiextensions.k8s.io/v1

设置默认值的功能允许在 OpenAPI v3 合法性检查模式定义中设置默认值:

  1. apiVersion: apiextensions.k8s.io/v1
  2. kind: CustomResourceDefinition
  3. metadata:
  4. name: crontabs.stable.example.com
  5. spec:
  6. group: stable.example.com
  7. versions:
  8. - name: v1
  9. served: true
  10. storage: true
  11. schema:
  12. # openAPIV3Schema 是用来检查定制对象的模式定义
  13. openAPIV3Schema:
  14. type: object
  15. properties:
  16. spec:
  17. type: object
  18. properties:
  19. cronSpec:
  20. type: string
  21. pattern: '^(\d+|\*)(/\d+)?(\s+(\d+|\*)(/\d+)?){4}$'
  22. default: "5 0 * * *"
  23. image:
  24. type: string
  25. replicas:
  26. type: integer
  27. minimum: 1
  28. maximum: 10
  29. default: 1
  30. scope: Namespaced
  31. names:
  32. plural: crontabs
  33. singular: crontab
  34. kind: CronTab
  35. shortNames:
  36. - ct

使用此 CRD 定义时,cronSpecreplicas 都会被设置默认值:

  1. apiVersion: "stable.example.com/v1"
  2. kind: CronTab
  3. metadata:
  4. name: my-new-cron-object
  5. spec:
  6. image: my-awesome-cron-image

会生成:

  1. apiVersion: "stable.example.com/v1"
  2. kind: CronTab
  3. metadata:
  4. name: my-new-cron-object
  5. spec:
  6. cronSpec: "5 0 * * *"
  7. image: my-awesome-cron-image
  8. replicas: 1

默认值设定的行为发生在定制对象上:

  • 在向 API 服务器发送的请求中,基于请求版本的设定设置默认值;
  • 在从 etcd 读取对象时,使用存储版本来设置默认值;
  • 在 Mutating 准入控制插件执行非空的补丁操作时,基于准入 Webhook 对象 版本设置默认值。

从 etcd 中读取数据时所应用的默认值设置不会被写回到 etcd 中。 需要通过 API 执行更新请求才能将这种方式设置的默认值写回到 etcd。

默认值一定会被剪裁(除了 metadata 字段的默认值设置),且必须通过所提供 的模式定义的检查。

针对 x-kubernetes-embedded-resource: true 节点(或者包含 metadata 字段的结构的默认值) 的 metadata 字段的默认值设置不会在 CustomResourceDefinition 创建时被剪裁, 而是在处理请求的字段剪裁阶段被删除。

设置默认值和字段是否可为空(Nullable)

1.20 版本新增: 对于未设置其 nullable 标志的字段或者将该标志设置为 false 的字段,其空值(Null)会在设置默认值之前被剪裁掉。如果对应字段 存在默认值,则默认值会被赋予该字段。当 nullable 被设置为 true 时, 字段的空值会被保留,且不会在设置默认值时被覆盖。

例如,给定下面的 OpenAPI 模式定义:

  1. type: object
  2. properties:
  3. spec:
  4. type: object
  5. properties:
  6. foo:
  7. type: string
  8. nullable: false
  9. default: "default"
  10. bar:
  11. type: string
  12. nullable: true
  13. baz:
  14. type: string

像下面这样创建一个为 foobarbaz 设置空值的对象时:

  1. spec:
  2. foo: null
  3. bar: null
  4. baz: null

其结果会是这样:

  1. spec:
  2. foo: "default"
  3. bar: null

其中的 foo 字段被剪裁掉并重新设置默认值,因为该字段是不可为空的。 bar 字段的 nullable: true 使得其能够保有其空值。 baz 字段则被完全剪裁掉,因为该字段是不可为空的,并且没有默认值设置。

以 OpenAPI v2 形式发布合法性检查模式

CustomResourceDefinition 的结构化的启用了剪裁的 OpenAPI v3 合法性检查模式 会在 Kubernetes API 服务器上作为 OpenAPI v2 规约 的一部分发布出来。

kubectl 命令行工具会基于所发布的模式定义来执行 客户端的合法性检查(kubectl createkubectl apply),为定制资源的模式定义 提供解释(kubectl explain)。 所发布的模式还可被用于其他目的,例如生成客户端或者生成文档。

OpenAPI v3 合法性检查模式定义会被转换为 OpenAPI v2 模式定义,并出现在 OpenAPI v2 规范definitionspaths 字段中。

在转换过程中会发生以下修改,目的是保持与 1.13 版本以前的 kubectl 工具兼容。 这些修改可以避免 kubectl 过于严格,以至于拒绝它无法理解的 OpenAPI 模式定义。 转换过程不会更改 CRD 中定义的合法性检查模式定义,因此不会影响到 API 服务器中 的合法性检查

  1. 以下字段会被移除,因为它们在 OpenAPI v2 中不支持(在将来版本中将使用 OpenAPI v3, 因而不会有这些限制)
    • 字段 allOfanyOfoneOfnot 会被删除
  2. 如果设置了 nullable: true,我们会丢弃 typenullableitemsproperties OpenAPI v2 无法表达 Nullable。为了避免 kubectl 拒绝正常的对象,这一转换是必要的。

额外的打印列

kubectl 工具依赖服务器端的输出格式化。你的集群的 API 服务器决定 kubectl get 命令要显示的列有哪些。 你可以为 CustomResourceDefinition 定制这些要打印的列。 下面的例子添加了 SpecReplicasAge 列:

将此 CustomResourceDefinition 保存到 resourcedefinition.yaml 文件:

  1. apiVersion: apiextensions.k8s.io/v1
  2. kind: CustomResourceDefinition
  3. metadata:
  4. name: crontabs.stable.example.com
  5. spec:
  6. group: stable.example.com
  7. scope: Namespaced
  8. names:
  9. plural: crontabs
  10. singular: crontab
  11. kind: CronTab
  12. shortNames:
  13. - ct
  14. versions:
  15. - name: v1
  16. served: true
  17. storage: true
  18. schema:
  19. openAPIV3Schema:
  20. type: object
  21. properties:
  22. spec:
  23. type: object
  24. properties:
  25. cronSpec:
  26. type: string
  27. image:
  28. type: string
  29. replicas:
  30. type: integer
  31. additionalPrinterColumns:
  32. - name: Spec
  33. type: string
  34. description: The cron spec defining the interval a CronJob is run
  35. jsonPath: .spec.cronSpec
  36. - name: Replicas
  37. type: integer
  38. description: The number of jobs launched by the CronJob
  39. jsonPath: .spec.replicas
  40. - name: Age
  41. type: date
  42. jsonPath: .metadata.creationTimestamp

创建 CustomResourceDefinition:

  1. kubectl apply -f resourcedefinition.yaml

使用前文中的 my-crontab.yaml 创建一个实例。

启用服务器端打印输出:

  1. kubectl get crontab my-new-cron-object

注意输出中的 NAMESPECREPLICASAGE 列:

  1. NAME SPEC REPLICAS AGE
  2. my-new-cron-object * * * * * 1 7s

Note: NAME 列是隐含的,不需要在 CustomResourceDefinition 中定义。

优先级

每个列都包含一个 priority(优先级)字段。当前,优先级用来区分标准视图(Standard View)和宽视图(Wide View)(使用 -o wide 标志)中显示的列:

  • 优先级为 0 的列会在标准视图中显示。
  • 优先级大于 0 的列只会在宽视图中显示。

类型

列的 type 字段可以是以下值之一 (比较 OpenAPI v3 数据类型):

  • integer – 非浮点数字
  • number – 浮点数字
  • string – 字符串
  • booleantruefalse
  • date – 显示为以自此时间戳以来经过的时长

如果定制资源中的值与列中指定的类型不匹配,该值会被忽略。 你可以通过定制资源的合法性检查来确保取值类型是正确的。

格式

列的 format 字段可以是以下值之一:

  • int32
  • int64
  • float
  • double
  • byte
  • date
  • date-time
  • password

列的 format 字段控制 kubectl 打印对应取值时采用的风格。

子资源

定制资源支持 /status/scale 子资源。

通过在 CustomResourceDefinition 中定义 statusscale, 可以有选择地启用这些子资源。

Status 子资源

当启用了 status 子资源时,对应定制资源的 /status 子资源会被暴露出来。

  • status 和 spec 内容分别用定制资源内的 .status.spec JSON 路径来表达;
  • /status 子资源的 PUT 请求要求使用定制资源对象作为其输入,但会忽略 status 之外的所有内容。
  • /status 子资源的 PUT 请求仅对定制资源的 status 内容进行合法性检查。
  • 对定制资源的 PUTPOSTPATCH 请求会忽略 status 内容的改变。
  • 对所有变更请求,除非改变是针对 .metadata.status.metadata.generation 的取值都会增加。

  • 在 CRD OpenAPI 合法性检查模式定义的根节点,只允许存在以下结构:

    • description
    • example
    • exclusiveMaximum
    • exclusiveMinimum
    • externalDocs
    • format
    • items
    • maximum
    • maxItems
    • maxLength
    • minimum
    • minItems
    • minLength
    • multipleOf
    • pattern
    • properties
    • required
    • title
    • type
    • uniqueItems

Scale 子资源

当启用了 scale 子资源时,定制资源的 /scale 子资源就被暴露出来。 针对 /scale 所发送的对象是 autoscaling/v1.Scale

为了启用 scale 子资源,CustomResourceDefinition 定义了以下字段:

  • specReplicasPath 指定定制资源内与 scale.spec.replicas 对应的 JSON 路径。

    • 此字段为必需值。
    • 只可以使用 .spec 下的 JSON 路径,只可使用带句点的路径。
    • 如果定制资源的 specReplicasPath 下没有取值,则针对 /scale 子资源执行 GET 操作时会返回错误。
  • statusReplicasPath 指定定制资源内与 scale.status.replicas 对应的 JSON 路径。

    • 此字段为必需值。
    • 只可以使用 .status 下的 JSON 路径,只可使用带句点的路径。
    • 如果定制资源的 statusReplicasPath 下没有取值,则针对 /scale 子资源的 副本个数状态值默认为 0。
  • labelSelectorPath 指定定制资源内与 scale.status.selector 对应的 JSON 路径。

    • 此字段为可选值。
    • 此字段必须设置才能使用 HPA。
    • 只可以使用 .status.spec 下的 JSON 路径,只可使用带句点的路径。
    • 如果定制资源的 labelSelectorPath 下没有取值,则针对 /scale 子资源的 选择算符状态值默认为空字符串。
    • 此 JSON 路径所指向的字段必须是一个字符串字段(而不是复合的选择算符结构), 其中包含标签选择算符串行化的字符串形式。

在下面的例子中,statusscale 子资源都被启用。

将此 CustomResourceDefinition 保存到 resourcedefinition.yaml 文件:

  1. apiVersion: apiextensions.k8s.io/v1
  2. kind: CustomResourceDefinition
  3. metadata:
  4. name: crontabs.stable.example.com
  5. spec:
  6. group: stable.example.com
  7. versions:
  8. - name: v1
  9. served: true
  10. storage: true
  11. schema:
  12. openAPIV3Schema:
  13. type: object
  14. properties:
  15. spec:
  16. type: object
  17. properties:
  18. cronSpec:
  19. type: string
  20. image:
  21. type: string
  22. replicas:
  23. type: integer
  24. status:
  25. type: object
  26. properties:
  27. replicas:
  28. type: integer
  29. labelSelector:
  30. type: string
  31. # subresources 描述定制资源的子资源
  32. subresources:
  33. # status 启用 status 子资源
  34. status: {}
  35. # scale 启用 scale 子资源
  36. scale:
  37. # specReplicasPath 定义定制资源中对应 scale.spec.replicas 的 JSON 路径
  38. specReplicasPath: .spec.replicas
  39. # statusReplicasPath 定义定制资源中对应 scale.status.replicas 的 JSON 路径
  40. statusReplicasPath: .status.replicas
  41. # labelSelectorPath 定义定制资源中对应 scale.status.selector 的 JSON 路径
  42. labelSelectorPath: .status.labelSelector
  43. scope: Namespaced
  44. names:
  45. plural: crontabs
  46. singular: crontab
  47. kind: CronTab
  48. shortNames:
  49. - ct

之后创建此 CustomResourceDefinition:

  1. kubectl apply -f resourcedefinition.yaml

CustomResourceDefinition 对象创建完毕之后,你可以创建定制对象,。

如果你将下面的 YAML 保存到 my-crontab.yaml 文件:

  1. apiVersion: "stable.example.com/v1"
  2. kind: CronTab
  3. metadata:
  4. name: my-new-cron-object
  5. spec:
  6. cronSpec: "* * * * */5"
  7. image: my-awesome-cron-image
  8. replicas: 3

并创建定制对象:

  1. kubectl apply -f my-crontab.yaml

那么会创建新的、命名空间作用域的 RESTful API 端点:

  1. /apis/stable.example.com/v1/namespaces/*/crontabs/status

  1. /apis/stable.example.com/v1/namespaces/*/crontabs/scale

定制资源可以使用 kubectl scale 命令来扩缩其规模。 例如下面的命令将前面创建的定制资源的 .spec.replicas 设置为 5:

  1. kubectl scale --replicas=5 crontabs/my-new-cron-object
  1. crontabs "my-new-cron-object" scaled
  1. kubectl get crontabs my-new-cron-object -o jsonpath='{.spec.replicas}'
  1. 5

你可以使用 PodDisruptionBudget 来保护启用了 scale 子资源的定制资源。

分类

分类(Categories)是定制资源所归属的分组资源列表(例如,all)。 你可以使用 kubectl get <分类名称> 来列举属于某分类的所有资源。

下面的示例在 CustomResourceDefinition 中将 all 添加到分类列表中, 并展示了如何使用 kubectl get all 来输出定制资源:

将下面的 CustomResourceDefinition 保存到 resourcedefinition.yaml 文件中:

  1. apiVersion: apiextensions.k8s.io/v1
  2. kind: CustomResourceDefinition
  3. metadata:
  4. name: crontabs.stable.example.com
  5. spec:
  6. group: stable.example.com
  7. versions:
  8. - name: v1
  9. served: true
  10. storage: true
  11. schema:
  12. openAPIV3Schema:
  13. type: object
  14. properties:
  15. spec:
  16. type: object
  17. properties:
  18. cronSpec:
  19. type: string
  20. image:
  21. type: string
  22. replicas:
  23. type: integer
  24. scope: Namespaced
  25. names:
  26. plural: crontabs
  27. singular: crontab
  28. kind: CronTab
  29. shortNames:
  30. - ct
  31. # categories 是定制资源所归属的分类资源列表
  32. categories:
  33. - all

之后创建此 CRD:

  1. kubectl apply -f resourcedefinition.yaml

创建了 CustomResourceDefinition 对象之后,你可以创建定制对象。

将下面的 YAML 保存到 my-crontab.yaml 中:

  1. apiVersion: "stable.example.com/v1"
  2. kind: CronTab
  3. metadata:
  4. name: my-new-cron-object
  5. spec:
  6. cronSpec: "* * * * */5"
  7. image: my-awesome-cron-image

并创建定制对象:

  1. kubectl apply -f my-crontab.yaml

你可以在使用 kubectl get 时指定分类:

  1. kubectl get all

输出中会包含类别为 CronTab 的定制资源:

  1. NAME AGE
  2. crontabs/my-new-cron-object 3s

What’s next

最后修改 November 09, 2021 at 2:25 PM PST: [zh] Fix typo (0877306b4)