后端云原生容器編排【免費(fèi)下載鏈接】pythonOfficial Python client library for kubernetes項(xiàng)目地址https://gitcode.com/gh_mirrors/python1/python點(diǎn)擊查看免費(fèi)下載導(dǎo)讀本文面向使用官方 Kubernetes Python 客戶端本項(xiàng)目倉(cāng)庫(kù)gh_mirrors/python1/python的開(kāi)發(fā)者系統(tǒng)講解V1beta2ResourceClaim模型——它是 Kubernetes 動(dòng)態(tài)資源分配Dynamic Resource Allocation簡(jiǎn)稱 DRA體系中描述工作負(fù)載需要訪問(wèn)集群中哪些資源的核心對(duì)象。讀完本文你將掌握該模型的字段結(jié)構(gòu)、JSON 序列化規(guī)則、與ResourceV1beta2Api的聯(lián)動(dòng)方式以及如何在同步kubernetes.client與異步kubernetes.aio.client兩種客戶端形態(tài)下構(gòu)造并提交一個(gè)真實(shí)的 ResourceClaim。本文以 doc/source/kubernetes.aio.client.models.v1beta2_resource_claim.rst 自動(dòng)生成的模塊文檔為入口結(jié)合 kubernetes/aio/client/models/v1beta2_resource_claim.py 等源碼進(jìn)行縱深解讀。一、模塊文檔與模型定位1.1 文檔入口與 automodule 機(jī)制關(guān)聯(lián)文檔 doc/source/kubernetes.aio.client.models.v1beta2_resource_claim.rst 是典型的 Sphinxautomodule自動(dòng) API 參考頁(yè).. automodule:: kubernetes.aio.client.models.v1beta2_resource_claim :members: :show-inheritance: :undoc-members:它并不手工羅列成員而是指示 Sphinx 從kubernetes.aio.client.models.v1beta2_resource_claim模塊中提取全部公開(kāi)成員:members:、繼承關(guān)系:show-inheritance:以及未寫文檔字符串的成員:undoc-members:最終渲染出V1beta2ResourceClaim類的完整參考。也就是說(shuō)本文講述的真實(shí)文檔內(nèi)容就是該模型類的 docstring 與全部公開(kāi) API。1.2 模型在 DRA 架構(gòu)中的位置從源碼 docstring 與 OpenAPI 定義scripts/swagger.json中的v1beta2.ResourceClaim可知ResourceClaim 描述了工作負(fù)載對(duì)集群內(nèi)資源的訪問(wèn)請(qǐng)求。例如若某個(gè)工作負(fù)載需要具有特定屬性的加速器設(shè)備accelerator device該請(qǐng)求正是通過(guò) ResourceClaim 表達(dá)的status段記錄了該請(qǐng)求是否已被滿足以及具體分配了哪些資源。兩個(gè)關(guān)鍵前提源碼與 swagger 雙重確認(rèn)見(jiàn) kubernetes/aio/client/models/v1beta2_resource_claim.py這是一個(gè)alpha 級(jí)類型需要啟用DynamicResourceAllocationfeature gate生成的 OpenAPI 文檔版本為release-1.37見(jiàn)文件頭注釋。模型類繼承自pydantic.BaseModel采用 Pydantic v2 校驗(yàn)體系配套生成類屬性openapi_types字段到類型的映射與attribute_mapPython 屬性名到 JSON 線上名映射并實(shí)現(xiàn)了to_dict/from_dict/to_json/from_json等序列化方法。完整的同步版本位于 kubernetes/client/models/v1beta2_resource_claim.py二者內(nèi)容一致分別服務(wù)于kubernetes.client與kubernetes.aio.client兩套包。二、字段結(jié)構(gòu)全景V1beta2ResourceClaim共聲明 5 個(gè)字段對(duì)應(yīng)__properties [apiVersion, kind, metadata, spec, status]下表匯總了字段、類型、JSON 線上名與說(shuō)明字段Python類型JSON 線上名說(shuō)明api_versionOptional[str]apiVersion對(duì)象的版本化 schema 標(biāo)識(shí)服務(wù)端應(yīng)將已識(shí)別的 schema 轉(zhuǎn)換為最新的內(nèi)部值并可能拒絕未識(shí)別的值kindOptional[str]kind對(duì)象所代表的 REST 資源類型字符串CamelCase不可更新metadataOptional[V1ObjectMeta]metadata標(biāo)準(zhǔn)對(duì)象元數(shù)據(jù)specOptional[V1beta2ResourceClaimSpec]spec描述請(qǐng)求什么資源以及如何配置該字段不可變immutablestatusOptional[V1beta2ResourceClaimStatus]status描述聲明是否已就緒可用以及已分配了什么資源對(duì)應(yīng)實(shí)現(xiàn)位于 kubernetes/aio/client/models/v1beta2_resource_claim.py其中openapi_types與attribute_map完整給出openapi_types: ClassVar[Dict[str, str]] { api_version: str, kind: str, metadata: V1ObjectMeta, spec: V1beta2ResourceClaimSpec, status: V1beta2ResourceClaimStatus } attribute_map: ClassVar[Dict[str, str]] { api_version: apiVersion, kind: kind, metadata: metadata, spec: spec, status: status }2.1 specV1beta2ResourceClaimSpeckubernetes/aio/client/models/v1beta2_resource_claim_spec.py 定義的V1beta2ResourceClaimSpec只有一個(gè)字段devices: Optional[V1beta2DeviceClaim]JSON 線上名同為devices含義為如何請(qǐng)求設(shè)備。也就是說(shuō)v1beta2 的 ResourceClaim 聲明內(nèi)容全部收斂在DeviceClaim上。V1beta2DeviceClaim見(jiàn) kubernetes/aio/client/models/v1beta2_device_claim.py包含三個(gè)列表字段字段類型說(shuō)明configList[V1beta2DeviceClaimConfiguration]為多個(gè)潛在 driver 提供的配置在分配聲明時(shí)被忽略constraintsList[V1beta2DeviceConstraint]必須被分配給該聲明的設(shè)備集合整體滿足的約束requestsList[V1beta2DeviceRequest]對(duì)獨(dú)立設(shè)備的逐個(gè)請(qǐng)求必須全部被滿足為空則無(wú)需分配任何東西其中V1beta2DeviceConstraintv1beta2_device_constraint.py必須恰好設(shè)置requests之外的其中一個(gè)字段match_attribute要求所有設(shè)備都具有該屬性且類型與值一致例如dra.example.com/numa可確保設(shè)備處于同一 NUMA 節(jié)點(diǎn)屬性名必須帶域名限定符distinct_attribute與match_attribute相反要求所有設(shè)備在該屬性上互不相同例如為兩個(gè)網(wǎng)絡(luò)接口分配來(lái)自不同物理 NIC 的設(shè)備requests約束所作用的請(qǐng)求名列表支持main request/[subrequest]格式。而V1beta2DeviceRequestv1beta2_device_request.py則要求必須提供nameDNS label可在pod.spec.containers[].resources.claims中引用并通過(guò)互斥的兩種方式之一聲明所需設(shè)備exactly: V1beta2ExactDeviceRequest請(qǐng)求一個(gè)或多個(gè)完全相同的設(shè)備first_available: List[V1beta2DeviceSubRequest]按優(yōu)先級(jí)列出多個(gè)候選子請(qǐng)求調(diào)度器按列表順序嘗試第一個(gè)可用者勝出DRA 當(dāng)前尚未實(shí)現(xiàn)打分scoring。V1beta2ExactDeviceRequestv1beta2_exact_device_request.py的字段要點(diǎn)device_class_name必填引用某個(gè) DeviceClass可繼承其額外的配置與選擇器allocation_mode可選ExactCount默認(rèn)或AllExactCount下未指定count時(shí)默認(rèn) 1count僅用于ExactCount模式必須大于 0selectors設(shè)備候選的過(guò)濾條件所有選擇器必須同時(shí)滿足tolerations最多 16 條用于容忍設(shè)備的 taint需啟用DRADeviceTaintsgatebetaadmin_access管理性訪問(wèn)聲明需啟用DRAAdminAccessgatealphaderived_attributes通過(guò) CEL 表達(dá)式計(jì)算的虛擬屬性最多 32 個(gè)需啟用DRADerivedAttributesgatealpha。V1beta2DeviceSubRequestv1beta2_device_sub_request.py與ExactDeviceRequest類似但不暴露adminAccess字段且額外要求name引用格式main request/subrequest。2.2 statusV1beta2ResourceClaimStatuskubernetes/aio/client/models/v1beta2_resource_claim_status.py 定義了三個(gè)字段字段Python類型JSON 線上名說(shuō)明allocationOptional[V1beta2AllocationResult]allocation聲明被成功分配后由控制器寫入devicesList[V1beta2AllocatedDeviceStatus]devicesdriver 報(bào)告的每個(gè)已分配設(shè)備的狀態(tài)可包含 driver 專屬信息reserved_forList[V1beta2ResourceClaimConsumerReference]reservedFor當(dāng)前允許使用該聲明的實(shí)體最多 256 條預(yù)留值得關(guān)注的是 swagger 定義scripts/swagger.json中v1beta2.ResourceClaimStatus補(bǔ)充的兩種 OpenAPI 元數(shù)據(jù)devices為x-kubernetes-list-type: map以driver、device、pool、shareID為 map 鍵reservedFor同樣為 map 列表以u(píng)id為鍵并聲明x-kubernetes-patch-merge-key: uid與x-kubernetes-patch-strategy: merge即服務(wù)端支持按uid合并式 PATCH。V1beta2AllocatedDeviceStatusv1beta2_allocated_device_status.py包含conditions最多 8 條V1Condition設(shè)備就緒時(shí)Ready條件應(yīng)為 True、datadriver 自定義數(shù)據(jù)原始長(zhǎng)度 ≤ 10 Ki、device、driver、pool三者共同構(gòu)成driver/pool/device標(biāo)識(shí)以及可選的shareID、networkData。V1beta2ResourceClaimConsumerReferencev1beta2_resource_claim_consumer_reference.py則用apiGroup、name、resource、uid四個(gè)字段精確定位一個(gè)消費(fèi)者必須與 ResourceClaim 處于同一 namespace。V1beta2AllocationResultv1beta2_allocation_result.py記錄分配結(jié)果allocationTimestamp資源分配時(shí)間beta需啟用DRADeviceBindingConditions與DRAResourceClaimDeviceStatusgate、devicesV1beta2DeviceAllocationResult以及nodeSelector限定資源所在節(jié)點(diǎn)。三、字段名的駝峰轉(zhuǎn)換validation_alias 與序列化機(jī)制與早期python-legacy生成器不同本倉(cāng)庫(kù)的模型以 Pydantic v2 為基礎(chǔ)對(duì)線上名wire name采用駝峰、Python 屬性名采用下劃線命名。例如api_version?apiVersionreserved_for?reservedForfirst_available?firstAvailabledevice_class_name?deviceClassName這在源碼中以validation_aliasAliasChoices(apiVersion, api_version)與serialization_aliasapiVersion成對(duì)出現(xiàn)見(jiàn) v1beta2_resource_claim.py。__preprocess_input_names負(fù)責(zé)在反序列化時(shí)把下劃線鍵名映射為駝峰鍵名見(jiàn) v1beta2_resource_claim_status.py因此構(gòu)造對(duì)象時(shí)兩種寫法均可V1beta2ResourceClaim(api_version...)或V1beta2ResourceClaim(apiVersion...)序列化到 JSON 時(shí)to_json()/to_dict(serializeTrue)一律輸出駝峰線上名與 Kubernetes API 服務(wù)器要求的 JSON 完全一致反序列化時(shí)from_dict()/from_json()對(duì) API 服務(wù)器返回的駝峰 JSON 同樣可正確處理。模型配置model_config同時(shí)開(kāi)啟了validate_by_nameTrue、validate_by_aliasTrue、validate_assignmentTrue并將extra設(shè)為forbid未知字段會(huì)觸發(fā)校驗(yàn)錯(cuò)誤protected_namespaces()允許字段名以model_等保留前綴開(kāi)頭見(jiàn) v1beta2_resource_claim.py。四、CRUD 操作與 ResourceV1beta2Api 聯(lián)動(dòng)V1beta2ResourceClaim對(duì)象本身只是數(shù)據(jù)模型真正提交給集群需通過(guò)ResourceV1beta2Api異步版類位于 kubernetes/aio/client/api/resource_v1beta2_api.py。對(duì)應(yīng) REST 端點(diǎn)已在scripts/swagger.json中定義POST /apis/resource.k8s.io/v1beta2/namespaces/{namespace}/resourceclaimsDELETE /apis/resource.k8s.io/v1beta2/namespaces/{namespace}/resourceclaims/{name}GET /apis/resource.k8s.io/v1beta2/namespaces/{namespace}/resourceclaimsGET /apis/resource.k8s.io/v1beta2/resourceclaims跨 namespace 列舉4.1 異步創(chuàng)建create_namespaced_resource_claim核心方法簽名見(jiàn) resource_v1beta2_api.pyasync def create_namespaced_resource_claim( self, namespace: Annotated[StrictStr, ...], body: V1beta2ResourceClaim, pretty: Optional[str] None, dry_run: Optional[str] None, field_manager: Optional[str] None, field_validation: Optional[str] None, ... ) - V1beta2ResourceClaim:參數(shù)說(shuō)明namespace對(duì)象所在命名空間必填bodyV1beta2ResourceClaim實(shí)例必填請(qǐng)求成功返回 200/201/202 與新建的對(duì)象prettytrue時(shí)輸出美化 JSONdry_runAll表示執(zhí)行所有 dry-run 階段但不持久化field_manager關(guān)聯(lián)的 fieldManager 名稱≤ 128 個(gè)可打印字符field_validationIgnore丟棄未知字段v1.23 之前默認(rèn)、Warn返回警告頭v1.23 默認(rèn)、Strict遇到未知/重復(fù)字段直接報(bào) BadRequest。4.2 完整的異步創(chuàng)建示例import asyncio from kubernetes import config from kubernetes.aio import config as aio_config from kubernetes.aio.client import ApiClient from kubernetes.aio.client.api import ResourceV1beta2Api from kubernetes.aio.client.models import ( V1ObjectMeta, V1beta2DeviceClaim, V1beta2DeviceRequest, V1beta2ExactDeviceRequest, V1beta2ResourceClaim, V1beta2ResourceClaimSpec, ) async def main(): # 使用集群外 kubeconfig也可改用 load_incluster_config await aio_config.load_kube_config() async with ApiClient() as client: api ResourceV1beta2Api(client) claim V1beta2ResourceClaim( api_versionresource.k8s.io/v1beta2, kindResourceClaim, metadataV1ObjectMeta(namegpu-claim, namespacedefault), specV1beta2ResourceClaimSpec( devicesV1beta2DeviceClaim( requests[ V1beta2DeviceRequest( namegpu, exactlyV1beta2ExactDeviceRequest( device_class_namegpu.example.com, count1, allocation_modeExactCount, ), ) ] ) ), ) created await api.create_namespaced_resource_claim( namespacedefault, bodyclaim, field_managermy-app ) print(created.to_dict()) asyncio.run(main())該示例使用了 examples_asyncio/ 目錄所體現(xiàn)的async with ApiClient()資源管理慣例以及kubernetes.aio.config的異步配置加載方式見(jiàn) examples_asyncio/list_pods.py。4.3 同步形態(tài)若使用同步客戶端將導(dǎo)入路徑換成kubernetes.client即可類與方法的簽名保持一致from kubernetes import client, config config.load_kube_config() api client.ResourceV1beta2Api() claim client.V1beta2ResourceClaim( api_versionresource.k8s.io/v1beta2, kindResourceClaim, metadataclient.V1ObjectMeta(namegpu-claim, namespacedefault), specclient.V1beta2ResourceClaimSpec( devicesclient.V1beta2DeviceClaim( requests[ client.V1beta2DeviceRequest( namegpu, exactlyclient.V1beta2ExactDeviceRequest( device_class_namegpu.example.com, count1, allocation_modeExactCount, ), ) ] ) ), ) created api.create_namespaced_resource_claim(namespacedefault, bodyclaim)兩種客戶端的完整方法列表可見(jiàn) kubernetes/README.mdResourceV1beta2Api一節(jié)包含 create/delete/list/patch/read/replace 以及 resourceclaimtemplate 相關(guān)方法。五、對(duì)象序列化與反序列化實(shí)踐V1beta2ResourceClaim繼承自 PydanticBaseModel并覆蓋了序列化接口常用方法方法說(shuō)明to_dict(serializeFalse)返回 Python 字典鍵為 Python 屬性名下劃線風(fēng)格to_dict(serializeTrue)/to_json()輸出線上格式鍵為駝峰 JSON 名如apiVersion、reservedForfrom_dict(obj)從字典構(gòu)建實(shí)例自動(dòng)處理駝峰/下劃線鍵名映射from_json(json_str)從 JSON 字符串構(gòu)建實(shí)例to_str()/__repr__打印友好的多行字符串表示便于調(diào)試?yán)鏲laim V1beta2ResourceClaim.from_dict({ apiVersion: resource.k8s.io/v1beta2, kind: ResourceClaim, metadata: {name: gpu-claim, namespace: default}, spec: {devices: {requests: [...]}}, }) print(claim.to_json()) # 輸出駝峰 JSON可直接用于 API 請(qǐng)求體源碼中的__openapi_generator_modern_projection見(jiàn) v1beta2_resource_claim.py保證嵌套模型metadata、spec、status也通過(guò)各自的to_dict()遞歸轉(zhuǎn)換從而得到與 API 服務(wù)器一致的完整線上 JSON。六、使用前提與限制綜合源碼 docstring 與 swagger 定義使用V1beta2ResourceClaim需注意以下前提與限制feature gate類型本身為 alpha需在集群開(kāi)啟DynamicResourceAllocation部分子字段還依賴額外 gate——DRAAdminAccessalpha、DRADerivedAttributesalpha、DRADeviceTaintsbeta、DRADeviceBindingConditions/DRAResourceClaimDeviceStatusbeta影響allocationTimestamp、DRAListTypeAttributes影響約束屬性的集合語(yǔ)義比較。不可變性spec不可更新swagger 明確標(biāo)注 The spec is immutable變更聲明需重建對(duì)象。配額與上限status.reservedFor最多 256 條預(yù)留ExactDeviceRequest.tolerations最多 16 條AllocatedDeviceStatus.conditions最多 8 條data原始長(zhǎng)度 ≤ 10 KiBderived_attributes最多 32 個(gè)。name 約束DeviceRequest.name、DeviceSubRequest.name、AllocatedDeviceStatus.device必須為 DNS labeldriver必須為 DNS 子域且建議以廠商擁有的域名結(jié)尾。并發(fā)調(diào)度語(yǔ)義多調(diào)度器實(shí)例并發(fā)為同一 claim 預(yù)留消費(fèi)者時(shí)僅最先到達(dá) API Server 的更新會(huì)被存儲(chǔ)其余調(diào)度器需將 Pod 重新入隊(duì)等待聲明恢復(fù)可用見(jiàn)reservedFor的字段說(shuō)明。七、源碼擴(kuò)展閱讀指引模型主文件kubernetes/aio/client/models/v1beta2_resource_claim.py同步版模型kubernetes/client/models/v1beta2_resource_claim.pyspec 與 statusv1beta2_resource_claim_spec.py、v1beta2_resource_claim_status.py設(shè)備請(qǐng)求相關(guān)v1beta2_device_claim.py、v1beta2_device_request.py、v1beta2_exact_device_request.py、v1beta2_device_sub_request.py分配狀態(tài)相關(guān)v1beta2_allocation_result.py、v1beta2_allocated_device_status.py、v1beta2_resource_claim_consumer_reference.pyAPI 層kubernetes/aio/client/api/resource_v1beta2_api.py異步、kubernetes/client/api/resource_v1beta2_api.py同步OpenAPI 定義scripts/swagger.jsonv1beta2.ResourceClaim等定義客戶端方法索引kubernetes/README.md結(jié)語(yǔ)V1beta2ResourceClaim是官方 Kubernetes Python 客戶端中表達(dá) DRA 資源請(qǐng)求的標(biāo)準(zhǔn)載體它以spec.devices描述要什么設(shè)備、滿足什么約束以status承載分配結(jié)果與消費(fèi)方預(yù)留配合ResourceV1beta2Api的 CRUD 方法即可完整落地按需分配加速器/網(wǎng)卡等異構(gòu)設(shè)備的典型場(chǎng)景。理解其駝峰別名、不可變 spec 與各 feature gate 前提是正確、安全地使用這一 alpha 類型的基礎(chǔ)。贊分享后端云原生容器編排【免費(fèi)下載鏈接】pythonOfficial Python client library for kubernetes項(xiàng)目地址https://gitcode.com/gh_mirrors/python1/python點(diǎn)擊查看免費(fèi)下載相關(guān)推薦Kubernetes Python 客戶端 V1ResourceClaimTemplateSpec 模型詳解Dynamic Resource Allocation 的資源聲明模板開(kāi)發(fā)指南Kubernetes Python 客戶端 V1ResourceClaimTemplateSpec 模型詳解Dynamic Resource Allocati后端云原生容器編排Kubernetes Python 客戶端 V1ResourceSliceSpec 模型詳解Dynamic Resource Allocation 資源切片聲明與序列化實(shí)踐Kubernetes Python 客戶端 V1ResourceSliceSpec 模型詳解Dynamic Resource Allocation 資源切片聲后端云原生容器編排Kubernetes Python 客戶端 V1beta2ResourceSliceSpec 模型全解析Dynamic Resource Allocation 的資源發(fā)布協(xié)議Kubernetes Python 客戶端 V1beta2ResourceSliceSpec 模型全解析Dynamic Resource Allocation后端云原生容器編排創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考