ResourceClaim v1alpha3

ResourceClaim 描述叢集中資源的存取請求,供工作負載使用。

apiVersion: resource.k8s.io/v1alpha3

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

ResourceClaim

ResourceClaim 描述叢集中資源的存取請求,供工作負載使用。例如,如果工作負載需要具有特定屬性的加速器裝置,則以此方式表示該請求。狀態節點追蹤此請求是否已滿足以及已分配哪些特定資源。

這是一個 Alpha 類型,需要啟用 DynamicResourceAllocation 功能閘道。


  • apiVersion: resource.k8s.io/v1alpha3

  • kind: ResourceClaim

  • metadata (ObjectMeta)

    標準物件 metadata

  • spec (ResourceClaimSpec), required

    Spec 描述請求的內容以及如何組態。spec 是不可變的。

  • status (ResourceClaimStatus)

    Status 描述請求是否已準備好使用以及已分配的內容。

ResourceClaimSpec

ResourceClaimSpec 定義 ResourceClaim 中請求的內容以及如何組態。


  • controller (string)

    Controller 是 DRA 驅動程式的名稱,旨在處理此請求的分配。如果為空,則在排程 Pod 時由排程器處理分配。

    必須是 DNS 子網域,且應以驅動程式供應商擁有的 DNS 網域結尾。

    這是一個 Alpha 欄位,需要啟用 DRAControlPlaneController 功能閘道。

  • devices (DeviceClaim)

    Devices 定義如何請求裝置。

    DeviceClaim 定義如何使用 ResourceClaim 請求裝置。

    • devices.config ([]DeviceClaimConfiguration)

      Atomic: 將在合併期間被取代

      此欄位保存多個可能驅動程式的組態,這些驅動程式可以滿足此請求中的請求。在分配請求時會忽略它。

      DeviceClaimConfiguration 用於 DeviceClaim 中的組態參數。

      • devices.config.opaque (OpaqueDeviceConfiguration)

        Opaque 提供驅動程式特定的組態參數。

        OpaqueDeviceConfiguration 包含驅動程式供應商定義格式的驅動程式組態參數。

        • devices.config.opaque.driver (string), required

          Driver 用於判斷哪個 kubelet 外掛程式需要傳遞這些組態參數。

          驅動程式開發人員提供的許可原則可以使用它來決定是否需要驗證它們。

          必須是 DNS 子網域,且應以驅動程式供應商擁有的 DNS 網域結尾。

        • devices.config.opaque.parameters (RawExtension), required

          參數可以包含任意資料。驅動程式開發人員有責任處理驗證和版本控制。通常這包括自我識別和版本資訊(Kubernetes 類型的 "kind" + "apiVersion"),以及不同版本之間的轉換。

          *RawExtension 用於在外部版本中保存擴充功能。

          要使用此功能,請在您的外部、版本化的結構中建立一個類型為 RawExtension 的欄位,並在您的內部結構中建立 Object 欄位。您還需要註冊各種外掛程式類型。

          // 內部套件

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

          // 外部套件

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

          // 在網路上,JSON 看起來會像這樣

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

          那麼發生了什麼事?Decode 首先使用 JSON 或 YAML 將序列化資料解組為您的外部 MyAPIObject。這會導致原始 JSON 被儲存,但不會被解壓縮。下一步是複製(使用 pkg/conversion)到內部結構。runtime 套件的 DefaultScheme 安裝了轉換函數,這些函數會解壓縮儲存在 RawExtension 中的 JSON,將其轉換為正確的物件類型,並將其儲存在 Object 中。(待辦事項:如果物件類型未知,則會建立並儲存 runtime.Unknown 物件。)*

      • devices.config.requests ([]string)

        Atomic: 將在合併期間被取代

        Requests 列出組態適用的請求名稱。如果為空,則適用於所有請求。

    • devices.constraints ([]DeviceConstraint)

      Atomic: 將在合併期間被取代

      這些約束條件必須由為宣告分配的裝置集合滿足。

      DeviceConstraint 除了 Requests 之外,必須恰好設定一個欄位。

      • devices.constraints.matchAttribute (string)

        MatchAttribute 要求相關的所有裝置都具有此屬性,並且這些裝置的類型和值都相同。

        例如,如果您指定了 "dra.example.com/numa"(一個假設的範例!),則只會選擇同一個 NUMA 節點中的裝置。不具有該屬性的裝置將不會被選擇。所有裝置都應使用相同類型的值作為此屬性的值,因為這是其規格的一部分,但如果有一個裝置沒有,則該裝置也不會被選擇。

        必須包含網域限定詞。

      • devices.constraints.requests ([]string)

        Atomic: 將在合併期間被取代

        Requests 是此宣告中一個或多個請求的列表,這些請求必須共同滿足此約束條件。如果一個請求由多個裝置滿足,則所有裝置都必須滿足約束條件。如果未指定,則此約束條件適用於此宣告中的所有請求。

    • devices.requests ([]DeviceRequest)

      Atomic: 將在合併期間被取代

      Requests 代表對必須全部滿足的不同裝置的個別請求。如果為空,則不需要分配任何裝置。

      *DeviceRequest 是對宣告所需的裝置的請求。這通常是對單一資源(如裝置)的請求,但也可能請求多個相同的裝置。

      目前需要 DeviceClassName。用戶端必須檢查它是否已設定。如果它不存在,則表示某些事物已發生變更,而用戶端尚不支援這種變更,在這種情況下,它必須拒絕處理請求。*

      • devices.requests.deviceClassName (string), required

        DeviceClassName 引用特定的 DeviceClass,它可以定義要由此請求繼承的其他組態和選取器。

        需要一個類別。可用的類別取決於叢集。

        管理員可以使用此功能來限制可以請求哪些裝置,方法是僅安裝具有允許裝置選取器的類別。如果使用者可以自由請求任何東西而沒有限制,則管理員可以建立一個空的 DeviceClass 供使用者參考。

      • devices.requests.name (string), required

        Name 可用於在 pod.spec.containers[].resources.claims 條目和宣告的約束條件中引用此請求。

        必須是 DNS 標籤。

      • devices.requests.adminAccess (boolean)

        AdminAccess 表示這是對裝置管理員存取權的宣告。具有 AdminAccess 的宣告預期用於裝置的監控或其他管理服務。它們忽略對裝置的所有普通宣告,關於存取模式和任何資源分配。

      • devices.requests.allocationMode (string)

        AllocationMode 及其相關欄位定義了如何分配裝置以滿足此請求。支援的值為

        • ExactCount:此請求是針對特定數量的裝置。這是預設值。確切的數量在 count 欄位中提供。

        • All:此請求是針對集區中所有符合條件的裝置。如果某些裝置已分配,則分配將會失敗,除非請求了 adminAccess。

        如果未指定 AlloctionMode,則預設模式為 ExactCount。如果模式為 ExactCount 且未指定 count,則預設計數為一。任何其他請求都必須指定此欄位。

        未來可能會新增更多模式。用戶端必須拒絕處理具有未知模式的請求。

      • devices.requests.count (int64)

        Count 僅在計數模式為 "ExactCount" 時使用。必須大於零。如果 AllocationMode 為 ExactCount 且未指定此欄位,則預設值為一。

      • devices.requests.selectors ([]DeviceSelector)

        Atomic: 將在合併期間被取代

        Selectors 定義了特定裝置必須滿足的條件,才能將該裝置視為此請求的候選裝置。裝置要被考慮,必須滿足所有選取器。

        DeviceSelector 必須恰好設定一個欄位。

        • devices.requests.selectors.cel (CELDeviceSelector)

          CEL 包含用於選取裝置的 CEL 表達式。

          CELDeviceSelector 包含用於選取裝置的 CEL 表達式。

          • devices.requests.selectors.cel.expression (string), required

            Expression 是一個 CEL 表達式,用於評估單個裝置。當正在考慮的裝置滿足所需條件時,它必須評估為 true,而當不滿足時,則評估為 false。任何其他結果都是錯誤,並導致裝置分配中止。

            表達式的輸入是一個名為 "device" 的物件,它攜帶以下屬性

            • driver (string):定義此裝置的驅動程式名稱。
            • attributes (map[string]object):裝置的屬性,按前綴分組(例如,device.attributes["dra.example.com"] 評估為一個物件,其中包含所有以 "dra.example.com" 為前綴的屬性。
            • capacity (map[string]object):裝置的容量,按前綴分組。

            範例:考慮一個 driver="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 欄位可用於檢查特定的驅動程式,無論是作為高階先決條件(即,您只想考慮來自此驅動程式的裝置),還是作為旨在考慮來自不同驅動程式的裝置的多子句表達式的一部分。

            每個屬性的值類型由裝置定義定義,編寫這些表達式的用戶必須查閱其特定驅動程式的文件。每個容量的值類型為 Quantity。

            如果使用未知前綴作為 device.attributes 或 device.capacity 中的查找,則會傳回一個空的地圖。任何對未知欄位的引用都將導致評估錯誤並中止分配。

            一個穩健的表達式應在引用屬性之前檢查屬性的存在。

            為了易於使用,啟用了 cel.bind() 函數,可用於簡化存取具有相同網域的多個屬性的表達式。例如

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

ResourceClaimStatus

ResourceClaimStatus 追蹤資源是否已分配以及分配結果。


  • allocation (AllocationResult)

    Allocation 在宣告成功分配後設定。

    AllocationResult 包含已分配資源的屬性。

    • allocation.controller (string)

      Controller 是處理分配的 DRA 驅動程式的名稱。該驅動程式也負責解除宣告分配。當可以在不涉及驅動程式的情況下解除宣告分配時,它為空。

      驅動程式可以分配其他驅動程式提供的裝置,因此此處的驅動程式名稱可能與結果中列出的驅動程式名稱不同。

      這是一個 Alpha 欄位,需要啟用 DRAControlPlaneController 功能閘道。

    • allocation.devices (DeviceAllocationResult)

      Devices 是分配裝置的結果。

      DeviceAllocationResult 是分配裝置的結果。

      • allocation.devices.config ([]DeviceAllocationConfiguration)

        Atomic: 將在合併期間被取代

        此欄位是所有宣告和類別組態參數的組合。驅動程式可以根據標誌區分它們。

        這包括沒有在結果中分配裝置的驅動程式的組態參數,因為這取決於驅動程式支援哪些組態參數。它們可以靜默地忽略未知的組態參數。

        DeviceAllocationConfiguration 嵌入在 AllocationResult 中。

        • allocation.devices.config.source (string), required

          Source 記錄組態是來自類別(因此不是普通使用者可以設定的內容)還是來自宣告。

        • allocation.devices.config.opaque (OpaqueDeviceConfiguration)

          Opaque 提供驅動程式特定的組態參數。

          OpaqueDeviceConfiguration 包含驅動程式供應商定義格式的驅動程式組態參數。

          • allocation.devices.config.opaque.driver (string), required

            Driver 用於判斷哪個 kubelet 外掛程式需要傳遞這些組態參數。

            驅動程式開發人員提供的許可原則可以使用它來決定是否需要驗證它們。

            必須是 DNS 子網域,且應以驅動程式供應商擁有的 DNS 網域結尾。

          • allocation.devices.config.opaque.parameters (RawExtension), required

            參數可以包含任意資料。驅動程式開發人員有責任處理驗證和版本控制。通常這包括自我識別和版本資訊(Kubernetes 類型的 "kind" + "apiVersion"),以及不同版本之間的轉換。

            *RawExtension 用於在外部版本中保存擴充功能。

            要使用此功能,請在您的外部、版本化的結構中建立一個類型為 RawExtension 的欄位,並在您的內部結構中建立 Object 欄位。您還需要註冊各種外掛程式類型。

            // 內部套件

            type MyAPIObject struct { runtime.TypeMeta json:",inline" MyPlugin runtime.Object json:"myPlugin" }

            type PluginA struct { AOption string json:"aOption" }

            // 外部套件

            type MyAPIObject struct { runtime.TypeMeta json:",inline" MyPlugin runtime.RawExtension json:"myPlugin" }

            type PluginA struct { AOption string json:"aOption" }

            // 在網路上,JSON 看起來會像這樣

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

            那麼發生了什麼事?Decode 首先使用 JSON 或 YAML 將序列化資料解組為您的外部 MyAPIObject。這會導致原始 JSON 被儲存,但不會被解壓縮。下一步是複製(使用 pkg/conversion)到內部結構。runtime 套件的 DefaultScheme 安裝了轉換函數,這些函數會解壓縮儲存在 RawExtension 中的 JSON,將其轉換為正確的物件類型,並將其儲存在 Object 中。(待辦事項:如果物件類型未知,則會建立並儲存 runtime.Unknown 物件。)*

        • allocation.devices.config.requests ([]string)

          Atomic: 將在合併期間被取代

          Requests 列出組態適用的請求名稱。如果為空,則適用於所有請求。

      • allocation.devices.results ([]DeviceRequestAllocationResult)

        Atomic: 將在合併期間被取代

        Results 列出所有已分配的裝置。

        DeviceRequestAllocationResult 包含一個請求的分配結果。

        • allocation.devices.results.device (string), required

          Device 通過其在驅動程式資源集區中的名稱引用一個裝置實例。它必須是 DNS 標籤。

        • allocation.devices.results.driver (string), required

          Driver 指定 DRA 驅動程式的名稱,該驅動程式的 kubelet 外掛程式應在節點上需要宣告時被調用以處理分配。

          必須是 DNS 子網域,且應以驅動程式供應商擁有的 DNS 網域結尾。

        • allocation.devices.results.pool (string), required

          此名稱與驅動程式名稱和裝置名稱欄位一起識別分配了哪個裝置 (\<driver name>/\<pool name>/\<device name>)。

          長度不得超過 253 個字元,並且可以包含一個或多個以斜線分隔的 DNS 子網域。

        • allocation.devices.results.request (string), required

          Request 是宣告中導致分配此裝置的請求名稱。每個請求可能已分配多個裝置。

    • allocation.nodeSelector (NodeSelector)

      NodeSelector 定義已分配資源可用的位置。如果未設定,則它們在任何地方都可用。

      節點選取器代表一組節點上一個或多個標籤查詢結果的聯集;也就是說,它代表節點選取器術語所代表的選取器的 OR 運算。

      • allocation.nodeSelector.nodeSelectorTerms ([]NodeSelectorTerm), required

        Atomic: 將在合併期間被取代

        Required. 節點選取器術語的列表。這些術語是 OR 運算。

        空值或空節點選取器術語與任何物件都不匹配。它們的要求是 AND 運算。TopologySelectorTerm 類型實作了 NodeSelectorTerm 的子集。

        • allocation.nodeSelector.nodeSelectorTerms.matchExpressions ([]NodeSelectorRequirement)

          Atomic: 將在合併期間被取代

          節點標籤的節點選取器需求列表。

        • allocation.nodeSelector.nodeSelectorTerms.matchFields ([]NodeSelectorRequirement)

          Atomic: 將在合併期間被取代

          節點欄位的節點選取器需求列表。

  • deallocationRequested (boolean)

    表示請求解除宣告分配。當設定此項時,不得將新的消費者新增到 ReservedFor。

    僅當宣告需要由 DRA 驅動程式解除分配時才使用此項。然後,該驅動程式必須解除分配此宣告,並重置該欄位以及清除 Allocation 欄位。

    這是一個 Alpha 欄位,需要啟用 DRAControlPlaneController 功能閘道。

  • reservedFor ([]ResourceClaimConsumerReference)

    Patch 策略:在鍵 uid 上合併

    Map:在合併期間,將保留鍵 uid 上的唯一值

    ReservedFor 指示目前允許哪些實體使用宣告。未為 Pod 保留的 ResourceClaim 的 Pod 將不會啟動。正在使用或可能正在使用的宣告(因為它已被保留)不得解除分配。

    在具有多個排程器實例的叢集中,兩個 Pod 可能會由不同的排程器同時排程。當它們引用已達到其最大消費者數量的同一個 ResourceClaim 時,只能排程一個 Pod。

    兩個排程器都嘗試將其 Pod 新增到 claim.status.reservedFor 欄位,但只有第一個到達 API 伺服器的更新才會被儲存。另一個更新會失敗並出現錯誤,發出該更新的排程器知道它必須將 Pod 放回佇列,等待 ResourceClaim 再次變得可用。

    最多可以有 32 個這樣的保留。未來可能會增加,但不會減少。

    ResourceClaimConsumerReference 包含足夠的資訊,讓您可以找到 ResourceClaim 的消費者。使用者必須是與 ResourceClaim 位於相同命名空間中的資源。

    • reservedFor.name (string), required

      Name 是被引用資源的名稱。

    • reservedFor.resource (string), required

      Resource 是被引用資源的類型,例如 "pods"。

    • reservedFor.uid (string), required

      UID 唯一識別資源的一個實例。

    • reservedFor.apiGroup (string)

      APIGroup 是被引用資源的群組。對於核心 API,它為空。這與建立資源時使用的 APIVersion 中的群組匹配。

ResourceClaimList

ResourceClaimList 是宣告的集合。


  • apiVersion: resource.k8s.io/v1alpha3

  • kind: ResourceClaimList

  • metadata (ListMeta)

    標準列表 metadata

  • items ([]ResourceClaim), required

    Items 是資源宣告的列表。

Operations


get 讀取指定的 ResourceClaim

HTTP Request

GET /apis/resource.k8s.io/v1alpha3/namespaces/{namespace}/resourceclaims/{name}

Parameters

  • name (in path): string, required

    ResourceClaim 的名稱

  • namespace (in path): string, required

    命名空間

  • pretty (in query): string

    pretty

Response

200 (ResourceClaim): OK

401: Unauthorized

get 讀取指定 ResourceClaim 的狀態

HTTP Request

GET /apis/resource.k8s.io/v1alpha3/namespaces/{namespace}/resourceclaims/{name}/status

Parameters

  • name (in path): string, required

    ResourceClaim 的名稱

  • namespace (in path): string, required

    命名空間

  • pretty (in query): string

    pretty

Response

200 (ResourceClaim): OK

401: Unauthorized

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

HTTP Request

GET /apis/resource.k8s.io/v1alpha3/namespaces/{namespace}/resourceclaims

Parameters

Response

200 (ResourceClaimList): OK

401: Unauthorized

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

HTTP Request

GET /apis/resource.k8s.io/v1alpha3/resourceclaims

Parameters

Response

200 (ResourceClaimList): OK

401: Unauthorized

create 建立 ResourceClaim

HTTP Request

POST /apis/resource.k8s.io/v1alpha3/namespaces/{namespace}/resourceclaims

Parameters

Response

200 (ResourceClaim): OK

201 (ResourceClaim): Created

202 (ResourceClaim): Accepted

401: Unauthorized

update 取代指定的 ResourceClaim

HTTP Request

PUT /apis/resource.k8s.io/v1alpha3/namespaces/{namespace}/resourceclaims/{name}

Parameters

Response

200 (ResourceClaim): OK

201 (ResourceClaim): Created

401: Unauthorized

update 取代指定 ResourceClaim 的狀態

HTTP Request

PUT /apis/resource.k8s.io/v1alpha3/namespaces/{namespace}/resourceclaims/{name}/status

Parameters

Response

200 (ResourceClaim): OK

201 (ResourceClaim): Created

401: Unauthorized

patch 部分更新指定的 ResourceClaim

HTTP Request

PATCH /apis/resource.k8s.io/v1alpha3/namespaces/{namespace}/resourceclaims/{name}

Parameters

  • name (in path): string, required

    ResourceClaim 的名稱

  • namespace (in path): string, required

    命名空間

  • body: Patch, required

  • dryRun (in query): string

    dryRun

  • fieldManager (in query): string

    fieldManager

  • fieldValidation (in query): string

    fieldValidation

  • force (in query): boolean

    force

  • pretty (in query): string

    pretty

Response

200 (ResourceClaim): OK

201 (ResourceClaim): Created

401: Unauthorized

patch 部分更新指定 ResourceClaim 的狀態

HTTP Request

PATCH /apis/resource.k8s.io/v1alpha3/namespaces/{namespace}/resourceclaims/{name}/status

Parameters

  • name (in path): string, required

    ResourceClaim 的名稱

  • namespace (in path): string, required

    命名空間

  • body: Patch, required

  • dryRun (in query): string

    dryRun

  • fieldManager (in query): string

    fieldManager

  • fieldValidation (in query): string

    fieldValidation

  • force (in query): boolean

    force

  • pretty (in query): string

    pretty

Response

200 (ResourceClaim): OK

201 (ResourceClaim): Created

401: Unauthorized

delete 刪除 ResourceClaim

HTTP Request

DELETE /apis/resource.k8s.io/v1alpha3/namespaces/{namespace}/resourceclaims/{name}

Parameters

Response

200 (ResourceClaim): OK

202 (ResourceClaim): Accepted

401: Unauthorized

deletecollection 刪除 ResourceClaim 的集合

HTTP Request

DELETE /apis/resource.k8s.io/v1alpha3/namespaces/{namespace}/resourceclaims

Parameters

Response

200 (Status): OK

401: Unauthorized

此頁面為自動產生。

如果您計劃回報此頁面的問題,請在您的問題描述中提及此頁面為自動產生。修正可能需要在 Kubernetes 專案中的其他地方進行。

上次修改時間:2024 年 8 月 28 日下午 6:01 PST:Update generated API reference for v1.31 (8ba98c79c1)