扩展资源

1 - CustomResourceDefinition

apiVersion: apiextensions.k8s.io/v1

import "k8s.io/apiextensions-apiserver/pkg/apis/apiextensions/v1"

CustomResourceDefinition

CustomResourceDefinition 表示应在 API 服务器上公开的资源。其名称必须采用 <.spec.name>.<.spec.group> 格式。

• apiVersion：apiextensions.k8s.io/v1

• kind：CustomResourceDefinition

• metadata (ObjectMeta)

  标准的对象元数据，更多信息： https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata

• spec (CustomResourceDefinitionSpec)，必需

  spec 描述了用户希望资源的呈现方式。

• status (CustomResourceDefinitionStatus)

  status 表示 CustomResourceDefinition 的实际状态。

CustomResourceDefinitionSpec

CustomResourceDefinitionSpec 描述了用户希望资源的呈现方式。

• group (string)，必需

  group 是自定义资源的 API 组。自定义资源在 /apis/<group>/... 下提供。 必须与 CustomResourceDefinition 的名称匹配（格式为 <names.plural>.<group>）。

• names (CustomResourceDefinitionNames)，必需

  names 表示自定义资源的资源和种类名称。

  CustomResourceDefinitionNames 表示提供此 CustomResourceDefinition 资源的名称。

  • names.kind (string)，必需

    kind 是资源的序列化类型。它通常是驼峰命名的单数形式。自定义资源实例将使用此值作为 API 调用中的 kind 属性。

  • names.plural (string)，必需

    plural 是所提供的资源的复数名称，自定义资源在 /apis/<group>/<version>/.../<plural> 下提供。 必须与 CustomResourceDefinition 的名称匹配（格式为 <names.plural>.<group>）。必须全部小写。

  • names.categories ([]string)

    原子：将在合并期间被替换

    categories 是自定义资源所属的分组资源列表（例如 'all'）。 它在 API 发现文档中发布，并支持客户端像 kubectl get all 这样的调用。

  • names.listKind (string)

    listKind 是此资源列表的序列化类型。默认为 "kindList"。

  • names.shortNames ([]string)

    原子：将在合并期间被替换

    shortNames 是资源的短名称，在 API 发现文档中公开，并支持客户端调用，如 kubectl get <shortname>。必须全部小写。

  • names.singular (string)

    singular 是资源的单数名称。必须全部小写。默认为小写 kind。

• scope (string)，必需

  scope 表示自定义资源是集群作用域还是命名空间作用域。允许的值为 Cluster 和 Namespaced。

• versions ([]CustomResourceDefinitionVersion)，必需

  原子：将在合并期间被替换

  versions 是自定义资源的所有 API 版本的列表。版本名称用于计算服务版本在 API 发现中列出的顺序。 如果版本字符串与 Kubernetes 的版本号形式类似，则它将被排序在非 Kubernetes 形式版本字符串之前。 Kubernetes 的版本号字符串按字典顺序排列。Kubernetes 版本号以 “v” 字符开头， 后面是一个数字（主版本），然后是可选字符串 “alpha” 或 “beta” 和另一个数字（次要版本）。 它们首先按 GA > beta > alpha 排序（其中 GA 是没有 beta 或 alpha 等后缀的版本），然后比较主要版本， 最后是比较次要版本。版本排序列表示例：v10、v2、v1、v11beta2、v10beta3、v3beta1、v12alpha1、v11alpha2、foo1、foo10。

  CustomResourceDefinitionVersion 描述 CRD 的一个版本。

  • versions.name (string)，必需

    name 是版本名称，例如 “v1”、“v2beta1” 等。如果 served 是 true，自定义资源在 /apis/<group>/<version>/... 版本下提供。

  • versions.served (boolean)，必需

    served 是用于启用/禁用该版本通过 REST API 提供服务的标志。

  • versions.storage (boolean)，必需

    storage 表示在将自定义资源持久保存到存储时，应使用此版本。有且仅有一个版本的 storage=true。

  • versions.additionalPrinterColumns ([]CustomResourceColumnDefinition)

    原子：将在合并期间被替换

    additionalPrinterColumns 表示在表输出中返回的附加列。 有关详细信息，请参阅 https://kubernetes.io/zh-cn/docs/reference/using-api/api-concepts/#receiving-resources-as-tables。 如果没有指定列，则显示自定义资源存活时间（AGE）列。

    CustomResourceColumnDefinition 指定用于服务器端打印的列。

    • versions.additionalPrinterColumns.jsonPath (string)，必需

      jsonPath 是一个简单的 JSON 路径（使用数组表示法），它对每个自定义资源进行评估，以生成该列的值。

    • versions.additionalPrinterColumns.name (string)，必需

      name 是便于阅读的列名称。

    • versions.additionalPrinterColumns.type (string)，必需

      type 是此列的 OpenAPI 类型定义。有关详细信息， 请参阅 https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#data-types

    • versions.additionalPrinterColumns.description (string)

      description 是该列的可读性描述。

    • versions.additionalPrinterColumns.format (string)

      format 是这个列的可选 OpenAPI 类型定义。'name' 格式应用于主标识符列，以帮助客户端识别列是资源名称。 有关详细信息，请参阅 https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#data-types。

    • versions.additionalPrinterColumns.priority (int32)

      priority 是一个定义此列相对于其他列的相对重要性的整数。数字越低，优先级越高。 在空间有限的情况下，可以省略的列的优先级应大于 0。

  • versions.deprecated (boolean)

    deprecated 表示此版本的自定义资源 API 已弃用。设置为 true 时，对此版本的 API 请求会在服务器响应头信息中带有警告（warning）信息。此值默认为 false。

  • versions.deprecationWarning (string)

    deprecationWarning 会覆盖返回给 API 客户端的默认警告。只能在 deprecated 为 true 时设置。 默认警告表示此版本已弃用，建议使用最新的同等或更高稳定性版本（如果存在）。

  • versions.schema (CustomResourceValidation)

    schema 描述了用于验证、精简和默认此版本的自定义资源的模式。

    CustomResourceValidation 是 CustomResources 的验证方法列表。

    • versions.schema.openAPIV3Schema (JSONSchemaProps)

      openAPIV3Schema 是用于验证和精简的 OpenAPI v3 模式。

  • versions.selectableFields ([]SelectableField)

    原子：将在合并期间被替换

    selectableFields 指定可用作字段选择器的字段路径，最多允许 8 个可选字段。 请参阅：https://kubernetes.io/zh-cn/docs/concepts/overview/working-with-objects/field-selectors

    SelectableField 指定可与字段选择器一起使用的字段的 JSON 路径。

  • versions.selectableFields.jsonPath (string), required

    jsonPath 是一个简单的 JSON 路径，它会根据每个自定义资源进行求值以生成字段选择器值。 只允许使用不带数组符号的 JSON 路径。必须指向字符串、布尔值或整数类型的字段。 允许使用枚举值类型和带格式的字符串。如果 jsonPath 引用资源中不存在的字段，则 jsonPath 的求值结果为空字符串。不得指向元数据字段。必需。

  • versions.subresources (CustomResourceSubresources)

    subresources 指定此版本已定义的自定义资源具有哪些子资源。

    CustomResourceSubresources 定义了 CustomResources 子资源的状态和规模。

    • versions.subresources.scale (CustomResourceSubresourceScale)

      scale 表示自定义资源应该提供一个 /scale 子资源，该子资源返回一个 autoscaling/v1 Scale 对象。

      CustomResourceSubresourceScale 定义了如何为 CustomResources 的 scale 子资源提供服务。

      • versions.subresources.scale.specReplicasPath (string)，必需

        specReplicasPath 定义对应于 Scale 的自定义资源内的 JSON 路径 spec.replicas。 只允许没有数组表示法的 JSON 路径。必须是 .spec 下的 JSON 路径。 如果自定义资源中的给定路径下没有值，那么 GET /scale 子资源将返回错误。

      • versions.subresources.scale.statusReplicasPath (string)，必需

        statusReplicasPath 定义对应于 Scale 的自定义资源内的 JSON 路径 status.replicas。 只允许不带数组表示法的 JSON 路径。必须是 .status 下的 JSON 路径。 如果自定义资源中给定路径下没有值，则 /scale 子资源中的 status.replicas 值将默认为 0。

      • versions.subresources.scale.labelSelectorPath (string)

        labelSelectorPath 定义对应于 Scale 的自定义资源内的 JSON 路径 status.selector。 只允许不带数组表示法的 JSON 路径。必须是 .status 或 .spec 下的路径。 必须设置为与 HorizontalPodAutoscaler 一起使用。 此 JSON 路径指向的字段必须是字符串字段（不是复杂的选择器结构），其中包含字符串形式的序列化标签选择器。 更多信息： https://kubernetes.io/zh-cn/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions#scale-subresource。 如果自定义资源中给定路径下没有值，则 /scale 子资源中的 status.selector 默认值为空字符串。

    • versions.subresources.status (CustomResourceSubresourceStatus)

      status 表示自定义资源应该为 /status 子资源服务。当启用时：

      1. 对自定义资源主端点的请求会忽略对对象 status 节的改变；
      2. 对自定义资源 /status 子资源的请求忽略对对象 status 节以外的任何变化。

      CustomResourceSubresourceStatus 定义了如何为自定义资源提供 status 子资源。 状态由 CustomResource 中的 .status JSON 路径表示。设置后，

      • 为自定义资源提供一个 /status 子资源。
      • 向 /status 子资源发出的 PUT 请求时，需要提供自定义资源对象，服务器端会忽略对 status 节以外的任何内容更改。
      • 对自定义资源的 PUT/POST/PATCH 请求会忽略对 status 节的更改。

• conversion (CustomResourceConversion)

  conversion 定义了 CRD 的转换设置。

  CustomResourceConversion 描述了如何转换不同版本的自定义资源。

  • conversion.strategy (string)，必需

    strategy 指定如何在版本之间转换自定义资源。允许的值为：

    • "None"：转换器仅更改 apiVersion 并且不会触及自定义资源中的任何其他字段。
    • "Webhook"：API 服务器将调用外部 Webhook 进行转换。此选项需要其他信息。这要求 spec.preserveUnknownFields 为 false，并且设置 spec.conversion.webhook。

  • conversion.webhook (WebhookConversion)

    webhook 描述了如何调用转换 Webhook。当 strategy 设置为 "Webhook" 时有效。

    WebhookConversion 描述了如何调用转换 Webhook

    原子：将在合并期间被替换

    • conversion.webhook.conversionReviewVersions ([]string)，必需

      conversionReviewVersions 是 Webhook 期望的 ConversionReview 版本的有序列表。 API 服务器将使用它支持的列表中的第一个版本。如果 API 服务器不支持此列表中指定的版本，则自定义资源的转换将失败。 如果持久化的 Webhook 配置指定了允许的版本但其中不包括 API 服务器所了解的任何版本，则对 Webhook 的调用将失败。

    • conversion.webhook.clientConfig (WebhookClientConfig)

      如果 strategy 是 Webhook，那么 clientConfig 是关于如何调用 Webhook 的说明。

      WebhookClientConfig 包含与 Webhook 建立 TLS 连接的信息。

      • conversion.webhook.clientConfig.caBundle ([]byte)

        caBundle 是一个 PEM 编码的 CA 包，用于验证 Webhook 服务器的服务证书。 如果未指定，则使用 API 服务器上的系统根证书。

      • conversion.webhook.clientConfig.service (ServiceReference)

        service 是对此 Webhook 服务的引用。必须指定 service 或 url 字段之一。

        如果在集群中运行 Webhook，那么你应该使用 service。

        ServiceReference 保存对 Service.legacy.k8s.io 的一个引用。

        • conversion.webhook.clientConfig.service.name (string)，必需

          name 是服务的名称。必需。

        • conversion.webhook.clientConfig.service.namespace (string)，必需

          namespace 是服务的命名空间。必需。

        • conversion.webhook.clientConfig.service.path (string)

          path 是一个可选的 URL 路径，Webhook 将通过该路径联系服务。

        • conversion.webhook.clientConfig.service.port (int32)

          port 是 Webhook 联系的可选服务端口。port 应该是一个有效的端口号（1-65535，包含）。 为实现向后兼容，默认端口号为 443。

      • conversion.webhook.clientConfig.url (string)

        url 以标准 URL 的形式（scheme://host:port/path）给出 Webhook 的位置。url 或 service 必须指定一个且只能指定一个。

        host 不应引用集群中运行的服务；若使用集群内服务应改为使用 service 字段。 host 值可能会通过外部 DNS 解析（例如，kube-apiserver 无法解析集群内 DNS，因为这将违反分层规则）。 host 也可能是 IP 地址。

        请注意，使用 localhost 或 127.0.0.1 作为 host 是有风险的， 除非你非常小心地在所有运行 API 服务器的主机上运行这个 Webhook，因为这些 API 服务器可能需要调用这个 Webhook。 这样的安装可能是不可移植的，也就是说，不容易在一个新的集群中复现。

        scheme 必须是 "https"；URL 必须以 "https://" 开头。

        路径（path）是可选的，如果存在，则可以是 URL 中允许的任何字符串。 你可以使用路径传递一个任意字符串给 Webhook，例如，一个集群标识符。

        不允许使用用户或基本认证，例如 "user:password@"，是不允许的。片段（"#..."）和查询参数（"?..."）也是不允许的。

• preserveUnknownFields (boolean)

  preserveUnknownFields 表示将对象写入持久性存储时应保留 OpenAPI 模式中未规定的对象字段。 apiVersion、kind、元数据（metadata）和元数据中的已知字段始终保留。不推荐使用此字段，而建议在 spec.versions[*].schema.openAPIV3Schema 中设置 x-preserve-unknown-fields 为 true。 更多详细信息参见： https://kubernetes.io/zh-cn/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#field-pruning

JSONSchemaProps

JSONSchemaProps 是JSON 模式（JSON-Schema），遵循其规范草案第 4 版（http://json-schema.org/）。

• $ref (string)

• $schema (string)

• additionalItems (JSONSchemaPropsOrBool)

  JSONSchemaPropsOrBool 表示 JSONSchemaProps 或布尔值。布尔属性默认为 true。

• additionalProperties (JSONSchemaPropsOrBool)

  JSONSchemaPropsOrBool 表示 JSONSchemaProps 或布尔值。布尔属性默认为 true。

• allOf ([]JSONSchemaProps)

  原子：将在合并期间被替换

• anyOf ([]JSONSchemaProps)

  原子：将在合并期间被替换

• default (JSON)

  default 是未定义对象字段的默认值。设置默认值操作是 CustomResourceDefaulting 特性门控所控制的一个 Beta 特性。 应用默认值设置时要求 spec.preserveUnknownFields 为 false。

  JSON 表示任何有效的 JSON 值。支持以下类型：bool、int64、float64、string、[]interface{}、map[string]interface{} 和 nil。

• definitions (map[string]JSONSchemaProps)

• dependencies (map[string]JSONSchemaPropsOrStringArray)

  JSONSchemaPropsOrStringArray 表示 JSONSchemaProps 或字符串数组。

• description (string)

• enum ([]JSON)

  原子：将在合并期间被替换

  JSON 表示任何有效的 JSON 值。支持以下类型：bool、int64、float64、string、[]interface{}、map[string]interface{} 和 nil。

• example (JSON)

  JSON 表示任何有效的 JSON 值。支持以下类型：bool、int64、float64、string、[]interface{}、map[string]interface{} 和 nil。

• exclusiveMaximum (boolean)

• exclusiveMinimum (boolean)

• externalDocs (ExternalDocumentation)

  ExternalDocumentation 允许引用外部资源作为扩展文档。

  • externalDocs.description (string)

  • externalDocs.url (string)

• format (string)

  format 是 OpenAPI v3 格式字符串。未知格式将被忽略。以下格式会被验证合法性：

  • bsonobjectid：一个 bson 对象的 ID，即一个 24 个字符的十六进制字符串
  • uri：由 Go 语言 net/url.ParseRequestURI 解析得到的 URI
  • email：由 Go 语言 net/mail.ParseAddress 解析得到的电子邮件地址
  • hostname：互联网主机名的有效表示，由 RFC 1034 第 3.1 节 [RFC1034] 定义
  • ipv4：由 Go 语言 net.ParseIP 解析得到的 IPv4 协议的 IP
  • ipv6：由 Go 语言 net.ParseIP 解析得到的 IPv6 协议的 IP
  • cidr：由 Go 语言 net.ParseCIDR 解析得到的 CIDR
  • mac：由 Go 语言 net.ParseMAC 解析得到的一个 MAC 地址
  • uuid：UUID，允许大写字母，满足正则表达式 (?i)^[0-9a-f]{8}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{12}$
  • uuid3：UUID3，允许大写字母，满足正则表达式 (?i)^[0-9a-f]{8}-?[0-9a-f]{4}-?3[0-9a-f]{3}-?[0-9a-f]{4}-?[0-9a-f]{12}$
  • uuid4：UUID4，允许大写字母，满足正则表达式 (?i)^[0-9a-f]{8}-?[0-9a-f]{4}-?4[0-9a-f]{3}-?[89ab][0-9a-f]{3}-?[0-9a-f]{12}$
  • uuid5：UUID5，允许大写字母，满足正则表达式 (?i)^[0-9a-f]{8}-?[0-9a-f]{4}-?5[0-9a-f]{3}-?[89ab][0-9a-f]{3}-?[0-9a-f]{12}$
  • isbn：一个 ISBN10 或 ISBN13 数字字符串，如 "0321751043" 或 "978-0321751041"
  • isbn10：一个 ISBN10 数字字符串，如 "0321751043"
  • isbn13：一个 ISBN13 号码字符串，如 "978-0321751041"
  • creditcard：信用卡号码，满足正则表达式 ^(?:4[0-9]{12}(?:[0-9]{3})?|5[1-5][0-9]{14}|6(?:011|5[0-9][0-9])[0-9]{12}|3[47][0-9]{13}|3(?:0[0-5]|[68][0-9])[0-9]{11}|(?:2131|1800|35\d{3})\d{11})$， 其中混合任意非数字字符
  • ssn：美国社会安全号码，满足正则表达式 ^\d{3}[- ]?\d{2}[- ]?\d{4}$
  • hexcolor：一个十六进制的颜色编码，如 "#FFFFFF"，满足正则表达式 ^#?([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$
  • rgbcolor：一个 RGB 颜色编码 例如 "rgb(255,255,255)"
  • byte：base64 编码的二进制数据
  • password：任何类型的字符串
  • date：类似 "2006-01-02" 的日期字符串，由 RFC3339 中的完整日期定义
  • duration：由 Go 语言 time.ParseDuration 解析的持续时长字符串，如 "22 ns"，或与 Scala 持续时间格式兼容。
  • datetime：一个日期时间字符串，如 "2014-12-15T19:30:20.000Z"，由 RFC3339 中的 date-time 定义。

• id (string)

• items (JSONSchemaPropsOrArray)

  JSONSchemaPropsOrArray 表示可以是 JSONSchemaProps 或 JSONSchemaProps 数组的值。这里目的主要用于序列化。

• maxItems (int64)

• maxLength (int64)

• maxProperties (int64)

• maximum (double)

• minItems (int64)

• minLength (int64)

• minProperties (int64)

• minimum (double)

• multipleOf (double)

• not (JSONSchemaProps)

• nullable (boolean)

• oneOf ([]JSONSchemaProps)

  原子：将在合并期间被替换

• pattern (string)

• patternProperties (map[string]JSONSchemaProps)

• properties (map[string]JSONSchemaProps)

• required ([]string)

  原子：将在合并期间被替换

• title (string)

• type (string)

• uniqueItems (boolean)

• x-kubernetes-embedded-resource (boolean)

  x-kubernetes-embedded-resource 定义该值是一个嵌入式 Kubernetes runtime.Object，具有 TypeMeta 和 ObjectMeta。 类型必须是对象。允许进一步限制嵌入对象。会自动验证 kind、apiVersion 和 metadata 等字段值。 x-kubernetes-preserve-unknown-fields 允许为 true，但如果对象已完全指定 （除 kind、apiVersion、metadata 之外），则不必为 true。

• x-kubernetes-int-or-string (boolean)

  x-kubernetes-int-or-string 指定此值是整数或字符串。如果为 true，则允许使用空类型， 并且如果遵循以下模式之一，则允许作为 anyOf 的子类型：

  1. anyOf:
     • type: integer
     • type: string
  2. allOf:
     • anyOf:
       • type: integer
       • type: string
     • （可以有选择地包含其他类型）

• x-kubernetes-list-map-keys ([]string)

  原子：将在合并期间被替换

  X-kubernetes-list-map-keys 通过指定用作 map 索引的键来使用 x-kubernetes-list-type map 注解数组。

  这个标签必须只用于 "x-kubernetes-list-type" 扩展设置为 "map" 的列表。 而且，为这个属性指定的值必须是子结构的标量类型的字段（不支持嵌套）。

  指定的属性必须是必需的或具有默认值，以确保所有列表项都存在这些属性。

• x-kubernetes-list-type (string)

  x-kubernetes-list-type 注解一个数组以进一步描述其拓扑。此扩展名只能用于列表，并且可能有 3 个可能的值：

  1. atomic： 列表被视为单个实体，就像标量一样。原子列表在更新时将被完全替换。这个扩展可以用于任何类型的列表（结构，标量，…）。
  2. set： set 是不能有多个具有相同值的列表。每个值必须是标量、具有 x-kubernetes-map-type atomic 的对象或具有 x-kubernetes-list-type atomic 的数组。
  3. map： 这些列表类似于映射表，因为它们的元素具有用于标识它们的非索引键。合并时保留顺序。 map 标记只能用于元数类型为 object 的列表。 数组默认为原子数组。

• x-kubernetes-map-type (string)

  x-kubernetes-map-type 注解一个对象以进一步描述其拓扑。此扩展只能在 type 为 object 时使用，并且可能有 2 个可能的值：

  1. granular： 这些 map 是真实的映射（键值对），每个字段都是相互独立的（它们都可以由不同的角色来操作）。 这是所有 map 的默认行为。
  2. atomic：map 被视为单个实体，就像标量一样。原子 map 更新后将被完全替换。

• x-kubernetes-preserve-unknown-fields (boolean)

  x-kubernetes-preserve-unknown-fields 针对未在验证模式中指定的字段，禁止 API 服务器的解码步骤剪除这些字段。 这一设置对字段的影响是递归的，但在模式中指定了嵌套 properties 或 additionalProperties 时，会切换回正常的字段剪除行为。 该值可为 true 或 undefined，不能为 false。

• x-kubernetes-validations ([]ValidationRule)

  补丁策略：基于键 rule 合并

  Map：合并时将保留 rule 键的唯一值

  x-kubernetes-validations 描述了用 CEL 表达式语言编写的验证规则列表。此字段是 Alpha 级别。

  ValidationRule 描述用 CEL 表达式语言编写的验证规则。

  • x-kubernetes-validations.rule (string)，必需

    rule 表示将由 CEL 评估的表达式。参考： https://github.com/google/cel-spec。 rule 的作用域为模式中的 x-kubernetes-validation 扩展所在的位置。CEL 表达式中的 self 与作用域值绑定。 例子：rule 的作用域是一个具有状态子资源的资源根： {"rule": "self.status.actual <= self.spec.maxDesired"}。

    如果 rule 的作用域是一个带有属性的对象，那么该对象的可访问属性是通过 self 进行字段选择的， 并且可以通过 has(self.field) 来检查字段是否存在。在 CEL 表达式中，Null 字段被视为不存在的字段。 如果该 rule 的作用域是一个带有附加属性的对象（例如一个 map），那么该 map 的值可以通过 self[mapKey]来访问，map 是否包含某主键可以通过 mapKey in self 来检查。 map 中的所有条目都可以通过 CEL 宏和函数（如 self.all(...)）访问。 如果 rule 的作用域是一个数组，数组的元素可以通过 self[i] 访问，也可以通过宏和函数访问。 如果 rule 的作用域为标量，self 绑定到标量值。举例：

    • rule 作用域为对象映射：{"rule": "self.components['Widget'].priority < 10"}
    • rule 作用域为整数列表：{"rule": "self.values.all(value, value >= 0 && value < 100)"}
    • rule 作用域为字符串值：{"rule": "self.startsWith('kube')"}

    apiVersion、kind、metadata.name 和 metadata.generateName 总是可以从对象的根和任何带 x-kubernetes-embedded-resource 注解的对象访问。其他元数据属性都无法访问。

    在 CEL 表达式中无法访问通过 x-kubernetes-preserve-unknown-fields 保存在自定义资源中的未知数据。 这包括：

    • 由包含 x-kubernetes-preserve-unknown-fields 的对象模式所保留的未知字段值；

    • 属性模式为 "未知类型" 的对象属性。"未知类型" 递归定义为：

      • 没有设置 type 但 x-kubernetes-preserve-unknown-fields 设置为 true 的模式。
      • 条目模式为"未知类型"的数组。
      • additionalProperties 模式为"未知类型"的对象。

    只有名称符合正则表达式 [a-zA-Z_.-/][a-zA-Z0-9_.-/]* 的属性才可被访问。 在表达式中访问属性时，可访问的属性名称根据以下规则进行转义：

    • '__' 转义为 'underscores'

    • '.' 转义为 'dot'

    • '-' 转义为 'dash'

    • '/' 转义为 'slash'

    • 恰好匹配 CEL 保留关键字的属性名称转义为 '{keyword}' 。这里的关键字具体包括： "true"，"false"，"null"，"in"，"as"，"break"，"const"，"continue"，"else"，"for"，"function"，"if"， "import"，"let"，"loop"，"package"，"namespace"，"return"。 举例：

      • 规则访问名为 "namespace" 的属性：{"rule": "self.__namespace__ > 0"}
      • 规则访问名为 "x-prop" 的属性：{"rule": "self.x__dash__prop > 0"}
      • 规则访问名为 "redact__d" 的属性：{"rule": "self.redact__underscores__d > 0"}

    对 x-kubernetes-list-type 为 'set' 或 'map' 的数组进行比较时忽略元素顺序，如：[1, 2] == [2, 1]。 使用 x-kubernetes-list-type 对数组进行串接使用下列类型的语义：

    • 'set'：X + Y 执行合并，其中 X 保留所有元素的数组位置，并附加不相交的元素 Y，保留其局部顺序。
    • 'map'：X + Y 执行合并，保留 X 中所有键的数组位置，但当 X 和 Y 的键集相交时，会被 Y 中的值覆盖。 添加 Y 中具有不相交键的元素，保持其局顺序。

    如果 rule 使用 oldSelf 变量，则隐式地将其视为一个 转换规则（transition rule）。

    默认情况下，oldSelf 变量与 self 类型相同。当 optionalOldSelf 为 true 时，oldSelf 变量是 CEL 可选变量，其 value() 与 self 类型相同。 有关详细信息，请参阅 optionalOldSelf 字段的文档。

    默认情况下，转换规则仅适用于 UPDATE 请求，如果找不到旧值，则会跳过转换规则。 你可以通过将 optionalOldSelf 设置为 true 来使转换规则进行无条件求值。

  • x-kubernetes-validations.fieldPath (string)

    fieldPath 表示验证失败时返回的字段路径。 它必须是相对 JSON 路径（即，支持数组表示法），范围仅限于此 x-kubernetes-validations 扩展在模式的位置，并引用现有字段。 例如，当验证检查 testMap 映射下是否有 foo 属性时，可以将 fieldPath 设置为 .testMap.foo。 如果验证需要确保两个列表具有各不相同的属性，则可以将 fieldPath 设置到其中任一列表，例如 .testList。 它支持使用子操作引用现有字段，而不支持列表的数字索引。 有关更多信息，请参阅 Kubernetes 中的 JSONPath 支持。 因为其不支持数组的数字索引，所以对于包含特殊字符的字段名称，请使用 ['specialName'] 来引用字段名称。 例如，对于出现在列表 testList 中的属性 foo.34$，fieldPath 可以设置为 .testList['foo.34$']。

  • x-kubernetes-validations.message (string)

    message 表示验证失败时显示的消息。如果规则包含换行符，则需要该消息。消息不能包含换行符。 如果未设置，则消息为 "failed rule: {Rule}"，如："must be a URL with the host matching spec.host"

  • x-kubernetes-validations.messageExpression (string)

    messageExpression 声明一个 CEL 表达式，其计算结果是此规则失败时返回的验证失败消息。 由于 messageExpression 用作失败消息，因此它的值必须是一个字符串。 如果在规则中同时存在 message 和 messageExpression，则在验证失败时使用 messageExpression。 如果是 messageExpression 出现运行时错误，则会记录运行时错误，并生成验证失败消息， 就好像未设置 messageExpression 字段一样。如果 messageExpression 求值为空字符串、 只包含空格的字符串或包含换行符的字符串，则验证失败消息也将像未设置 messageExpression 字段一样生成， 并记录 messageExpression 生成空字符串/只包含空格的字符串/包含换行符的字符串的事实。 messageExpression 可以访问的变量与规则相同；唯一的区别是返回类型。 例如："x must be less than max ("+string(self.max)+")"。

  • x-kubernetes-validations.optionalOldSelf (boolean)

    即使在对象首次创建时，或者旧对象无值时，也可以使用 optionalOldSelf 来使用转换规则求值。

    当启用了 optionalOldSelf 时，oldSelf 将是 CEL 可选项，如果没有旧值或最初创建对象时，其值将为 None。

    你可以使用 oldSelf.hasValue() 检查 oldSelf 是否存在，并在检查后使用 oldSelf.value() 将其解包。 更多的信息可查看 CEL 文档中的 Optional 类型：https://pkg.go.dev/github.com/google/cel-go/cel#OptionalTypes

    除非在 rule 中使用了 oldSelf，否则不可以设置。

  • x-kubernetes-validations.reason (string)

    reason 提供机器可读的验证失败原因，当请求未通过此验证规则时，该原因会返回给调用者。 返回给调用者的 HTTP 状态代码将与第一个失败的验证规则的原因相匹配。 目前支持的原因有：FieldValueInvalid、FieldValueForbidden、FieldValueRequired、FieldValueDuplicate。 如果未设置，则默认使用 FieldValueInvalid。 所有未来添加的原因在读取该值时必须被客户端接受，未知原因应被视为 FieldValueInvalid。

    可能的枚举值：

    • "FieldValueDuplicate" 用于报告取值必须唯一的值之间的冲突（例如，唯一 ID）。
    • "FieldValueForbidden" 用于报告在某些条件下可接受（根据格式规则），但当前条件下不允许的合法值（例如，安全策略）。
    • "FieldValueInvalid" 用于报告格式错误的值（例如，正则表达式匹配失败、过长、越界）。
    • "FieldValueRequired" 用于报告未提供的必需值（例如，空字符串、null 值或空数组）。

CustomResourceDefinitionStatus

CustomResourceDefinitionStatus 表示 CustomResourceDefinition 的状态。

• acceptedNames (CustomResourceDefinitionNames)

  acceptedNames 是实际用于服务发现的名称。它们可能与规约（spec）中的名称不同。

  CustomResourceDefinitionNames 表示提供此 CustomResourceDefinition 资源的名称。

  • acceptedNames.kind (string)，必需

    kind 是资源的序列化类型。它通常是驼峰命名的单数形式。 自定义资源实例将使用此值作为 API 调用中的 kind 属性。

  • acceptedNames.plural (string)，必需

    plural 是所提供的资源的复数名称，自定义资源在 /apis/<group>/<version>/.../<plural> 下提供。 必须与 CustomResourceDefinition 的名称匹配（格式为 <names.plural>.<group>）。必须全部小写。

  • acceptedNames.categories ([]string)

    原子：将在合并期间被替换

    categories 是此自定义资源所属的分组资源列表（例如 'all'）。 它在 API 发现文档中发布，并被客户端用于支持像 kubectl get all 这样的调用。

  • acceptedNames.listKind (string)

    listKind 是此资源列表的序列化类型。默认为 "<kind>List"。

  • acceptedNames.shortNames ([]string)

    原子：将在合并期间被替换

    shortNames 是资源的短名称，在 API 发现文档中公开，并支持客户端调用，如 kubectl get <shortname>。必须全部小写。

  • acceptedNames.singular (string)

    singular 是资源的单数名称。必须全部小写。默认为小写形式的 kind。

• conditions ([]CustomResourceDefinitionCondition)

  Map：合并时将保留 type 键的唯一值

  conditions 表示 CustomResourceDefinition 特定方面的状态

  CustomResourceDefinitionCondition 包含此 Pod 当前状况的详细信息。

  • conditions.status (string)，必需

    status 表示状况（Condition）的状态，取值为 True、False 或 Unknown 之一。

  • conditions.type (string)，必需

    type 是条件的类型。类型包括：Established、NamesAccepted 和 Terminating。

  • conditions.lastTransitionTime (Time)

    lastTransitionTime 是上一次发生状况状态转换的时间。

    Time 是对 time.Time 的封装。Time 支持对 YAML 和 JSON 进行正确封包。 为 time 包的许多函数方法提供了封装器。

  • conditions.message (string)

    message 是有关上次转换的详细可读信息。

  • conditions.observedGeneration (int64)

    observedGeneration 表示状况被设置时所依据的 .metadata.generation 值。 例如，如果 .metadata.generation 当前为 12，但 .status.conditions[x].observedGeneration 为 9，则该状况相对于实例的当前状态已过时。

  • conditions.reason (string)

    reason 表述状况上次转换原因的、驼峰格式命名的、唯一的一个词。

• observedGeneration (int64)

  CRD 控制器观测到的世代值。

• storedVersions ([]string)

  原子：将在合并期间被替换

  storedVersions 列出了曾经被持久化的所有 CustomResources 版本。跟踪这些版本可以为 etcd 中的存储版本提供迁移路径。 该字段是可变的，因此迁移控制器可以完成到另一个版本的迁移（确保存储中没有遗留旧对象），然后从该列表中删除其余版本。 当版本在此列表中时，则不能从 spec.versions 中删除。

CustomResourceDefinitionList

CustomResourceDefinitionList 是 CustomResourceDefinition 对象的列表。

• items ([]CustomResourceDefinition)，必需

  items 列出单个 CustomResourceDefinition 对象。

• apiVersion (string)

  apiVersion 定义对象表示的版本化模式。服务器应将已识别的模式转换为最新的内部值，并可能拒绝未识别的值。 更多信息：https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources

• kind (string)

  kind 是一个字符串值，表示该对象所表示的 REST 资源。服务器可以从客户端提交请求的端点推断出 REST 资源。 不能被更新。驼峰命名。更多信息： https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds

• metadata (ListMeta)

  标准的对象元数据，更多信息： https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata

Operations

get 读取指定的 CustomResourceDefinition

HTTP 请求

GET /apis/apiextensions.k8s.io/v1/customresourcedefinitions/{name}

参数

• name （路径参数）：string，必需

  CustomResourceDefinition 的名称。

• pretty （查询参数）：string

  pretty

响应

200 (CustomResourceDefinition): OK

401: Unauthorized

get 读取指定 CustomResourceDefinition 的状态

HTTP 请求

GET /apis/apiextensions.k8s.io/v1/customresourcedefinitions/{name}/status

参数

• name （路径参数）：string，必需

  CustomResourceDefinition 的名称。

• pretty （查询参数）：string

  pretty

响应

200 (CustomResourceDefinition): OK

401: Unauthorized

list 列出或观察 CustomResourceDefinition 类型的对象

HTTP 请求

GET /apis/apiextensions.k8s.io/v1/customresourcedefinitions

参数

• allowWatchBookmarks （查询参数）：boolean

  allowWatchBookmarks

• continue （查询参数）：string

  continue

• fieldSelector （查询参数）：string

  fieldSelector

• labelSelector （查询参数）：string

  labelSelector

• limit （查询参数）：integer

  limit

• pretty （查询参数）：string

  pretty

• resourceVersion （查询参数）：string

  resourceVersion

• resourceVersionMatch （查询参数）：string

  resourceVersionMatch

• sendInitialEvents （查询参数）: boolean

  sendInitialEvents

• timeoutSeconds （查询参数）：integer

  timeoutSeconds

• watch （查询参数）：boolean

  watch

响应

200 (CustomResourceDefinitionList): OK

401: Unauthorized

create 创建一个 CustomResourceDefinition

HTTP 请求

POST /apis/apiextensions.k8s.io/v1/customresourcedefinitions

参数

• body：CustomResourceDefinition，必需

• dryRun （查询参数）：string

  dryRun

• fieldManager （查询参数）：string

  fieldManager

• fieldValidation （查询参数）：string

  fieldValidation

• pretty （查询参数）：string

  pretty

响应

200 (CustomResourceDefinition): OK

201 (CustomResourceDefinition): Created

202 (CustomResourceDefinition): Accepted

401: Unauthorized

update 替换指定的 CustomResourceDefinition

HTTP 请求

PUT /apis/apiextensions.k8s.io/v1/customresourcedefinitions/{name}

参数

• name （路径参数）：string，必需

  CustomResourceDefinition 的名称。

• body：CustomResourceDefinition，必需

• dryRun （查询参数）：string

  dryRun

• fieldManager （查询参数）：string

  fieldManager

• fieldValidation （查询参数）：string

  fieldValidation

• pretty （查询参数）：string

  pretty

响应

200 (CustomResourceDefinition): OK

201 (CustomResourceDefinition): Created

401: Unauthorized

update 替换指定 CustomResourceDefinition 的状态

HTTP 请求

PUT /apis/apiextensions.k8s.io/v1/customresourcedefinitions/{name}/status

参数

• name （路径参数）：string，必需

  CustomResourceDefinition 的名称。

• body：CustomResourceDefinition，必需

• dryRun （查询参数）：string

  dryRun

• fieldManager （查询参数）：string

  fieldManager

• fieldValidation （查询参数）：string

  fieldValidation

• pretty （查询参数）：string

  pretty

响应

200 (CustomResourceDefinition): OK

201 (CustomResourceDefinition): Created

401: Unauthorized

patch 部分更新指定的 CustomResourceDefinition

HTTP 请求

PATCH /apis/apiextensions.k8s.io/v1/customresourcedefinitions/{name}

参数

• name （路径参数）：string，必需

  CustomResourceDefinition 的名称。

• body：Patch，必需

• dryRun （查询参数）：string

  dryRun

• fieldManager （查询参数）：string

  fieldManager

• fieldValidation （查询参数）：string

  fieldValidation

• force （查询参数）：boolean

  force

• pretty（查询参数）：string

  pretty

响应

200 (CustomResourceDefinition): OK

201 (CustomResourceDefinition): Created

401: Unauthorized

patch 部分更新指定 CustomResourceDefinition 的状态

HTTP 请求

PATCH /apis/apiextensions.k8s.io/v1/customresourcedefinitions/{name}/status

参数

• name （路径参数）：string，必需

  CustomResourceDefinition 的名称。

• body：Patch，必需

• dryRun （查询参数）：string

  dryRun

• fieldManager （查询参数）：string

  fieldManager

• fieldValidation （查询参数）：string

  fieldValidation

• force （查询参数）：boolean

  force

• pretty （查询参数）：string

  pretty

响应

200 (CustomResourceDefinition): OK

201 (CustomResourceDefinition): Created

401: Unauthorized

delete 删除一个 CustomResourceDefinition

HTTP 请求

DELETE /apis/apiextensions.k8s.io/v1/customresourcedefinitions/{name}

参数

• name （路径参数）：string，必需

  CustomResourceDefinition 的名称。

• body：DeleteOptions

• dryRun （查询参数）：string

  dryRun

• gracePeriodSeconds （查询参数）：integer

  gracePeriodSeconds

• ignoreStoreReadErrorWithClusterBreakingPotential （查询参数）：boolean

  ignoreStoreReadErrorWithClusterBreakingPotential

• pretty （查询参数）：string

  pretty

• propagationPolicy （查询参数）：string

  propagationPolicy

响应

200 (Status): OK

202 (Status): Accepted

401: Unauthorized

deletecollection 删除 CustomResourceDefinition 的集合

HTTP 请求

DELETE /apis/apiextensions.k8s.io/v1/customresourcedefinitions

参数

• body：DeleteOptions

• continue （查询参数）：string

  continue

• dryRun （查询参数）：string

  dryRun

• fieldSelector （查询参数）：string

  fieldSelector

• gracePeriodSeconds （查询参数）：integer

  gracePeriodSeconds

• ignoreStoreReadErrorWithClusterBreakingPotential （查询参数）：boolean

  ignoreStoreReadErrorWithClusterBreakingPotential

• labelSelector （查询参数）：string

  labelSelector

• limit （查询参数）：integer

  limit

• pretty （查询参数）：string

  pretty

• propagationPolicy （查询参数）：string

  propagationPolicy

• resourceVersion （查询参数）：string

  resourceVersion

• resourceVersionMatch （查询参数）：string

  resourceVersionMatch

• sendInitialEvents （查询参数）: boolean

  sendInitialEvents

• timeoutSeconds （查询参数）：integer

  timeoutSeconds

响应

200 (Status): OK

401: Unauthorized

2 - DeviceClass

apiVersion: resource.k8s.io/v1

import "k8s.io/api/resource/v1"

DeviceClass

DeviceClass 是由供应商或管理员提供的资源，包含设备配置和选择算符。 它可以在申领的设备请求中被引用，以应用预设值。作用域为集群范围。

这是一个 Alpha 阶段的资源类别，需要启用 DynamicResourceAllocation 特性门控。

• apiVersion: resource.k8s.io/v1

• kind: DeviceClass

• metadata (ObjectMeta)

  标准的对象元数据。

• spec (DeviceClassSpec)，必需

  spec 定义可被分配的资源以及如何配置这类资源。

  此字段是可变更的。消费者必须准备好应对随时会变更的类，变更的原因可能是被更新或被替换。 申领分配是基于分配之时类中所设置的内容而确定的。

  变更 spec 会让 metadata.generation 编号自动递增。

DeviceClassSpec

DeviceClassSpec 在 DeviceClass 中用于定义可被分配的资源以及如何配置这类资源。

• config ([]DeviceClassConfiguration)

  原子：将在合并期间被替换

  config 定义适用于通过此类申领的每个设备的配置参数。 某些类可能会由多个驱动所满足，因此供应商配置的每个实例仅适用于一个驱动。

  这些配置参数被传递给驱动，但在分配申领时不考虑这些配置参数。

  DeviceClassConfiguration 在 DeviceClass 中使用。

  • config.opaque (OpaqueDeviceConfiguration)

    opaque 提供特定于驱动的配置参数。

    OpaqueDeviceConfiguration 以驱动供应商所定义的格式提供驱动的配置参数。

    • config.opaque.driver (string)，必需

      driver 用于确定需要将这些配置参数传递给哪个 kubelet 插件。

      驱动开发者所提供的准入策略可以使用此字段来决定是否需要校验这些参数。

      必须是一个 DNS 子域，并且应以驱动供应商拥有的 DNS 域结尾。 应当只使用小写字母。

    • config.opaque.parameters (RawExtension)，必需

      parameters 可以包含任意数据。处理校验和版本控制是驱动开发者的责任。 通常这包括自我标识和版本信息（对 Kubernetes 而言即 "kind" + "apiVersion"），并在不同版本之间进行转换。

      原始数据的长度必须小于或等于 10 Ki。

      RawExtension 用于以外部版本来保存扩展数据。

      要使用它，请在外部、版本化的结构中生成一个字段，以 RawExtension 作为其类型，在内部结构中以 Object 作为其类型。 你还需要注册你的各个插件类型。

      // 内部包：

      ```go  
      type MyAPIObject struct {
        runtime.TypeMeta `json:",inline"`
        MyPlugin runtime.Object `json:"myPlugin"`
      }
      
      type PluginA struct {
        AOption string `json:"aOption"`
      }
      ```
      

      // 外部包：

      ```go
      type MyAPIObject struct {
        runtime.TypeMeta `json:",inline"`
        MyPlugin runtime.RawExtension `json:"myPlugin"`
      }
      
      type PluginA struct {
        AOption string `json:"aOption"`
      }
      ```
      

      // 在网络上，JSON 看起来像这样：

      ```json
      {
        "kind": "MyAPIObject",
        "apiVersion": "v1",
        "myPlugin": {
          "kind": "PluginA",
          "aOption": "foo",
        },
      }
      ```
      

      那么会发生什么？解码首先使用 JSON 或 YAML 将序列化数据解组到你的外部 MyAPIObject 中。 这会导致原始 JSON 被存储下来，但不会被解包。下一步是复制（使用 pkg/conversion）到内部结构中。 runtime 包的 DefaultScheme 安装了转换函数，它将解析存储在 RawExtension 中的 JSON， 将其转换为正确的对象类型，并将其存储在 Object 中。 （TODO：如果对象是未知类型，将创建并存储一个 runtime.Unknown 对象。）

• extendedResourceName (string)

  extendedResourceName 是此类设备的扩展资源名称。 此类中的设备可用于满足 Pod 的扩展资源请求。其格式与 Pod 扩展资源的名称相同。 在一个集群中，它应当是唯一的。如果两个设备类具有相同的名称，则后创建的设备类将用于满足 Pod 的扩展资源请求。 如果两个类被同时创建，则选择名称按字母排序后位于前面的类。

  这是 Alpha 字段。

• selectors ([]DeviceSelector)

  原子：将在合并期间被替换

  通过此类所申领的设备必须满足这里的每个选择算符。

  DeviceSelector 中必须设置且仅设置一个字段。

  • selectors.cel (CELDeviceSelector)

    cel 包含用于选择设备的 CEL 表达式。

    CELDeviceSelector 包含用于选择设备的 CEL 表达式。

    • selectors.cel.expression (string)，必需

      expression 是一个 CEL 表达式，用于评估单个设备。 当被考虑的设备满足所需条件时，表达式的求值结果必须为 true；当不满足时，结果应为 false。 任何其他结果都是错误，会导致设备分配中止。

      表达式的输入是一个名为 "device" 的对象，具有以下属性：

      • driver (string)：定义此设备的驱动的名称。
      • attributes (map[string]object)：设备的属性，按前缀分组 （例如，device.attributes["dra.example.com"] 评估为一个对象，包含所有以 "dra.example.com" 为前缀的属性。）
      • capacity (map[string]object)：设备的容量，按前缀分组。
      • allowMultipleAllocations (bool)：设备的 allowMultipleAllocations 属性 （在 v1.34+ 中随 DRAConsumableCapacity 特性启用）。

      示例：考虑一个驱动为 "dra.example.com" 的设备，它暴露两个名为 "model" 和 "ext.example.com/family" 的属性， 并且暴露一个名为 "modules" 的容量。此表达式的输入将具有以下字段：

      device.driver
      device.attributes["dra.example.com"].model
      device.attributes["ext.example.com"].family
      device.capacity["dra.example.com"].modules
      

      device.driver 字段可用于检查特定驱动，既可以作为高层次的前提条件（即你只想考虑来自此驱动的设备）， 也可以作为考虑来自不同驱动的设备的多子句表达式的一部分。

      attribute 中每个元素的值类型由设备定义，编写这些表达式的用户必须查阅其特定驱动的文档。 capacity 中元素的值类型为 Quantity。

      如果在 device.attributes 或 device.capacity 中使用未知前缀进行查找， 将返回一个空映射。对未知字段的任何引用将导致评估错误和分配中止。

      一个健壮的表达式应在引用属性之前检查其是否存在。

      为了方便使用，cel.bind() 函数被启用，此函数可用于简化访问同一域的多个属性的表达式。例如：

      cel.bind(dra, device.attributes["dra.example.com"], dra.someBool && dra.anotherBool)
      

      表达式的长度必须小于或等于 10 Ki。根据估计的逻辑步骤数，其评估成本也受到限制。

DeviceClassList

DeviceClassList 是类的集合。

• apiVersion: resource.k8s.io/v1

• kind: DeviceClassList

• metadata (ListMeta)

  标准的列表元数据。

• items ([]DeviceClass)，必需

  items 是资源类的列表。

操作

get 读取指定的 DeviceClass

HTTP 请求

GET /apis/resource.k8s.io/v1/deviceclasses/{name}

参数

• name（路径参数）：string，必需

  DeviceClass 的名称。

• pretty（查询参数）：string

  pretty

响应

200 (DeviceClass): OK

401: Unauthorized

list 列举或监视 DeviceClass 类别的对象

HTTP 请求

GET /apis/resource.k8s.io/v1/deviceclasses

参数

• allowWatchBookmarks (查询参数): boolean

  allowWatchBookmarks

• continue (查询参数): string

  continue

• fieldSelector (查询参数): string

  fieldSelector

• labelSelector (查询参数): string

  labelSelector

• limit (查询参数): integer

  limit

• pretty (查询参数): string

  pretty

• resourceVersion (查询参数): string

  resourceVersion

• resourceVersionMatch (查询参数): string

  resourceVersionMatch

• sendInitialEvents (查询参数): boolean

  sendInitialEvents

• timeoutSeconds (查询参数): integer

  timeoutSeconds

• watch (查询参数): boolean

  watch

响应

200 (DeviceClassList): OK

401: Unauthorized

create 创建 DeviceClass

HTTP 请求

POST /apis/resource.k8s.io/v1/deviceclasses

参数

• body: DeviceClass，必需

• dryRun (查询参数): string

  dryRun

• fieldManager (查询参数): string

  fieldManager

• fieldValidation (查询参数): string

  fieldValidation

• pretty (查询参数): string

  pretty

响应

200 (DeviceClass): OK

201 (DeviceClass): Created

202 (DeviceClass): Accepted

401: Unauthorized

update 替换指定的 DeviceClass

HTTP 请求

PUT /apis/resource.k8s.io/v1/deviceclasses/{name}

参数

• name (路径参数): string，必需

  DeviceClass 的名称。

• body: DeviceClass，必需

• dryRun (查询参数): string

  dryRun

• fieldManager (查询参数): string

  fieldManager

• fieldValidation (查询参数): string

  fieldValidation

• pretty (查询参数): string

  pretty

响应

200 (DeviceClass): OK

201 (DeviceClass): Created

401: Unauthorized

patch 部分更新指定的 DeviceClass

HTTP 请求

PATCH /apis/resource.k8s.io/v1/deviceclasses/{name}

参数

• name (路径参数): string，必需

  DeviceClass 的名称。

• body: Patch，必需

• dryRun (查询参数): string

  dryRun

• fieldManager (查询参数): string

  fieldManager

• fieldValidation (查询参数): string

  fieldValidation

• force (查询参数): boolean

  force

• pretty (查询参数): string

  pretty

响应

200 (DeviceClass): OK

201 (DeviceClass): Created

401: Unauthorized

delete 删除 DeviceClass

HTTP 请求

DELETE /apis/resource.k8s.io/v1/deviceclasses/{name}

参数

• name (路径参数): string，必需

  DeviceClass 的名称。

• body: DeleteOptions

• dryRun (查询参数): string

  dryRun

• gracePeriodSeconds (查询参数): integer

  gracePeriodSeconds

• ignoreStoreReadErrorWithClusterBreakingPotential (查询参数): boolean

  ignoreStoreReadErrorWithClusterBreakingPotential

• pretty (查询参数): string

  pretty

• propagationPolicy (查询参数): string

  propagationPolicy

响应

200 (DeviceClass): OK

202 (DeviceClass): Accepted

401: Unauthorized

deletecollection 删除 DeviceClass 的集合

HTTP 请求

DELETE /apis/resource.k8s.io/v1/deviceclasses

参数

• body: DeleteOptions

• continue (查询参数): string

  continue

• dryRun (查询参数): string

  dryRun

• fieldSelector (查询参数): string

  fieldSelector

• gracePeriodSeconds (查询参数): integer

  gracePeriodSeconds

• ignoreStoreReadErrorWithClusterBreakingPotential (查询参数): boolean

  ignoreStoreReadErrorWithClusterBreakingPotential

• labelSelector (查询参数): string

  labelSelector

• limit (查询参数): integer

  limit

• pretty (查询参数): string

  pretty

• propagationPolicy (查询参数): string

  propagationPolicy

• resourceVersion (查询参数): string

  resourceVersion

• resourceVersionMatch (查询参数): string

  resourceVersionMatch

• sendInitialEvents (查询参数): boolean

  sendInitialEvents

• timeoutSeconds (查询参数): integer

  timeoutSeconds

响应

200 (Status): OK

401: Unauthorized

3 - MutatingWebhookConfiguration

apiVersion: admissionregistration.k8s.io/v1

import "k8s.io/api/admissionregistration/v1"

MutatingWebhookConfiguration

MutatingWebhookConfiguration 描述准入 Webhook 的配置，该 Webhook 可接受或拒绝对象请求，并且可能变更对象。

• apiVersion：admissionregistration.k8s.io/v1

• kind：MutatingWebhookConfiguration

• metadata (ObjectMeta)

  标准的对象元数据，更多信息： https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata。

• webhooks ([]MutatingWebhook)

  补丁策略：根据 name 键执行合并操作

  映射：基于 name 键的唯一值将在合并期间被保留

  webhooks 是 Webhook 及其所影响的资源和操作的列表。

  MutatingWebhook 描述了一个准入 Webhook 及其适用的资源和操作。

  • webhooks.admissionReviewVersions ([]string)，必需

    原子性：将在合并期间被替换

    admissionReviewVersions 是 Webhook 期望的 AdmissionReview 版本的优选顺序列表。 API 服务器将尝试使用它所支持的版本列表中的第一个版本。如果 API 服务器不支持此列表中设置的任何版本，则此对象将验证失败。 如果持久化的 Webhook 配置指定了所允许的版本，但其中不包括 API 服务器所知道的任何版本， 则对 Webhook 的调用将失败并根据失败策略进行处理。

  • webhooks.clientConfig (WebhookClientConfig)，必需

    clientConfig 定义了如何与 Webhook 通信。必需。

    WebhookClientConfig 包含与 Webhook 建立 TLS 连接的信息

    • webhooks.clientConfig.caBundle ([]byte)

      caBundle 是一个 PEM 编码的 CA 包，将用于验证 Webhook 的服务证书。 如果未指定，则使用 apiserver 上的系统信任根。

    • webhooks.clientConfig.service (ServiceReference)

      service 是对此 Webhook 的服务的引用。必须指定 service 或 url 之一。

      如果 Webhook 在集群中运行，那么你应该使用 service。

      ServiceReference 包含对 Service.legacy.k8s.io 的引用

      • webhooks.clientConfig.service.name (string)，必需

        name 是服务的名称。必需。

      • webhooks.clientConfig.service.namespace (string)，必需

        namespace 是服务的命名空间。必需。

      • webhooks.clientConfig.service.path (string)

        path 是一个可选的 URL 路径，在针对此服务的所有请求中都会发送此路径。

      • webhooks.clientConfig.service.port (int32)

        如果指定了，则为托管 Webhook 的服务上的端口。默认为 443 以实现向后兼容。 port 应该是一个有效的端口号（包括 1-65535）。

    • webhooks.clientConfig.url (string)

      url 以标准 URL 形式（scheme://host:port/path）给出了 Webhook 的位置。 必须指定 url 或 service 中的一个。

      host 不能用来引用集群中运行的服务；这种情况应改用 service 字段。 在某些 API 服务器上，可能会通过外部 DNS 解析 host 值。 （例如，kube-apiserver 无法解析集群内 DNS，因为这会违反分层原理）。host 也可以是 IP 地址。

      请注意，使用 localhost 或 127.0.0.1 作为 host 是有风险的， 除非你非常小心地在运行 apiserver 的所有主机上运行此 Webhook， 而这些 API 服务器可能需要调用此 Webhook。此类部署可能是不可移植的， 即不容易在新集群中重复安装。

      该方案必须是 "https"；URL 必须以 "https://" 开头。

      路径是可选的，如果存在，可以是 URL 中允许的任何字符串。你可以使用路径将任意字符串传递给 Webhook，例如集群标识符。

      不允许使用用户或基本身份验证，例如不允许使用 “user:password@”。 不允许使用片段（“#...”）和查询参数（“?...”）。

  • webhooks.name (string)，必需

    准入 Webhook 的名称。应该是完全限定的名称，例如 imagepolicy.kubernetes.io，其中 imagepolicy 是 Webhook 的名称，kubernetes.io 是组织的名称。必需。

  • webhooks.sideEffects (string)，必需

    sideEffects 说明此 Webhook 是否有副作用。可接受的值为：None、NoneOnDryRun （通过 v1beta1 创建的 Webhook 也可以指定 Some 或 Unknown）。 具有副作用的 Webhook 必须实现协调系统，因为请求可能会被准入链中的未来步骤拒绝，因此需要能够撤消副作用。 如果请求与带有 sideEffects == Unknown 或 Some 的 Webhook 匹配，则带有 dryRun 属性的请求将被自动拒绝。

    可能的枚举值：

    • "None" 表示调用 Webhook 不会产生任何副作用。
    • "NoneOnDryRun" 表示调用 Webhook 可能会产生副作用， 但如果被审查的请求具有 dry-run 属性，则会抑制这些副作用。
    • "Some" 表示调用 Webhook 可能会产生副作用。如果带有 dry-run 属性的请求触发了对此 Webhook 的调用，该请求将会失败。
    • "Unknown" 表示对调用 Webhook 是否会产生副作用未知。如果带有 dry-run 属性的请求触发了对此 Webhook 的调用，该请求将会失败。

  • webhooks.failurePolicy (string)

    failurePolicy 定义如何处理来自准入端点的无法识别的错误 - 允许的值是 Ignore 或 Fail。默认为 Fail。

    可能的枚举值：

    • "Fail" 表示调用 Webhook 出错会导致准入失败。
    • "Ignore" 表示调用 Webhook 出错将被忽略。

  • webhooks.matchConditions ([]MatchCondition)

    补丁策略：根据 name 键执行合并操作

    映射：键 name 的唯一值将在合并过程中保留

    matchConditions 是将请求发送到此 webhook 之前必须满足的条件列表。 匹配条件过滤已经被 rules、namespaceSelector、objectSelector 匹配的请求。 matchConditions 取值为空列表时匹配所有请求。最多允许 64 个匹配条件。

    精确匹配逻辑是（按顺序）：

    1. 如果任一 matchCondition 的计算结果为 FALSE，则跳过该 Webhook。
    2. 如果所有 matchConditions 的计算结果为 TRUE，则调用该 Webhook。
    3. 如果任一 matchCondition 的计算结果为错误（但都不是 FALSE）：
       • 如果 failurePolicy=Fail，拒绝该请求；
       • 如果 failurePolicy=Ignore，忽略错误并跳过该 Webhook。

    MatchCondition 表示将请求发送到 Webhook 之前必须满足的条件。

    • webhooks.matchConditions.expression (string)，必需

      expression 表示将由 CEL 求值的表达式。求值结果必须是 bool 值。CEL 表达式可以访问 以 CEL 变量的形式给出的 AdmissionRequest 和 Authorizer 的内容：

      • 'object' - 来自传入请求的对象。对于 DELETE 请求，该值为 null。

      • 'oldObject' - 现有对象。对于 CREATE 请求，该值为 null。

      • 'request' - 准入请求的属性(/pkg/apis/admission/types.go#AdmissionRequest)。

      • 'authorizer' - CEL 授权者。可用于对请求的主体（用户或服务账号）执行授权检查。

        参阅： https://pkg.go.dev/k8s.io/apiserver/pkg/cel/library#Authz

      • 'authorizer.requestResource' - CEL ResourceCheck 从"授权方"构建并配置请求资源。

      CEL 文档： https://kubernetes.io/zh-cn/docs/reference/using-api/cel/

      此字段为必需字段。

      • webhooks.matchConditions.name (string)，必需

      name 是此匹配条件的标识符，用于 MatchConditions 的策略性合并， 以及提供用于日志目的的标识符。一个好的 name 应该是对相关表达式的描述。 name 必须是由字母数字字符 -、_ 或 . 组成的限定名称， 并且必须以字母、数字字符开头和结尾（例如 MyName、my.name 或 123-abc， 用于验证 name 的正则表达式是 ([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9]）。 带有可选的 DNS 子域前缀和 /（例如 example.com/MyName）

      此字段为必需字段。

  • webhooks.matchPolicy (string)

    matchPolicy 定义了如何使用 rules 列表来匹配传入的请求。允许的值为 Exact 或 Equivalent。

    • Exact：仅当请求与指定规则完全匹配时才匹配请求。 例如，如果可以通过 apps/v1、apps/v1beta1 和 extensions/v1beta1 修改 deployments 资源， 但 “rules” 仅包含 apiGroups:["apps"]、apiVersions:["v1"]、resources:["deployments"]， 对 apps/v1beta1 或 extensions/v1beta1 的请求不会被发送到 Webhook。

    • Equivalent：如果针对的资源包含在 rules 中，即使请求是通过另一个 API 组或版本提交，也会匹配。 例如，如果可以通过 apps/v1、apps/v1beta1 和 extensions/v1beta1 修改 deployments 资源， 并且 rules 仅包含 apiGroups:["apps"]、apiVersions:["v1"]、resources:["deployments "]， 对 apps/v1beta1 或 extensions/v1beta1 的请求将被转换为 apps/v1 并发送到 Webhook。

    默认为 "Equivalent"。

    可能的枚举值：

    • "Equivalent" 表示如果请求通过另一个 API 组或版本修改规则中列出的资源， 则应将请求发送到 Webhook。
    • "Exact" 表示仅当请求与给定规则完全匹配时，才应将请求发送到 Webhook。

  • webhooks.namespaceSelector (LabelSelector)

    namespaceSelector 根据对象的命名空间是否与 selector 匹配来决定是否在该对象上运行 Webhook。 如果对象本身是 Namespace，则针对 object.metadata.labels 执行匹配。 如果对象是其他集群作用域资源，则永远不会跳过 Webhook 的匹配动作。

    例如，为了针对 runlevel 不为 “0” 或 “1” 的名字空间中的所有对象运行 Webhook； 你可以按如下方式设置 selector：

    "namespaceSelector": {
      "matchExpressions": [
        {
          "key": "runlevel",
          "operator": "NotIn",
          "values": [
            "0",
            "1"
          ]
        }
      ]
    }
    

    相反，如果你只想针对 “environment” 为 “prod” 或 “staging” 的名字空间中的对象运行 Webhook； 你可以按如下方式设置 selector：

    "namespaceSelector": {
      "matchExpressions": [
        {
          "key": "environment",
          "operator": "In",
          "values": [
            "prod",
            "staging"
          ]
        }
      ]
    }
    

    有关标签选择算符的更多示例，请参阅 https://kubernetes.io/zh-cn/docs/concepts/overview/working-with-objects/labels。

    默认为空的 LabelSelector，匹配所有对象。

  • webhooks.objectSelector (LabelSelector)

    objectSelector 根据对象是否具有匹配的标签来决定是否运行 Webhook。 objectSelector 针对将被发送到 Webhook 的 oldObject 和 newObject 进行评估，如果任一对象与选择器匹配，则视为匹配。 空对象（create 时为 oldObject，delete 时为 newObject）或不能有标签的对象（如 DeploymentRollback 或 PodProxyOptions 对象） 认为是不匹配的。 仅当 Webhook 支持时才能使用对象选择器，因为最终用户可以通过设置标签来跳过准入 Webhook。 默认为空的 LabelSelector，匹配所有内容。

  • webhooks.reinvocationPolicy (string)

    reinvocationPolicy 表示这个 Webhook 是否可以被多次调用，作为一次准入评估的一部分。 可取值有 "Never" 和 "IfNeeded"。

    • Never：在一次录取评估中，Webhook 被调用的次数不会超过一次。
    • IfNeeded：如果被录取的对象在被最初的 Webhook 调用后又被其他录取插件修改， 那么该 Webhook 将至少被额外调用一次作为录取评估的一部分。 指定此选项的 Webhook 必须是幂等的，能够处理它们之前承认的对象。 注意：不保证额外调用的次数正好为1。 如果额外的调用导致对对象的进一步修改，Webhook 不保证会再次被调用。 使用该选项的 Webhook 可能会被重新排序，以最小化额外调用的数量。 在保证所有的变更都完成后验证一个对象，使用验证性质的准入 Webhook 代替。

    默认值为 "Never"。

    可能的枚举值：

    • "IfNeeded" 表示如果被准入的对象在初次变更调用后被其他准入插件修改， 则作为准入评估的一部分，可能会再次调用此变更。
    • "Never" 表示在一个单一的准入评估中，不得多次调用此变更。

  • webhooks.rules ([]RuleWithOperations)

    原子性：将在合并期间被替换

    rules 描述了 Webhook 关心的资源/子资源上有哪些操作。Webhook 关心操作是否匹配任何 rules。 但是，为了防止 ValidatingAdmissionWebhooks 和 MutatingAdmissionWebhooks 将集群置于只能完全禁用插件才能恢复的状态， ValidatingAdmissionWebhooks 和 MutatingAdmissionWebhooks 永远不会在处理 ValidatingWebhookConfiguration 和 MutatingWebhookConfiguration 对象的准入请求时被调用。

    RuleWithOperations 是操作和资源的元组。建议确保所有元组组合都是有效的。

    • webhooks.rules.apiGroups ([]string)

      Atomic：将在合并期间被替换

      apiGroups 是资源所属的 API 组列表。* 是所有组。 如果存在 *，则列表的长度必须为 1。必需。

    • webhooks.rules.apiVersions ([]string)

      Atomic: 将在合并期间被替换

      apiVersions 是资源所属的 API 版本列表。* 是所有版本。 如果存在 *，则列表的长度必须为 1。必需。

    • webhooks.rules.operations ([]string)

      Atomic: 将在合并期间被替换

      operations 是准入 Webhook 所关心的操作 —— CREATE、UPDATE、DELETE、CONNECT 或用来指代所有已知操作以及将来可能添加的准入操作的 *。 如果存在 *，则列表的长度必须为 1。必需。

    • webhooks.rules.resources ([]string)

      原子性：将在合并期间被替换

      resources 是此规则适用的资源列表。

      • pods 表示 pods，'pods/log' 表示 pods 的日志子资源。* 表示所有资源，但不是子资源。
      • pods/* 表示 pods 的所有子资源,
      • */scale 表示所有 scale 子资源,
      • */* 表示所有资源及其子资源。

      如果存在通配符，则验证规则将确保资源不会相互重叠。

      根据所指定的对象，可能不允许使用子资源。必需。

    • webhooks.rules.scope (string)

      scope 指定此规则的范围。有效值为 “Cluster”, “Namespaced” 和 “”。 “Cluster” 表示只有集群范围的资源才会匹配此规则。 Namespace API 对象是集群范围的。 “Namespaced” 意味着只有命名空间作用域的资源会匹配此规则。 “” 表示没有范围限制。 子资源与其父资源的作用域相同。默认为 “*”。

      可能的枚举值：

      • "*" 表示包含所有范围。
      • "Cluster" 表示范围限于集群范围的对象。命名空间对象是集群范围的。
      • "Namespaced" 表示范围限于命名空间范围的对象。

  • webhooks.timeoutSeconds (int32)

    timeoutSeconds 指定此 Webhook 的超时时间。 超时后，Webhook 的调用将被忽略或 API 调用将根据失败策略失败。 超时值必须在 1 到 30 秒之间。默认为 10 秒。

MutatingWebhookConfigurationList

MutatingWebhookConfigurationList 是 MutatingWebhookConfiguration 的列表。

• apiVersion: admissionregistration.k8s.io/v1

• kind: MutatingWebhookConfigurationList

• metadata (ListMeta)

  标准的对象元数据，更多信息： https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds

• items ([]MutatingWebhookConfiguration)，必需

  MutatingWebhookConfiguration 列表。

操作

get 读取指定的 MutatingWebhookConfiguration

HTTP 请求

GET /apis/admissionregistration.k8s.io/v1/mutatingwebhookconfigurations/{name}

参数

• name（路径参数）：string，必需

  MutatingWebhookConfiguration 的名称。

• pretty（查询参数）：string

  pretty

响应

200 (MutatingWebhookConfiguration): OK

401: Unauthorized

list 列出或观察 MutatingWebhookConfiguration 类型的对象

HTTP 请求

GET /apis/admissionregistration.k8s.io/v1/mutatingwebhookconfigurations

参数

• allowWatchBookmarks（查询参数）：boolean

  allowWatchBookmarks

• continue（查询参数）：string

  continue

• fieldSelector（查询参数）：string

  fieldSelector

• fieldSelector（查询参数）：string

  fieldSelector

• limit（查询参数）：integer

  limit

• pretty（查询参数）：string

  pretty

• resourceVersion（查询参数）：string

  resourceVersion

• resourceVersionMatch（查询参数）：string

  resourceVersionMatch

• sendInitialEvents（查询参数）：boolean

  sendInitialEvents

• timeoutSeconds（查询参数）：integer

  timeoutSeconds

• watch（查询参数）：boolean

  watch

响应

200 (MutatingWebhookConfigurationList): OK

401: Unauthorized

create 创建一个 MutatingWebhookConfiguration

HTTP 请求

POST /apis/admissionregistration.k8s.io/v1/mutatingwebhookconfigurations

参数

• body: MutatingWebhookConfiguration，必需

• dryRun（查询参数）：string

  dryRun

• fieldManager（查询参数）：string

  fieldManager

• fieldValidation（查询参数）：string

  fieldValidation

• pretty（查询参数）：string

  pretty

响应

200 (MutatingWebhookConfiguration): OK

201 (MutatingWebhookConfiguration): Created

202 (MutatingWebhookConfiguration): Accepted

401: Unauthorized

update 替换指定的 MutatingWebhookConfiguration

HTTP 请求

PUT /apis/admissionregistration.k8s.io/v1/mutatingwebhookconfigurations/{name}

参数

• name（路径参数）：string，必需

  MutatingWebhookConfiguration 的名称。

• body: MutatingWebhookConfiguration，必需

• dryRun（查询参数）：string

  dryRun

• fieldManager（查询参数）：string

  fieldManager

• fieldValidation（查询参数）：string

  fieldValidation

• pretty（查询参数）：string

  pretty

响应

200 (MutatingWebhookConfiguration): OK

201 (MutatingWebhookConfiguration): Created

401: Unauthorized

patch 部分更新指定的 MutatingWebhookConfiguration

HTTP 请求

PATCH /apis/admissionregistration.k8s.io/v1/mutatingwebhookconfigurations/{name}

参数

• name（路径参数）：string，必需

  MutatingWebhookConfiguration 的名称。

• body: Patch，必需

• dryRun（查询参数）：string

  dryRun

• fieldManager（查询参数）：string

  fieldManager

• fieldValidation（查询参数）：string

  fieldValidation

• force（查询参数）：boolean

  force

• pretty（查询参数）：string

  pretty

响应

200 (MutatingWebhookConfiguration): OK

201 (MutatingWebhookConfiguration): Created

401: Unauthorized

delete 删除 MutatingWebhookConfiguration

HTTP 请求

DELETE /apis/admissionregistration.k8s.io/v1/mutatingwebhookconfigurations/{name}

参数

• name（路径参数）：string，必需

  MutatingWebhookConfiguration 的名称。

• body: DeleteOptions

• dryRun（查询参数）：string

  dryRun

• gracePeriodSeconds（查询参数）：integer

  gracePeriodSeconds

• ignoreStoreReadErrorWithClusterBreakingPotential（查询参数）：boolean

  ignoreStoreReadErrorWithClusterBreakingPotential

• pretty（查询参数）：string

  pretty

• propagationPolicy（查询参数）：string

  propagationPolicy

响应

200 (Status): OK

202 (Status): Accepted

401: Unauthorized

deletecollection 删除 MutatingWebhookConfiguration 的集合

HTTP 请求

DELETE /apis/admissionregistration.k8s.io/v1/mutatingwebhookconfigurations

参数

• body: DeleteOptions

• continue（查询参数）：string

  continue

• dryRun（查询参数）：string

  dryRun

• fieldSelector（查询参数）：string

  fieldSelector

• gracePeriodSeconds（查询参数）：integer

  gracePeriodSeconds

• ignoreStoreReadErrorWithClusterBreakingPotential（查询参数）：boolean

  ignoreStoreReadErrorWithClusterBreakingPotential

• labelSelector（查询参数）：string

  labelSelector

• limit（查询参数）：integer

  limit

• pretty（查询参数）：string

  pretty

• propagationPolicy（查询参数）：string

  propagationPolicy

• resourceVersion（查询参数）：string

  resourceVersion

• resourceVersionMatch（查询参数）：string

  resourceVersionMatch

• sendInitialEvents（查询参数）：boolean

  sendInitialEvents

• timeoutSeconds（查询参数）：integer

  timeoutSeconds

响应

200 (Status): OK

401: Unauthorized

4 - ValidatingWebhookConfiguration

apiVersion: admissionregistration.k8s.io/v1

import "k8s.io/api/admissionregistration/v1"

ValidatingWebhookConfiguration

ValidatingWebhookConfiguration 描述准入 Webhook 的配置，此 Webhook 可在不更改对象的情况下接受或拒绝对象请求。

• apiVersion: admissionregistration.k8s.io/v1

• kind: ValidatingWebhookConfiguration

• metadata (ObjectMeta)

  标准的对象元数据，更多信息： https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata。

• webhooks ([]ValidatingWebhook)

  补丁策略：根据 name 键执行合并操作

  Map：name 键的唯一值将在合并期间保留

  webhooks 是 Webhook 以及受影响的资源和操作的列表。

  ValidatingWebhook 描述了一个准入 Webhook 及其适用的资源和操作。

  • webhooks.admissionReviewVersions ([]string)，必需

    Atomic：将在合并期间被替换

    admissionReviewVersions 是 Webhook 期望的优选 AdmissionReview 版本的有序列表。 API 服务器将尝试使用它支持的列表中的第一个版本。如果 API 服务器不支持此列表中指定的版本，则此对象将验证失败。 如果持久化的 Webhook 配置指定了允许的版本，并且不包括 API 服务器已知的任何版本，则对 Webhook 的调用将失败并受失败策略的约束。

  • webhooks.clientConfig (WebhookClientConfig)，必需

    clientConfig 定义了如何与 Webhook 通信。必需。

    WebhookClientConfig 包含与 Webhook 建立 TLS 连接的信息

    • webhooks.clientConfig.caBundle ([]byte)

      caBundle 是一个 PEM 编码的 CA 包，将用于验证 Webhook 的服务证书。 如果未指定，则使用 apiserver 上的系统信任根。

    • webhooks.clientConfig.service (ServiceReference)

      service 是对此 Webhook 服务的引用。必须指定 service 或 url。

      如果 Webhook 在集群中运行，那么你应该使用 service。

      ServiceReference 持有对 Service.legacy.k8s.io 的引用

      • webhooks.clientConfig.service.name (string)，必需

        name 是服务的名称。必需。

      • webhooks.clientConfig.service.namespace (string)，必需

        namespace 是服务的命名空间。必需。

      • webhooks.clientConfig.service.path (string)

        path 是一个可选的 URL 路径，它将发送任何请求到此服务。

      • webhooks.clientConfig.service.port (int32)

        如果指定，则为托管 Webhook 的服务上的端口。默认为 443 以实现向后兼容性。 port 应该是一个有效的端口号（包括 1-65535）。

    • webhooks.clientConfig.url (string)

      url 以标准 URL 形式（scheme://host:port/path）给出了 Webhook 的位置。 必须指定 url 或 service 中的一个。

      host 不应指代在集群中运行的服务；请改用 service 字段。在某些 apiserver 中，可能会通过外部 DNS 解析 host。 （例如，kube-apiserver 无法解析集群内 DNS，因为这会违反分层原理）。host 也可以是 IP 地址。

      请注意，使用 localhost 或 127.0.0.1 作为 host 是有风险的， 除非你非常小心地在运行 apiserver 的所有主机上运行此 Webhook， 而这些 API 服务器可能需要调用此 Webhook。此类部署可能是不可移植的，即不容易在新集群中重复安装。

      该方案必须是 "https"；URL 必须以 "https://" 开头。

      路径是可选的，如果存在，可以是 URL 中允许的任何字符串。你可以使用路径将任意字符串传递给 Webhook，例如集群标识符。

      不允许使用用户或基本身份验证，例如不允许使用 “user:password@”。 不允许使用片段（“#...”）和查询参数（“?...”）。

  • webhooks.name (string)，必需

    准入 Webhook 的名称。应该是完全限定的名称，例如 imagepolicy.kubernetes.io， 其中 imagepolicy 是 Webhook 的名称， kubernetes.io 是组织的名称。必需。

  • webhooks.sideEffects (string)，必需

  sideEffects 说明此 Webhook 是否有副作用。可接受的值为：None、NoneOnDryRun（通过 v1beta1 创建的 Webhook 也可以指定 Some 或 Unknown）。 具有副作用的 Webhook 必须实现协调系统，因为请求可能会被准入链中的未来步骤拒绝，因此需要能够撤消副作用。 如果请求与带有 sideEffects 为 Unknown 或 Some 的 Webhook 匹配，则带有 dryRun 属性的请求将被自动拒绝。

  可能的枚举值：

  • "None" 表示调用 Webhook 不会产生副作用。
  • "NoneOnDryRun" 表示调用 Webhook 可能会有副作用，但如果被审查的请求具有 dry-run 属性，则会抑制这些副作用。
  • "Some" 表示调用 Webhook 可能会有副作用。如果带有 dry-run 属性的请求会触发对此 Webhook 的调用，该请求将会失败。
  • "Unknown" 表示对调用 Webhook 的副作用不了解。如果带有 dry-run 属性的请求会触发对此 Webhook 的调用，该请求将会失败。
  • webhooks.failurePolicy (string)

  failurePolicy 定义了如何处理来自准入端点的无法识别的错误 - 允许的值是 Ignore 或 Fail。默认为 Fail。

  可能的枚举值：

  • "Fail" 表示调用 Webhook 发生错误时，准入操作将失败。
  • "Ignore" 表示调用 Webhook 发生错误时，该错误将被忽略。
  • webhooks.matchConditions ([]MatchCondition)

  补丁策略：根据 name 键的取值合并

  Map：name 键的唯一值将在合并期间保留

  matchConditions 是将请求发送到此 webhook 之前必须满足的条件列表。 匹配条件过滤已经被 rules、namespaceSelector、objectSelector 匹配的请求。 matchConditions 取值为空列表时匹配所有请求。最多允许 64 个匹配条件。

  精确匹配逻辑是（按顺序）:

  1. 如果任一 matchCondition 的计算结果为 FALSE，则跳过该 Webhook。
  2. 如果所有 matchConditions 的计算结果为 TRUE，则调用该 Webhook。
  3. 如果任一 matchCondition 的计算结果为错误（但都不是 FALSE）：
     • 如果 failurePolicy=Fail，拒绝该请求；
     • 如果 failurePolicy=Ignore，忽略错误并跳过该 Webhook。

  MatchCondition 表示将请求发送到 Webhook 之前必须满足的条件。

  • webhooks.matchConditions.expression (string)，必需

  expression 表示将由 CEL 求值的表达式。求值结果必须是 bool 值。CEL 表达式可以访问 以 CEL 变量的形式给出的 AdmissionRequest 和 Authorizer 的内容：

  • 'object' - 来自传入请求的对象。对于 DELETE 请求，该值为 null。

  • 'oldObject' - 现有对象。对于 CREATE 请求，该值为 null。

  • 'request' - 准入请求的属性(/pkg/apis/admission/types.go#AdmissionRequest)。

  • 'authorizer' - CEL 授权者。可用于对请求的主体（用户或服务帐户）执行授权检查。

    参阅：https://pkg.go.dev/k8s.io/apiserver/pkg/cel/library#Authz

  • 'authorizer.requestResource' - CEL ResourceCheck 从"授权方"构建并配置请求资源。

  CEL 文档：https://kubernetes.io/zh-cn/docs/reference/using-api/cel/

  此字段为必需字段。

  • webhooks.matchConditions.name (string)，必需

    name 是此匹配条件的标识符，用于 matchConditions 的策略性合并， 以及提供用于日志目的的标识符。一个好的 name 应该是对相关表达式的描述。 name 必须是由字母数字字符 -、_ 或 . 组成的限定名称， 并且必须以字母、数字字符开头和结尾（例如 MyName、my.name 或 123-abc， 用于验证 name 的正则表达式是 ([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9]）。 带有可选的 DNS 子域前缀和 /（例如 example.com/MyName）

    此字段为必需字段。

  • webhooks.matchPolicy (string)

    matchPolicy 定义了如何使用 rules 列表来匹配传入的请求。允许的值为 "Exact" 或 "Equivalent"。

    • Exact：仅当请求与指定规则完全匹配时才匹配请求。 例如，如果可以通过 apps/v1、apps/v1beta1 和 extensions/v1beta1 修改 Deployment 资源， 但 “rules” 仅包含 apiGroups:["apps"]、apiVersions:["v1"]、resources:["deployments "]， 对 apps/v1beta1 或 extensions/v1beta1 的请求不会被发送到 Webhook。

    • Equivalent：如果针对的资源包含在 rules 中，即使是通过另一个 API 组或版本，也视作匹配请求。 例如，如果可以通过 apps/v1、apps/v1beta1 和 extensions/v1beta1 修改 deployments 资源， 并且 “rules” 仅包含 apiGroups:["apps"]、apiVersions:["v1"]、resources:["deployments "]， 对 apps/v1beta1 或 extensions/v1beta1 的请求将被转换为 apps/v1 并发送到 Webhook。

    默认为 "Equivalent"。

    可能的枚举值：

    • "Equivalent" 表示如果请求通过另一个 API 组或版本修改了规则中列出的资源， 则应将请求发送到 Webhook。
    • "Exact" 表示仅当请求完全匹配给定规则时，才应将请求发送到 Webhook。

  • webhooks.namespaceSelector (LabelSelector)

    namespaceSelector 根据对象的命名空间是否与 selector 匹配来决定是否在该对象上运行 Webhook。 如果对象本身是命名空间，则在 object.metadata.labels 上执行匹配。 如果对象是另一个集群范围的资源，则永远不会跳过 Webhook 执行匹配。

    例如，在命名空间与 “0” 或 “1” 的 “runlevel” 不关联的任何对象上运行 Webhook； 你可以按如下方式设置 selector：

    "namespaceSelector": {
    "matchExpressions": [
      {
        "key": "runlevel",
        "operator": "NotIn",
        "values": [
          "0",
          "1"
        ]
      }
    ]
    }
    

    相反，如果你只想在命名空间与 “prod” 或 “staging” 的 “environment” 相关联的对象上运行 Webhook； 你可以按如下方式设置 selector:

    "namespaceSelector": {
    "matchExpressions": [
      {
        "key": "environment",
        "operator": "In",
        "values": [
          "prod",
          "staging"
        ]
      }
    ]
    }
    

    有关标签选择算符的更多示例，请参阅 https://kubernetes.io/zh-cn/docs/concepts/overview/working-with-objects/labels。

    默认为空的 LabelSelector，匹配所有对象。

  • webhooks.objectSelector (LabelSelector)

    objectSelector 根据对象是否具有匹配的标签来决定是否运行 Webhook。 objectSelector 针对将被发送到 Webhook 的 oldObject 和 newObject 进行评估，如果任一对象与选择器匹配，则视为匹配。 空对象（create 时为 oldObject，delete 时为 newObject）或不能有标签的对象 （如 DeploymentRollback 或 PodProxyOptions 对象） 认为是不匹配的。 仅当 Webhook 支持时才能使用对象选择器，因为最终用户可以通过设置标签来跳过准入 webhook。 默认为空的 LabelSelector，匹配所有内容。

  • webhooks.rules ([]RuleWithOperations)

    原子性：将在合并期间被替换

    rules 描述了 Webhook 关心的资源/子资源上有哪些操作。Webhook 关心操作是否匹配任何rules。 但是，为了防止 ValidatingAdmissionWebhooks 和 MutatingAdmissionWebhooks 将集群置于只能完全禁用插件才能恢复的状态， ValidatingAdmissionWebhooks 和 MutatingAdmissionWebhooks 永远不会在处理 ValidatingWebhookConfiguration 和 MutatingWebhookConfiguration 对象的准入请求被调用。

    RuleWithOperations 是操作和资源的元组。建议确保所有元组组合都是有效的。

    • webhooks.rules.apiGroups ([]string)

      原子性：合并期间会被替换

      apiGroups 是资源所属的 API 组列表。'' 是所有组。 如果存在 ''，则列表的长度必须为 1。必需。

    • webhooks.rules.apiVersions ([]string)

      原子性：合并期间会被替换

      apiVersions 是资源所属的 API 版本列表。'' 是所有版本。 如果存在 ''，则列表的长度必须为 1。必需。

    • webhooks.rules.operations ([]string)

      原子性: 合并期间会被替换

      operations 是准入 Webhook 所关心的操作 —— CREATE、UPDATE、DELETE、CONNECT 或用来指代所有已知操作以及将来可能添加的准入操作的 *。 如果存在 '*'，则列表的长度必须为 1。必需。

    • webhooks.rules.resources ([]string)

      原子性: 合并期间会被替换

      resources 是此规则适用的资源列表。

      • 'pods' 表示 pods，'pods/log' 表示 pods 的日志子资源。'*' 表示所有资源，但不是子资源。
      • 'pods/*' 表示 pods 的所有子资源,
      • '*/scale' 表示所有 scale 子资源,
      • '/' 表示所有资源及其子资源。

      如果存在通配符，则验证规则将确保资源不会相互重叠。

      根据所指定的对象，可能不允许使用子资源。必需。

    • webhooks.rules.scope (string)

      scope 指定此规则的范围。有效值为 "Cluster", "Namespaced" 和 ""。 "Cluster" 表示只有集群范围的资源才会匹配此规则。 Namespace API 对象是集群范围的。 "Namespaced" 意味着只有命名空间作用域的资源会匹配此规则。 "" 表示没有范围限制。 子资源与其父资源的作用域相同。默认为 "*"。

      可能的枚举值：

      • "*" 表示包含所有作用域。
      • "Cluster" 表示作用域仅限于集群作用域的对象。Namespace 对象属于集群作用域。
      • "Namespaced" 表示作用域仅限于命名空间作用域的对象。

  • webhooks.timeoutSeconds (int32)

    timeoutSeconds 指定此 Webhook 的超时时间。超时后，Webhook 的调用将被忽略或 API 调用将根据失败策略失败。 超时值必须在 1 到 30 秒之间。默认为 10 秒。

ValidatingWebhookConfigurationList

ValidatingWebhookConfigurationList 是 ValidatingWebhookConfiguration 的列表。

• items ([]ValidatingWebhookConfiguration)，必需

  ValidatingWebhookConfiguration 列表。

apiVersion 定义对象表示的版本化模式。服务器应将已识别的模式转换为最新的内部值， 并可能拒绝未识别的值。更多信息： https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources

• kind（string）

  kind 是一个字符串值，表示此对象表示的 REST 资源。服务器可以从客户端提交请求的端点推断出资源类别。 无法更新。采用驼峰式命名。更多信息： https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds

• metadata (ListMeta)

  标准的列表元数据。更多信息： https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata

操作

get 读取指定的 ValidatingWebhookConfiguration

HTTP 请求

GET /apis/admissionregistration.k8s.io/v1/validatingwebhookconfigurations/{name}

参数

• name (路径参数): string，必需

  ValidatingWebhookConfiguration 的名称。

• pretty (查询参数): string

  pretty

响应

200 (ValidatingWebhookConfiguration): OK

401: Unauthorized

list 列出或观察 ValidatingWebhookConfiguration 类型的对象

HTTP 请求

GET /apis/admissionregistration.k8s.io/v1/validatingwebhookconfigurations

参数

• allowWatchBookmarks (查询参数): boolean

  allowWatchBookmarks

• continue (查询参数): string

  continue

• fieldSelector (查询参数): string

  fieldSelector

• fieldSelector (查询参数): string

  fieldSelector

• limit (查询参数): integer

  limit

• pretty (查询参数): string

  pretty

• resourceVersion (查询参数): string

  resourceVersion

• resourceVersionMatch (查询参数): string

  resourceVersionMatch

• sendInitialEvents (查询参数): boolean

  sendInitialEvents

• timeoutSeconds (查询参数): integer

  timeoutSeconds

• watch (查询参数): boolean

  watch

响应

200 (ValidatingWebhookConfigurationList): OK

401: Unauthorized

create 创建一个 ValidatingWebhookConfiguration

HTTP 请求

POST /apis/admissionregistration.k8s.io/v1/validatingwebhookconfigurations

参数

• body: ValidatingWebhookConfiguration，必需

• dryRun (查询参数): string

  dryRun

• fieldManager (查询参数): string

  fieldManager

• fieldValidation (查询参数): string

  fieldValidation

• pretty (查询参数): string

  pretty

响应

200 (ValidatingWebhookConfiguration): OK

201 (ValidatingWebhookConfiguration): Created

202 (ValidatingWebhookConfiguration): Accepted

401: Unauthorized

update 替换指定的 ValidatingWebhookConfiguration

HTTP 请求

PUT /apis/admissionregistration.k8s.io/v1/validatingwebhookconfigurations/{name}

参数

• name (路径参数): string，必需

  ValidatingWebhookConfiguration 的名称。

• body: ValidatingWebhookConfiguration，必需

• dryRun (查询参数): string

  dryRun

• fieldManager (查询参数): string

  fieldManager

• fieldValidation (查询参数): string

  fieldValidation

• pretty (查询参数): string

  pretty

响应

200 (ValidatingWebhookConfiguration): OK

201 (ValidatingWebhookConfiguration): Created

401: Unauthorized

patch 部分更新指定的 ValidatingWebhookConfiguration

HTTP 请求

PATCH /apis/admissionregistration.k8s.io/v1/validatingwebhookconfigurations/{name}

参数

• name (路径参数): string，必需

  ValidatingWebhookConfiguration 的名称。

• body: Patch，必需

• dryRun (查询参数): string

  dryRun

• fieldManager (查询参数): string

  fieldManager

• fieldValidation (查询参数): string

  fieldValidation

• force (查询参数): boolean

  force

• pretty (查询参数): string

  pretty

响应

200 (ValidatingWebhookConfiguration): OK

201 (ValidatingWebhookConfiguration): Created

401: Unauthorized

delete 删除 ValidatingWebhookConfiguration

HTTP 请求

DELETE /apis/admissionregistration.k8s.io/v1/validatingwebhookconfigurations/{name}

参数

• name (路径参数): string，必需

  ValidatingWebhookConfiguration 的名称。

• body: DeleteOptions

• dryRun (查询参数): string

  dryRun

• gracePeriodSeconds (查询参数): integer

  gracePeriodSeconds

• ignoreStoreReadErrorWithClusterBreakingPotential (查询参数): boolean

  ignoreStoreReadErrorWithClusterBreakingPotential

• pretty (查询参数): string

  pretty

• propagationPolicy (查询参数): string

  propagationPolicy

响应

200 (Status): OK

202 (Status): Accepted

401: Unauthorized

deletecollection 删除 ValidatingWebhookConfiguration 的集合

HTTP 请求

DELETE /apis/admissionregistration.k8s.io/v1/validatingwebhookconfigurations

参数

• body: DeleteOptions

• continue (查询参数): string

  continue

• dryRun (查询参数): string

  dryRun

• fieldSelector (查询参数): string

  fieldSelector

• gracePeriodSeconds (查询参数): integer

  gracePeriodSeconds

• ignoreStoreReadErrorWithClusterBreakingPotential (查询参数): boolean

  ignoreStoreReadErrorWithClusterBreakingPotential

• labelSelector (查询参数): string

  labelSelector

• limit (查询参数): integer

  limit

• pretty (查询参数): string

  pretty

• propagationPolicy (查询参数): string

  propagationPolicy

• resourceVersion (查询参数): string

  resourceVersion

• resourceVersionMatch (查询参数): string

  resourceVersionMatch

• sendInitialEvents (查询参数): boolean

  sendInitialEvents

• timeoutSeconds (查询参数): integer

  timeoutSeconds

响应

200 (Status): OK

401: Unauthorized