1 - CustomResourceDefinition

CustomResourceDefinition 表示应在 API 服务器上公开的资源。

apiVersion: apiextensions.k8s.io/v1

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

CustomResourceDefinition

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


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 表示自定义资源是集群作用域还是命名空间作用域。允许的值为 ClusterNamespaced

  • 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.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 的位置。urlservice 必须指定一个且只能指定一个。

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

          请注意,使用 localhost127.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 级别。 使用此字段需要启用 CustomResourceValidationExpressions 特性门控。

    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')"}

      apiVersionkindmetadata.namemetadata.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 中所有键的数组位置,但当 XY 的键集相交时,会被 Y 中的值覆盖。 添加 Y 中具有不相交键的元素,保持其局顺序。
    • 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.reason (string)

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

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.reason (string)

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

  • storedVersions ([]string)

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

CustomResourceDefinitionList

CustomResourceDefinitionList 是 CustomResourceDefinition 对象的列表。


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

参数

响应

200 (CustomResourceDefinitionList): OK

401: Unauthorized

create 创建一个 CustomResourceDefinition

HTTP 请求

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

参数

响应

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 的名称。

  • bodyCustomResourceDefinition,必需

  • 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 的名称。

  • bodyCustomResourceDefinition,必需

  • 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 的名称。

  • bodyPatch,必需

  • 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 的名称。

  • bodyPatch,必需

  • 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 的名称。

  • bodyDeleteOptions

  • dryRun 查询参数):string

    dryRun

  • gracePeriodSeconds 查询参数):integer

    gracePeriodSeconds

  • pretty 查询参数):string

    pretty

  • propagationPolicy 查询参数):string

    propagationPolicy

响应

200 (Status): OK

202 (Status): Accepted

401: Unauthorized

deletecollection 删除 CustomResourceDefinition 的集合

HTTP 请求

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

参数

响应

200 (Status): OK

401: Unauthorized

2 - MutatingWebhookConfiguration

MutatingWebhookConfiguration 描述准入 Webhook 的配置,该 Webhook 可在更改对象的情况下接受或拒绝对象请求

apiVersion: admissionregistration.k8s.io/v1

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

MutatingWebhookConfiguration

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


  • apiVersion:admissionregistration.k8s.io/v1

  • kind:MutatingWebhookConfiguration

  • webhooks ([]MutatingWebhook)

    补丁策略:根据 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 的服务的引用。必须指定 serviceurl 之一。

        如果 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 的位置。必须指定 urlservice 中的一个。

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

        请注意,使用 localhost127.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 属性的请求将被自动拒绝。

    • webhooks.failurePolicy (string)

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

    • 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。

      这是一个 Beta 功能特性,由 AdmissionWebhookMatchConditions 特性门控管理。

      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 必须是由字母数字字符 -_. 组成的限定名称, 并且必须以字母、数字字符开头和结尾(例如 MyNamemy.name123-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”。

    • 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” 。

    • 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)

        Atomic: 将在合并期间被替换

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

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

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

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

      • webhooks.rules.scope (string)

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

    • webhooks.timeoutSeconds (int32)

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

MutatingWebhookConfigurationList

MutatingWebhookConfigurationList 是 MutatingWebhookConfiguration 的列表。


  • apiVersion: admissionregistration.k8s.io/v1

  • kind: MutatingWebhookConfigurationList

操作


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

参数

  • continue查询参数):string

    continue

  • limit查询参数):integer

    limit

  • pretty查询参数):string

    pretty

  • watch查询参数):boolean

    watch

响应

200 (MutatingWebhookConfigurationList): OK

401: Unauthorized

create 创建一个 MutatingWebhookConfiguration

HTTP 请求

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

参数

  • dryRun查询参数):string

    dryRun

  • 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 的名称。

  • dryRun查询参数):string

    dryRun

  • 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 的名称。

  • dryRun查询参数):string

    dryRun

  • 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

  • pretty查询参数):string

    pretty

响应

200 (Status): OK

202 (Status): Accepted

401: Unauthorized

deletecollection 删除 MutatingWebhookConfiguration 的集合

HTTP 请求

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

参数

  • continue查询参数):string

    continue

  • dryRun查询参数):string

    dryRun

  • limit查询参数):integer

    limit

  • pretty查询参数):string

    pretty

响应

200 (Status): OK

401: Unauthorized

3 - ValidatingWebhookConfiguration

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

apiVersion: admissionregistration.k8s.io/v1

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

ValidatingWebhookConfiguration

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


  • apiVersion: admissionregistration.k8s.io/v1

  • kind: ValidatingWebhookConfiguration

  • webhooks ([]ValidatingWebhook)

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

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

    ValidatingWebhook 描述了一个准入 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 服务的引用。必须指定 serviceurl

        如果 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 的位置。必须指定 urlservice 中的一个。

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

        请注意,使用 localhost127.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 属性的请求将被自动拒绝。

    • webhooks.failurePolicy (string)

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

    • 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。

    这是一个 Beta 功能特性,由 AdmissionWebhookMatchConditions 特性门控管理。

    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 必须是由字母数字字符 -_. 组成的限定名称, 并且必须以字母、数字字符开头和结尾(例如 MyNamemy.name123-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”。

    • 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" 意味着只有命名空间作用域的资源会匹配此规则。 "" 表示没有范围限制。 子资源与其父资源的作用域相同。默认为 "*"。

    • webhooks.timeoutSeconds (int32)

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

ValidatingWebhookConfigurationList

ValidatingWebhookConfigurationList 是 ValidatingWebhookConfiguration 的列表。


  • apiVersion: admissionregistration.k8s.io/v1

  • kind: ValidatingWebhookConfigurationList

操作


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

参数

  • continue (查询参数): string

    continue

  • limit (查询参数): integer

    limit

  • pretty (查询参数): string

    pretty

  • watch (查询参数): boolean

    watch

响应

200 (ValidatingWebhookConfigurationList): OK

401: Unauthorized

create 创建一个 ValidatingWebhookConfiguration

HTTP 请求

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

参数

  • dryRun (查询参数): string

    dryRun

  • 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 的名称。

  • dryRun (查询参数): string

    dryRun

  • 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 的名称。

  • dryRun (查询参数): string

    dryRun

  • 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

  • pretty (查询参数): string

    pretty

响应

200 (Status): OK

202 (Status): Accepted

401: Unauthorized

deletecollection 删除 ValidatingWebhookConfiguration 的集合

HTTP 请求

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

参数

  • continue (查询参数): string

    continue

  • dryRun (查询参数): string

    dryRun

  • limit (查询参数): integer

    limit

  • pretty (查询参数): string

    pretty

响应

200 (Status): OK

401: Unauthorized