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 (字串)，必要

  group 是已定義自訂資源的 API 群組。自訂資源在 /apis/\<group>/... 下提供服務。必須符合 CustomResourceDefinition 的名稱 (格式為 \<names.plural>.\<group>)。

• names (CustomResourceDefinitionNames)，必要

  names 指定自訂資源的資源和 Kind 名稱。

  CustomResourceDefinitionNames 指出為此 CustomResourceDefinition 提供服務的名稱

  • names.kind (字串)，必要

    kind 是資源的序列化 Kind。通常為 CamelCase 且為單數。自訂資源執行個體將使用此值作為 API 呼叫中的 kind 屬性。

  • names.plural (字串)，必要

    plural 是要提供服務的資源複數名稱。自訂資源在 /apis/\<group>/\<version>/.../\<plural> 下提供服務。必須符合 CustomResourceDefinition 的名稱 (格式為 \<names.plural>.\<group>)。必須全部小寫。

  • names.categories ([]字串)

    Atomic：將在合併期間取代

    categories 是此自訂資源所屬的分組資源清單 (例如 'all')。這會發佈在 API 探索文件中，並由用戶端用來支援類似 kubectl get all 的調用。

  • names.listKind (字串)

    listKind 是此資源清單的序列化 Kind。預設為「kindList」。

  • names.shortNames ([]字串)

    Atomic：將在合併期間取代

    shortNames 是資源的簡短名稱，公開在 API 探索文件中，並由用戶端用來支援類似 kubectl get \<shortname> 的調用。必須全部小寫。

  • names.singular (字串)

    singular 是資源的單數名稱。必須全部小寫。預設為小寫的 kind。

• scope (字串)，必要

  scope 指出已定義的自訂資源是叢集範圍還是命名空間範圍。允許的值為 Cluster 和 Namespaced。

• versions ([]CustomResourceDefinitionVersion)，必要

  Atomic：將在合併期間取代

  versions 是已定義自訂資源的所有 API 版本清單。版本名稱用於計算 API 探索中列出的服務版本順序。如果版本字串為「類似 kube」，則其排序將高於非「類似 kube」的版本字串，後者按字典順序排序。「類似 kube」版本以「v」開頭，然後是數字 (主要版本)，然後選擇性地為字串「alpha」或「beta」和另一個數字 (次要版本)。這些排序方式首先是 GA > beta > alpha (其中 GA 是沒有後綴 (例如 beta 或 alpha) 的版本)，然後比較主要版本，然後是次要版本。已排序的版本範例清單：v10、v2、v1、v11beta2、v10beta3、v3beta1、v12alpha1、v11alpha2、foo1、foo10。

  CustomResourceDefinitionVersion 描述 CRD 的版本。

  • versions.name (字串)，必要

    name 是版本名稱，例如「v1」、「v2beta1」等。如果 served 為 true，則自訂資源在此版本下於 /apis/\<group>/\<version>/... 提供服務。

  • versions.served (布林值)，必要

    served 是一個旗標，用於啟用/停用透過 REST API 提供服務的此版本

  • versions.storage (布林值)，必要

    storage 指出在將自訂資源持續保存到儲存空間時，應使用此版本。必須正好有一個版本 storage=true。

  • versions.additionalPrinterColumns ([]CustomResourceColumnDefinition)

    Atomic：將在合併期間取代

    additionalPrinterColumns 指定表格輸出中傳回的其他欄位。如需詳細資訊，請參閱 https://kubernetes.dev.org.tw/docs/reference/using-api/api-concepts/#receiving-resources-as-tables。如果未指定任何欄位，則會使用單一欄位顯示自訂資源的存留時間。

    CustomResourceColumnDefinition 指定伺服器端列印的欄位。

    • versions.additionalPrinterColumns.jsonPath (字串)，必要

      jsonPath 是簡單的 JSON 路徑 (即具有陣列表示法)，針對每個自訂資源進行評估，以產生此欄位的值。

    • versions.additionalPrinterColumns.name (字串)，必要

      name 是欄位的人類可讀名稱。

    • versions.additionalPrinterColumns.type (字串)，必要

      type 是此欄位的 OpenAPI 類型定義。如需詳細資訊，請參閱 https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#data-types。

    • versions.additionalPrinterColumns.description (字串)

      description 是此欄位的人類可讀描述。

    • versions.additionalPrinterColumns.format (字串)

      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 (布林值)

    deprecated 指出此版本的自訂資源 API 已棄用。設定為 true 時，對此版本的 API 請求會在伺服器回應中收到警告標頭。預設為 false。

  • versions.deprecationWarning (字串)

    deprecationWarning 覆寫傳回給 API 用戶端的預設警告。僅當 deprecated 為 true 時才能設定。預設警告會指出此版本已棄用，並建議使用相等或更高穩定性的最新服務版本 (如果有的話)。

  • versions.schema (CustomResourceValidation)

    schema 描述用於此自訂資源版本的驗證、修剪和預設值設定的 schema。

    CustomResourceValidation 是 CustomResource 的驗證方法列表。

    • versions.schema.openAPIV3Schema (JSONSchemaProps)

      openAPIV3Schema 是用於驗證和修剪的 OpenAPI v3 schema。

  • versions.selectableFields ([]SelectableField)

    Atomic：將在合併期間取代

    selectableFields 指定可用作欄位選擇器的欄位路徑。最多允許 8 個可選欄位。請參閱 https://kubernetes.dev.org.tw/docs/concepts/overview/working-with-objects/field-selectors

    SelectableField 指定可用於欄位選擇器的欄位的 JSON 路徑。

    • versions.selectableFields.jsonPath (字串), 必填

      jsonPath 是一個簡單的 JSON 路徑，會針對每個自訂資源進行評估，以產生欄位選擇器值。僅允許不帶陣列表示法的 JSON 路徑。必須指向字串、布林值或整數類型的欄位。允許使用具有列舉值的類型和具有格式的字串。如果 jsonPath 參照資源中不存在的欄位，則 jsonPath 會評估為空字串。不得指向 metadata 欄位。必填。

  • versions.subresources (CustomResourceSubresources)

    subresources 指定此版本定義的自訂資源有哪些子資源。

    CustomResourceSubresources 定義了 CustomResource 的狀態和 scale 子資源。

    • versions.subresources.scale (CustomResourceSubresourceScale)

      scale 表示自訂資源應提供 /scale 子資源，該子資源會傳回 autoscaling/v1 Scale 物件。

      CustomResourceSubresourceScale 定義了如何為 CustomResource 提供 scale 子資源。

      • versions.subresources.scale.specReplicasPath (字串), 必填

        specReplicasPath 定義了自訂資源內部的 JSON 路徑，該路徑對應到 Scale 的 spec.replicas。僅允許不帶陣列表示法的 JSON 路徑。必須是 .spec 下的 JSON 路徑。如果自訂資源中給定路徑下沒有值，則 /scale 子資源在 GET 時會傳回錯誤。

      • versions.subresources.scale.statusReplicasPath (字串), 必填

        statusReplicasPath 定義了自訂資源內部的 JSON 路徑，該路徑對應到 Scale 的 status.replicas。僅允許不帶陣列表示法的 JSON 路徑。必須是 .status 下的 JSON 路徑。如果自訂資源中給定路徑下沒有值，則 /scale 子資源中的 status.replicas 值會預設為 0。

      • versions.subresources.scale.labelSelectorPath (字串)

        labelSelectorPath 定義了自訂資源內部的 JSON 路徑，該路徑對應到 Scale 的 status.selector。僅允許不帶陣列表示法的 JSON 路徑。必須是 .status 或 .spec 下的 JSON 路徑。必須設定才能與 HorizontalPodAutoscaler 搭配使用。此 JSON 路徑指向的欄位必須是字串欄位 (而非複雜的選擇器結構)，其中包含字串形式的序列化標籤選擇器。更多資訊：https://kubernetes.dev.org.tw/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 定義了如何為 CustomResource 提供 status 子資源。Status 由 CustomResource 內部的 .status JSON 路徑表示。設定後，* 為自訂資源公開 /status 子資源 * 對 /status 子資源的 PUT 請求會取得自訂資源物件，並忽略對 status 段落以外任何內容的變更 * 對自訂資源的 PUT/POST/PATCH 請求會忽略對 status 段落的變更

• conversion (CustomResourceConversion)

  conversion 定義 CRD 的轉換設定。

  CustomResourceConversion 描述如何轉換 CR 的不同版本。

  • conversion.strategy (字串), 必填

    strategy 指定自訂資源如何在版本之間轉換。允許的值為：- "None"：轉換器僅變更 apiVersion，不會觸及自訂資源中的任何其他欄位。- "Webhook"：API 伺服器將呼叫外部 webhook 進行轉換。此選項需要額外資訊。這需要 spec.preserveUnknownFields 為 false，且 spec.conversion.webhook 已設定。

  • conversion.webhook (WebhookConversion)

    webhook 描述如何呼叫轉換 webhook。當 strategy 設定為 "Webhook" 時為必填。

    WebhookConversion 描述如何呼叫轉換 webhook

    • conversion.webhook.conversionReviewVersions ([]字串), 必填

      Atomic：將在合併期間取代

      conversionReviewVersions 是 Webhook 預期的偏好 ConversionReview 版本的排序列表。API 伺服器將使用列表中它支援的第一個版本。如果 API 伺服器不支援此列表中指定的任何版本，則自訂資源的轉換將會失敗。如果持續的 Webhook 設定指定了允許的版本，且未包含 API 伺服器已知的任何版本，則對 webhook 的呼叫將會失敗。

    • conversion.webhook.clientConfig (WebhookClientConfig)

      clientConfig 是當 strategy 為 Webhook 時，如何呼叫 webhook 的指示。

      WebhookClientConfig 包含與 webhook 建立 TLS 連線的資訊。

      • conversion.webhook.clientConfig.caBundle ([]位元組)

        caBundle 是一個 PEM 編碼的 CA 組合包，將用於驗證 webhook 的伺服器憑證。如果未指定，則會使用 apiserver 上的系統信任根。

      • conversion.webhook.clientConfig.service (ServiceReference)

        service 是對此 webhook 服務的參照。必須指定 service 或 url 其中一個。

        如果 webhook 在叢集內執行，則應使用 service。

        ServiceReference 保有對 Service.legacy.k8s.io 的參照

        • conversion.webhook.clientConfig.service.name (字串), 必填

          name 是服務的名稱。必填

        • conversion.webhook.clientConfig.service.namespace (字串), 必填

          namespace 是服務的命名空間。必填

        • conversion.webhook.clientConfig.service.path (字串)

          path 是 webhook 將被連線的可選 URL 路徑。

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

          port 是 webhook 將被連線的可選服務埠。port 應為有效的埠號 (1-65535，包含)。為了向後相容性，預設為 443。

      • conversion.webhook.clientConfig.url (字串)

        url 以標準 URL 格式 (scheme://host:port/path) 提供 webhook 的位置。必須指定 url 或 service 其中一個。

        host 不應參照在叢集中執行的服務；請改用 service 欄位。host 可能會透過外部 DNS 在某些 apiserver 中解析 (例如，kube-apiserver 無法解析叢集內 DNS，因為這會違反分層)。host 也可能是 IP 位址。

        請注意，除非您非常小心地在所有執行 apiserver 的主機上執行此 webhook (這些主機可能需要呼叫此 webhook)，否則使用 localhost 或 127.0.0.1 作為 host 是有風險的。此類安裝可能不具可攜性，亦即不容易在新叢集中啟動。

        scheme 必須為 "https"；URL 必須以 "https://" 開頭。

        path 是可選的，如果存在，則可以是 URL 中允許的任何字串。您可以使用 path 將任意字串傳遞給 webhook，例如叢集識別碼。

        不允許嘗試使用使用者或基本驗證，例如 "user:password@"。也不允許片段 ("#...") 和查詢參數 ("?...")。

• preserveUnknownFields (布林值)

  preserveUnknownFields 表示在持續儲存時，應保留 OpenAPI schema 中未指定的物件欄位。apiVersion、kind、metadata 和 metadata 內部的已知欄位始終會被保留。此欄位已被取代，建議改為在 spec.versions[*].schema.openAPIV3Schema 中將 x-preserve-unknown-fields 設定為 true。有關詳細資訊，請參閱 https://kubernetes.dev.org.tw/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#field-pruning。

JSONSchemaProps

JSONSchemaProps 是遵循 Specification Draft 4 (https://json-schema.dev.org.tw/) 的 JSON-Schema。

• $ref (字串)

• $schema (字串)

• additionalItems (JSONSchemaPropsOrBool)

  JSONSchemaPropsOrBool 代表 JSONSchemaProps 或布林值。布林值屬性預設為 true。

• additionalProperties (JSONSchemaPropsOrBool)

  JSONSchemaPropsOrBool 代表 JSONSchemaProps 或布林值。布林值屬性預設為 true。

• allOf ([]JSONSchemaProps)

  Atomic：將在合併期間取代

• anyOf ([]JSONSchemaProps)

  Atomic：將在合併期間取代

• default (JSON)

  default 是未定義物件欄位的預設值。預設值設定是 CustomResourceDefaulting 功能閘道下的 Beta 功能。預設值設定需要 spec.preserveUnknownFields 為 false。

  JSON 代表任何有效的 JSON 值。支援的類型包括：布林值、int64、float64、字串、[]interface{}、map[string]interface{} 和 nil。

• definitions (map[字串]JSONSchemaProps)

• dependencies (map[字串]JSONSchemaPropsOrStringArray)

  JSONSchemaPropsOrStringArray 代表 JSONSchemaProps 或字串陣列。

• description (字串)

• enum ([]JSON)

  Atomic：將在合併期間取代

  JSON 代表任何有效的 JSON 值。支援的類型包括：布林值、int64、float64、字串、[]interface{}、map[string]interface{} 和 nil。

• example (JSON)

  JSON 代表任何有效的 JSON 值。支援的類型包括：布林值、int64、float64、字串、[]interface{}、map[string]interface{} 和 nil。

• exclusiveMaximum (布林值)

• exclusiveMinimum (布林值)

• externalDocs (ExternalDocumentation)

  ExternalDocumentation 允許參照外部資源以取得擴充文件。

  • externalDocs.description (字串)

  • externalDocs.url (字串)

• format (字串)

  format 是 OpenAPI v3 格式字串。未知的格式會被忽略。以下格式會經過驗證

  • bsonobjectid：bson 物件 ID，即 24 個字元的十六進位字串 - uri：由 Golang net/url.ParseRequestURI 剖析的 URI - email：由 Golang net/mail.ParseAddress 剖析的電子郵件地址 - hostname：網際網路主機名稱的有效表示法，如 RFC 1034 第 3.1 節 [RFC1034] 所定義。- ipv4：由 Golang net.ParseIP 剖析的 IPv4 IP - ipv6：由 Golang net.ParseIP 剖析的 IPv6 IP - cidr：由 Golang net.ParseCIDR 剖析的 CIDR - mac：由 Golang net.ParseMAC 剖析的 MAC 位址 - uuid：允許大寫的 UUID，由 regex (?i)^[0-9a-f]{8}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{12}$ 定義 - uuid3：允許大寫的 UUID3，由 regex (?i)^[0-9a-f]{8}-?[0-9a-f]{4}-?3[0-9a-f]{3}-?[0-9a-f]{4}-?[0-9a-f]{12}$ 定義 - uuid4：允許大寫的 UUID4，由 regex (?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，由 regex (?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：信用卡號碼，由 regex ^(?: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：美國社會安全號碼，遵循 regex ^\d{3}[- ]?\d{2}[- ]?\d{4}$ - hexcolor：十六進位色彩代碼，例如 "#FFFFFF"，遵循 regex ^#?([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$ - rgbcolor：RGB 色彩代碼，例如 "rgb(255,255,2559" - byte：base64 編碼的二進位資料 - password：任何類型的字串 - date：日期字串，例如 "2006-01-02"，如 RFC3339 中的 full-date 所定義 - duration：持續時間字串，例如 "22 ns"，由 Golang time.ParseDuration 剖析或與 Scala 持續時間格式相容 - datetime：日期時間字串，例如 "2014-12-15T19:30:20.000Z"，如 RFC3339 中的 date-time 所定義。

• id (字串)

• 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 (布林值)

• oneOf ([]JSONSchemaProps)

  Atomic：將在合併期間取代

• pattern (字串)

• patternProperties (map[字串]JSONSchemaProps)

• properties (map[字串]JSONSchemaProps)

• required ([]字串)

  Atomic：將在合併期間取代

• title (字串)

• type (字串)

• uniqueItems (布林值)

• x-kubernetes-embedded-resource (布林值)

  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 (布林值)

  x-kubernetes-int-or-string 指定此值可以是整數或字串。如果為 true，則允許空類型，且如果遵循以下模式之一，則允許將 type 作為 anyOf 的子項

  1. anyOf
     • type: integer
     • type: string
  2. allOf
     • anyOf
       • type: integer
       • type: string
     • ... 零個或多個

• x-kubernetes-list-map-keys ([]字串)

  Atomic：將在合併期間取代

  x-kubernetes-list-map-keys 透過指定用作 map 索引的鍵，使用 x-kubernetes-list-type map 註解陣列。

  此標籤僅能用於將 "x-kubernetes-list-type" 擴充功能設定為 "map" 的列表。此外，為此屬性指定的值必須是子結構的純量類型欄位 (不支援巢狀)。

  指定的屬性必須是必填的或具有預設值，以確保所有列表項目都存在這些屬性。

• x-kubernetes-list-type (字串)

  x-kubernetes-list-type 註解陣列以進一步描述其拓撲。此擴充功能僅能用於列表，且可能有 3 個可能的值

  1. atomic：列表被視為單一實體，就像純量一樣。原子列表在更新時將會完全被取代。此擴充功能可用於任何類型的列表 (結構、純量、...)。
  2. set：Set 是不得有多個具有相同值的項目的列表。每個值都必須是純量、具有 x-kubernetes-map-type atomic 的物件，或具有 x-kubernetes-list-type atomic 的陣列。
  3. map：這些列表就像 map 一樣，因為它們的元素具有用於識別它們的非索引鍵。合併時會保留順序。map 標籤僅能用於元素類型為物件的列表。陣列預設為 atomic。

• x-kubernetes-map-type (字串)

  x-kubernetes-map-type 註解物件以進一步描述其拓撲。此擴充功能僅能用於類型為物件時，且可能有 2 個可能的值

  1. granular：這些 map 是實際的 map (鍵值對)，且每個欄位都彼此獨立 (它們可以由不同的參與者操作)。這是所有 map 的預設行為。
  2. atomic：列表被視為單一實體，就像純量一樣。原子 map 在更新時將會完全被取代。

• x-kubernetes-preserve-unknown-fields (布林值)

  x-kubernetes-preserve-unknown-fields 停止 API 伺服器解碼步驟修剪驗證 schema 中未指定的欄位。這會遞迴地影響欄位，但如果在 schema 中指定了巢狀屬性或 additionalProperties，則會切換回正常的修剪行為。它可以是 true 或未定義。禁止為 false。

• x-kubernetes-validations ([]ValidationRule)

  Patch 策略：在鍵 rule 上合併

  Map：在合併期間，鍵 rule 上的唯一值將被保留

  x-kubernetes-validations 描述以 CEL 運算式語言撰寫的驗證規則列表。

  ValidationRule 描述以 CEL 運算式語言撰寫的驗證規則。

  • x-kubernetes-validations.rule (字串), 必填

    rule 代表將由 CEL 評估的運算式。參考：https://github.com/google/cel-spec Rule 的範圍限定於 schema 中 x-kubernetes-validations 擴充功能的位置。CEL 運算式中的 self 變數繫結至範圍值。範例：- 範圍限定於具有 status 子資源的資源根目錄的 Rule：{"rule": "self.status.actual <= self.spec.maxDesired"}

    如果 Rule 的範圍限定於具有屬性的物件，則物件的可存取屬性可透過 self.field 進行欄位選擇，且欄位存在性可透過 has(self.field) 檢查。在 CEL 運算式中，空值欄位會被視為不存在的欄位。如果 Rule 的範圍限定於具有 additionalProperties 的物件 (即 map)，則 map 的值可透過 self[mapKey] 存取，map 包含性可透過 mapKey in self 檢查，且 map 的所有條目都可透過 CEL 巨集和函數 (例如 self.all(...)) 存取。如果 Rule 的範圍限定於陣列，則陣列的元素可透過 self[i] 以及巨集和函數存取。如果 Rule 的範圍限定於純量，則 self 會繫結至純量值。範例：- 範圍限定於物件 map 的 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 註解的物件存取。無法存取其他 metadata 屬性。

    透過 x-kubernetes-preserve-unknown-fields 保留在自訂資源中的未知資料在 CEL 運算式中無法存取。這包括：- 透過具有 x-kubernetes-preserve-unknown-fields 的物件 schema 保留的未知欄位值。- 屬性 schema 為「未知類型」的物件屬性。「未知類型」遞迴定義為

    • 沒有類型且 x-kubernetes-preserve-unknown-fields 設定為 true 的 schema
    • 項目 schema 為「未知類型」的陣列
    • additionalProperties schema 為「未知類型」的物件

    僅表單為 [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：{"rule": "self.__namespace__ > 0"}
    • 存取名為 "x-prop" 的屬性的 Rule：{"rule": "self.x__dash__prop > 0"}
    • 存取名為 "redact__d" 的屬性的 Rule：{"rule": "self.redact__underscores__d > 0"}

    對 x-kubernetes-list-type 為 'set' 或 'map' 的陣列進行等式比較會忽略元素順序，即 [1, 2] == [2, 1]。對 x-kubernetes-list-type 為 'set' 或 'map' 的陣列進行串連會使用列表類型的語意

    • '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 (字串)

    fieldPath 代表驗證失敗時傳回的欄位路徑。它必須是相對於此 schema 中 x-kubernetes-validations 擴充功能位置的 JSON 路徑 (即帶有陣列表示法)，並且參照現有欄位。例如，當驗證檢查 map testMap 下的特定屬性 foo 時，fieldPath 可以設定為 .testMap.foo。如果驗證檢查兩個列表必須具有唯一屬性，則 fieldPath 可以設定為任一列表：例如 .testList。它不支援列表數字索引。它支援子運算以參照目前現有的欄位。有關更多資訊，請參閱 Kubernetes 中的 JSONPath 支援。不支援陣列的數字索引。對於包含特殊字元的欄位名稱，請使用 ['特殊名稱'] 來參照欄位名稱。例如，對於列表 testList 中出現的屬性 foo.34$，fieldPath 可以設定為 .testList['foo.34$']

  • x-kubernetes-validations.message (字串)

    message 代表驗證失敗時顯示的訊息。如果 Rule 包含換行符號，則此訊息為必填。訊息不得包含換行符號。如果未設定，則訊息為「failed rule: {Rule}」。例如「must be a URL with the host matching spec.host」

  • x-kubernetes-validations.messageExpression (字串)

    messageExpression 宣告一個 CEL 運算式，該運算式評估為在此規則失敗時傳回的驗證失敗訊息。由於 messageExpression 用作失敗訊息，因此它必須評估為字串。如果規則上同時存在 message 和 messageExpression，則驗證失敗時將使用 messageExpression。如果 messageExpression 導致執行階段錯誤，則會記錄執行階段錯誤，並且產生的驗證失敗訊息將如同 messageExpression 欄位未設定一樣。如果 messageExpression 評估為空字串、僅包含空格的字串或包含換行符號的字串，則驗證失敗訊息也會如同 messageExpression 欄位未設定一樣產生，並且將記錄 messageExpression 產生空字串/僅包含空格的字串/包含換行符號的字串的事實。messageExpression 可以存取與 rule 相同的所有變數；唯一的區別是傳回類型。範例：「x 必須小於 max ("+string(self.max)+")」

  • x-kubernetes-validations.optionalOldSelf (布林值)

    optionalOldSelf 用於即使在首次建立物件時，或舊物件缺少值時，也將轉換規則選擇加入評估。

    啟用後，如果沒有舊值，或物件最初建立時，oldSelf 將會是一個 CEL 可選值，其值將為 None。

    您可以使用 oldSelf.hasValue() 檢查 oldSelf 的存在，並在使用 oldSelf.value() 檢查後將其解包。有關可選類型的更多資訊，請參閱 CEL 文件：https://pkg.go.dev/github.com/google/cel-go/cel#OptionalTypes

    除非在 rule 中使用 oldSelf，否則不得設定。

  • x-kubernetes-validations.reason (字串)

    reason 提供機器可讀的驗證失敗原因，當請求未能通過此驗證規則時，會將其傳回給呼叫者。傳回給呼叫者的 HTTP 狀態碼將與第一個失敗的驗證規則的原因相符。目前支援的原因包括："FieldValueInvalid"、"FieldValueForbidden"、"FieldValueRequired"、"FieldValueDuplicate"。如果未設定，則預設使用 "FieldValueInvalid"。所有未來新增的原因都必須在用戶端讀取此值時被接受，且未知的理由應被視為 FieldValueInvalid。

CustomResourceDefinitionStatus

CustomResourceDefinitionStatus 指出 CustomResourceDefinition 的狀態

• acceptedNames (CustomResourceDefinitionNames)

  acceptedNames 是實際用於提供探索服務的名稱。它們可能與 spec 中的名稱不同。

  CustomResourceDefinitionNames 指出為此 CustomResourceDefinition 提供服務的名稱

  • acceptedNames.kind (字串), 必填

    kind 是資源的序列化 Kind。通常為 CamelCase 且為單數。自訂資源執行個體將使用此值作為 API 呼叫中的 kind 屬性。

  • acceptedNames.plural (字串), 必填

    plural 是要提供服務的資源複數名稱。自訂資源在 /apis/\<group>/\<version>/.../\<plural> 下提供服務。必須符合 CustomResourceDefinition 的名稱 (格式為 \<names.plural>.\<group>)。必須全部小寫。

  • acceptedNames.categories ([]字串)

    Atomic：將在合併期間取代

    categories 是此自訂資源所屬的分組資源清單 (例如 'all')。這會發佈在 API 探索文件中，並由用戶端用來支援類似 kubectl get all 的調用。

  • acceptedNames.listKind (字串)

    listKind 是此資源清單的序列化 Kind。預設為「kindList」。

  • acceptedNames.shortNames ([]字串)

    Atomic：將在合併期間取代

    shortNames 是資源的簡短名稱，公開在 API 探索文件中，並由用戶端用來支援類似 kubectl get \<shortname> 的調用。必須全部小寫。

  • acceptedNames.singular (字串)

    singular 是資源的單數名稱。必須全部小寫。預設為小寫的 kind。

• conditions ([]CustomResourceDefinitionCondition)

  Map：在合併期間，鍵 type 上的唯一值將被保留

  conditions 指出 CustomResourceDefinition 特定方面的狀態

  CustomResourceDefinitionCondition 包含此 pod 目前狀況的詳細資訊。

  • conditions.status (字串), 必填

    status 是狀況的狀態。可以是 True、False、Unknown。

  • conditions.type (字串), 必填

    type 是狀況的類型。類型包括 Established、NamesAccepted 和 Terminating。

  • conditions.lastTransitionTime (時間)

    lastTransitionTime 狀況上次從一種狀態轉換到另一種狀態的時間。

    時間是 time.Time 的包裝器，支援正確地封送處理為 YAML 和 JSON。為 time 套件提供的許多 factory 方法提供了包裝器。

  • conditions.message (字串)

    message 是人類可讀的訊息，指出上次轉換的詳細資訊。

  • conditions.reason (字串)

    reason 是狀況上次轉換的唯一、單字、駝峰式大小寫原因。

• storedVersions ([]字串)

  Atomic：將在合併期間取代

  storedVersions 列出曾經持續儲存的所有 CustomResource 版本。追蹤這些版本允許 etcd 中已儲存版本的遷移路徑。此欄位是可變的，因此遷移控制器可以完成遷移到另一個版本 (確保儲存中沒有舊物件留下)，然後從此列表中移除其餘版本。當版本存在於此列表中時，不得從 spec.versions 中移除版本。

CustomResourceDefinitionList

CustomResourceDefinitionList 是 CustomResourceDefinition 物件的列表。

• items ([]CustomResourceDefinition), 必填

  items 列出個別的 CustomResourceDefinition 物件

• apiVersion (字串)

  apiVersion 定義此物件表示版本的 schema。伺服器應將可辨識的 schema 轉換為最新的內部值，並可能拒絕無法辨識的值。更多資訊：https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources

• kind (字串)

  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 讀取指定的 CustomResourceDefinition

HTTP 請求

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

參數

• name (在路徑中)：字串，必填

  CustomResourceDefinition 的名稱

• pretty (在查詢中)：字串

  pretty

回應

200 (CustomResourceDefinition)：OK

401：未經授權

get 讀取指定 CustomResourceDefinition 的狀態

HTTP 請求

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

參數

• name (在路徑中)：字串，必填

  CustomResourceDefinition 的名稱

• pretty (在查詢中)：字串

  pretty

回應

200 (CustomResourceDefinition)：OK

401：未經授權

list 列出或監看 CustomResourceDefinition 類型的物件

HTTP 請求

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

參數

• allowWatchBookmarks (在查詢中)：布林值

  allowWatchBookmarks

• continue (在查詢中)：字串

  continue

• fieldSelector (在查詢中)：字串

  fieldSelector

• labelSelector (在查詢中)：字串

  labelSelector

• limit (在查詢中)：整數

  limit

• pretty (在查詢中)：字串

  pretty

• resourceVersion (在查詢中)：字串

  resourceVersion

• resourceVersionMatch (在查詢中)：字串

  resourceVersionMatch

• sendInitialEvents (在查詢中)：布林值

  sendInitialEvents

• timeoutSeconds (在查詢中)：整數

  timeoutSeconds

• watch (在查詢中)：布林值

  watch

回應

200 (CustomResourceDefinitionList)：OK

401：未經授權

create 建立 CustomResourceDefinition

HTTP 請求

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

參數

• body：CustomResourceDefinition，必填

• dryRun (在查詢中)：字串

  dryRun

• fieldManager (在查詢中)：字串

  fieldManager

• fieldValidation (在查詢中)：字串

  fieldValidation

• pretty (在查詢中)：字串

  pretty

回應

200 (CustomResourceDefinition)：OK

201 (CustomResourceDefinition)：已建立

202 (CustomResourceDefinition)：已接受

401：未經授權

update 取代指定的 CustomResourceDefinition

HTTP 請求

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

參數

• name (在路徑中)：字串，必填

  CustomResourceDefinition 的名稱

• body：CustomResourceDefinition，必填

• dryRun (在查詢中)：字串

  dryRun

• fieldManager (在查詢中)：字串

  fieldManager

• fieldValidation (在查詢中)：字串

  fieldValidation

• pretty (在查詢中)：字串

  pretty

回應

200 (CustomResourceDefinition)：OK

201 (CustomResourceDefinition)：已建立

401：未經授權

update 取代指定 CustomResourceDefinition 的狀態

HTTP 請求

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

參數

• name (在路徑中)：字串，必填

  CustomResourceDefinition 的名稱

• body：CustomResourceDefinition，必填

• dryRun (在查詢中)：字串

  dryRun

• fieldManager (在查詢中)：字串

  fieldManager

• fieldValidation (在查詢中)：字串

  fieldValidation

• pretty (在查詢中)：字串

  pretty

回應

200 (CustomResourceDefinition)：OK

201 (CustomResourceDefinition)：已建立

401：未經授權

patch 部分更新指定的 CustomResourceDefinition

HTTP 請求

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

參數

• name (在路徑中)：字串，必填

  CustomResourceDefinition 的名稱

• body：Patch，必填

• dryRun (在查詢中)：字串

  dryRun

• fieldManager (在查詢中)：字串

  fieldManager

• fieldValidation (在查詢中)：字串

  fieldValidation

• force (在查詢中)：布林值

  force

• pretty (在查詢中)：字串

  pretty

回應

200 (CustomResourceDefinition)：OK

201 (CustomResourceDefinition)：已建立

401：未經授權

patch 部分更新指定 CustomResourceDefinition 的狀態

HTTP 請求

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

參數

• name (在路徑中)：字串，必填

  CustomResourceDefinition 的名稱

• body：Patch，必填

• dryRun (在查詢中)：字串

  dryRun

• fieldManager (在查詢中)：字串

  fieldManager

• fieldValidation (在查詢中)：字串

  fieldValidation

• force (在查詢中)：布林值

  force

• pretty (在查詢中)：字串

  pretty

回應

200 (CustomResourceDefinition)：OK

201 (CustomResourceDefinition)：已建立

401：未經授權

delete 刪除 CustomResourceDefinition

HTTP 請求

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

參數

• name (在路徑中)：字串，必填

  CustomResourceDefinition 的名稱

• body：DeleteOptions

• dryRun (在查詢中)：字串

  dryRun

• gracePeriodSeconds (在查詢中)：整數

  gracePeriodSeconds

• pretty (在查詢中)：字串

  pretty

• propagationPolicy (在查詢中)：字串

  propagationPolicy

回應

200 (Status)：OK

202 (Status)：已接受

401：未經授權

deletecollection 刪除 CustomResourceDefinition 的集合

HTTP 請求

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

參數

• body：DeleteOptions

• continue (在查詢中)：字串

  continue

• dryRun (在查詢中)：字串

  dryRun

• fieldSelector (在查詢中)：字串

  fieldSelector

• gracePeriodSeconds (在查詢中)：整數

  gracePeriodSeconds

• labelSelector (在查詢中)：字串

  labelSelector

• limit (在查詢中)：整數

  limit

• pretty (在查詢中)：字串

  pretty

• propagationPolicy (在查詢中)：字串

  propagationPolicy

• resourceVersion (在查詢中)：字串

  resourceVersion

• resourceVersionMatch (在查詢中)：字串

  resourceVersionMatch

• sendInitialEvents (在查詢中)：布林值

  sendInitialEvents

• timeoutSeconds (在查詢中)：整數

  timeoutSeconds

回應

200 (Status)：OK

401：未經授權