后端云原生容器编排【免费下载链接】pythonOfficial Python client library for kubernetes项目地址https://gitcode.com/gh_mirrors/python1/python点击查看免费下载本文聚焦官方 Python 客户端库kubernetes中kubernetes.aio.client.models.v1_csi_driver_spec模块含其同步版kubernetes.client.models.v1_csi_driver_spec的V1CSIDriverSpec模型。该模型对应 Kubernetesstorage.k8s.io/v1下CSIDriver对象的spec结构是声明 CSI 卷驱动程序 attach、挂载、调度、SELinux、ServiceAccount Token 与容量感知等行为的核心配置载体。读完本文你将掌握V1CSIDriverSpec全部 11 个字段的语义、默认值与不可变性约束理解其序列化/反序列化机制to_dict/from_dict/from_json与属性别名映射并能在StorageV1Api同步与StorageV1Api异步kubernetes.aio中完整地创建、读取、更新CSIDriver对象。模型定位CSIDriver 的 spec 是什么在 Kubernetes 存储体系里CSIDriver是一个集群级非命名空间对象用于描述部署在集群中的某个 CSIContainer Storage Interface卷驱动。正如 V1CSIDriver 模型 类注释所述Kubernetes 的 attach/detach 控制器使用该对象判断是否需要执行 attachkubelet 则使用它判断挂载时是否需要传入 Pod 信息。而V1CSIDriverSpec正是这个对象的spec字段类型。从 Sphinx 文档入口 doc/source/kubernetes.aio.client.models.v1_csi_driver_spec.rst 看该 RST 通过automodule指令完整收录V1CSIDriverSpec类的全部成员:members:、:show-inheritance:、:undoc-members:。实际模型实现位于 kubernetes/aio/client/models/v1_csi_driver_spec.py异步包与 kubernetes/client/models/v1_csi_driver_spec.py同步包二者代码逻辑完全一致仅内部依赖导入路径不同分别引用kubernetes.aio.client.models.storage_v1_token_request与kubernetes.client.models.storage_v1_token_request。V1CSIDriverSpec继承自pydantic.BaseModel模型头部注释标明其由 OpenAPI Generator 基于 Kubernetesrelease-1.37的 scripts/swagger.json定义见其中v1.CSIDriverSpec一节自动生成因此所有字段的语义描述与 Kubernetes API 服务器端保持严格一致。十一个字段全景速览先看模型类中定义的类型映射openapi_types与属性名映射attribute_map见 v1_csi_driver_spec.pyPython 属性snake_case线上 JSON 字段camelCase类型默认值是否可变immutableattach_requiredattachRequiredboolNone不可变fs_group_policyfsGroupPolicystrNone语义默认ReadWriteOnceWithFSType1.29 不可变现可变node_allocatable_update_period_secondsnodeAllocatableUpdatePeriodSecondsintNone可变pod_info_on_mountpodInfoOnMountboolNone语义默认false1.29 不可变现可变prevent_pod_scheduling_if_missingpreventPodSchedulingIfMissingboolNone语义默认false可变requires_republishrequiresRepublishboolNone语义默认false可变se_linux_mountseLinuxMountboolNone语义默认false可变service_account_token_in_secretsserviceAccountTokenInSecretsboolNone可变storage_capacitystorageCapacityboolNone≤1.22 不可变现可变token_requeststokenRequestsList[StorageV1TokenRequest]None可变volume_lifecycle_modesvolumeLifecycleModesList[str]None语义默认[Persistent]不可变beta所有字段均可选Optional[...]对应 OpenAPI 定义中每个属性的[optional]标注openapi_types中token_requests的元素类型为List[StorageV1TokenRequest]volume_lifecycle_modes为List[str]。在 swagger.json 中tokenRequests标记为x-kubernetes-list-type: atomic整个列表原子替换而volumeLifecycleModes标记为x-kubernetes-list-type: set无序集合语义。核心字段逐个深入attach_required是否需要 attach 操作当 CSI 驱动实现了 CSIControllerPublishVolume()方法、即需要先挂到节点后再挂到 Pod时应设置attach_requiredTrue。此时 Kubernetes 的 attach/detach 控制器会调用 attach 卷接口先检查volumeattachment状态并等待卷完成 attach再继续执行 mountCSI external-attacher 组件负责与驱动协调并在 attach 完成后更新volumeattachment状态。显式设置为false时跳过 attach 操作。该字段不可变创建后不可修改。fs_group_policy挂载前是否修改卷属主与权限fs_group_policy声明底层卷是否支持在挂载前被修改所有权和权限。该字段在 Kubernetes 1.29 时不可变1.29 起可变。未设置时语义上默认为ReadWriteOnceWithFSType此时 Kubernetes 会逐个卷检查是否应修改属主权限——只有在定义了fstype且卷的访问模式包含ReadWriteOnce时指定的fsGroup才会被应用。node_allocatable_update_period_secondsCSINode 可分配容量刷新周期该整数字段指定驱动对应CSINode可分配容量allocatable.count周期性更新的间隔秒。一旦设置周期性更新与容量相关故障触发的更新都会被启用未设置时两类更新都不会发生allocatable.count保持静态。字段最小允许值为10 秒且依赖MutableCSINodeAllocatableCountfeature gate 开启。该字段可变。pod_info_on_mount挂载时传递 Pod 信息pod_info_on_mountTrue表示驱动在挂载操作中需要额外的 Pod 信息Pod 名称、UID 等。开启后kubelet 会在 CSINodePublishVolume()调用中通过VolumeContext传入以下键值该键列表未来可能扩充但键前缀保持不变csi.storage.k8s.io/pod.namePod 名称csi.storage.k8s.io/pod.namespacePod 命名空间csi.storage.k8s.io/pod.uidstring(pod.UID)csi.storage.k8s.io/ephemeral若卷是由CSIVolumeSource定义的临时内联卷则为true否则为false其中csi.storage.k8s.io/ephemeral是 Kubernetes 1.16 引入的特性仅对同时支持Persistent与Ephemeral两种VolumeLifecycleMode的驱动是必需的。驱动需要自行解析并校验传入的VolumeContext。该字段语义默认false且在 Kubernetes 1.29 时不可变现可变。prevent_pod_scheduling_if_missing节点缺失驱动时阻止调度设置为true时调度器以及内嵌默认调度器的组件如 cluster-autoscaler不会把 Pod 调度到未安装该 CSI 驱动的节点上。对于内嵌调度器并运行调度模拟的组件必须通过CSINode对象感知驱动的注册信息在调度模拟时除创建模拟Node对象外还需创建模拟CSINode对象否则当该字段在CSIDriver上全局开启时任何新加入的节点都可能因缺失驱动信息而被调度器拒绝。这是beta 特性需要启用VolumeLimitScalingfeature gate语义默认false。requires_republish周期性重新调用 NodePublishVolumerequires_republishTrue表示驱动希望 kubelet 周期性地调用NodePublishVolume以反映挂载卷中任何可能的变化例如令牌过期后刷新。注意首次成功的NodePublishVolume调用之后后续调用只应更新卷内容新产生的挂载点不会被运行中的容器看到。该字段默认false。se_linux_mountSELinux-o context挂载选项支持se_linux_mountTrue声明驱动支持-o context挂载选项即驱动必须确保其提供的所有卷可以被不同-o context选项分别挂载典型场景是提供块设备上的文件系统或独立共享卷的存储后端。当 Pod 显式设置了 SELinux context 并挂载ReadWriteOncePod卷时Kubernetes 会以-o contextxyz调用NodeStage/NodePublish未来可能扩展到其他访问模式。无论如何Kubernetes 都会保证卷只以单个 SELinux context 挂载。设置为false时默认Kubernetes 不会向驱动传递任何特殊 SELinux 挂载选项这典型适用于表示更大共享文件系统子目录的卷。service_account_token_in_secrets令牌经 Secrets 字段传递安全加固这是一个 opt-in 字段设置为true时CSI 驱动声明希望 service account 令牌通过NodePublishVolumeRequest的Secrets 字段键csi.storage.k8s.io/serviceAccount.tokens传递而非VolumeContext字段。CSI 规范本就为令牌等敏感信息提供了专用的 Secrets 字段这解决了敏感令牌随卷上下文被记录进日志的安全隐患。驱动必须相应升级为从 Secrets 字段读取令牌。false或未设置时维持既有行为从VolumeContext读取同一键保证向后兼容。关键约束该字段只能在配置了tokenRequests时设置否则 API 服务器会直接拒绝该CSIDriverspec这一点在 kubernetes/docs/V1CSIDriverSpec.md 的属性说明中明确记录。未设置时默认走VolumeContext传递。storage_capacity调度时考虑存储容量storage_capacityTrue表示驱动希望 Pod 调度时考虑其通过创建CSIStorageCapacity对象上报的容量信息。可在部署驱动时立即启用该检查——此时使用延迟绑定late binding的新卷供应会暂停直到驱动发布合适的CSIStorageCapacity对象也可以先以false/未设置部署待容量信息发布后再翻转。该字段在 Kubernetes ≤ 1.22 时不可变之后可变。token_requests需要的 Service Account 令牌规格驱动需要所挂载 Pod 的 service account 令牌以完成必要认证时通过该字段声明请求规格元素为StorageV1TokenRequest模型见 kubernetes/client/models/storage_v1_token_request.py其包含两个属性audience必填str令牌的目标受众对应TokenRequestSpec中的 audience默认取 kube-apiserver 的 audiencesexpiration_seconds可选int令牌有效期与TokenRequestSpec.expirationSeconds默认值一致。kubelet 会把这些令牌放入 CSINodePublishVolume调用的VolumeContext中结构如下csi.storage.k8s.io/serviceAccount.tokens: { audience: { token: token, expirationTimestamp: expiration timestamp in RFC3339, }, ... }约束要点每个TokenRequest的audience必须互不相同且至多允许一个令牌的 audience 为空字符串。令牌过期后如需获取新令牌可配合requires_republish周期性地触发NodePublishVolume。volume_lifecycle_modes支持的卷生命周期模式声明驱动支持的卷类型。列表为空时语义默认Persistent即 CSI 规范定义、经 Kubernetes 常规 PV/PVC 机制实现的用法另一种模式为Ephemeral卷在 Pod spec 内以CSIVolumeSource内联定义其生命周期与 Pod 绑定驱动只会收到对应的NodePublishVolume调用。驱动可支持其中一种或多种未来可能新增更多模式。该字段为beta且不可变。序列化与反序列化属性别名与校验机制V1CSIDriverSpec的每个字段都通过 pydantic 的AliasChoices同时接受两种键名输入见 v1_csi_driver_spec.py例如AliasChoices(attachRequired, attach_required)。配合__preprocess_input_names类方法from_dict既能解析 Kubernetes API 返回的 camelCase JSON如attachRequired也能兼容开发者手写的 snake_case 字典如attach_required二者都会归一化为 Python 属性名。模型配置model_config启用了validate_by_name、validate_by_alias、validate_assignment赋值时即校验与extraforbid拒绝未知字段因此传入未定义字段会直接报错。__eq__/__ne__基于to_dict()结果比较对象相等性。该模型提供完整的方法族kubernetes/docs/V1CSIDriverSpec.md 中的示例同样覆盖了这些用法to_str()返回 pprint 格式化字符串to_json()按线上别名输出 JSON 字符串from_json(json_str)从 JSON 字符串反序列化实例to_dict(serializeFalse)返回 dictserializeFalse时用 Python 属性名snake_caseserializeTrue时用线上别名camelCasefrom_dict(obj)从 dict 反序列化实例其中tokenRequests列表项会逐个调用StorageV1TokenRequest.from_dict()。from kubernetes.client.models.v1_csi_driver_spec import V1CSIDriverSpec # 从 JSON 字符串构建 spec V1CSIDriverSpec.from_json({attachRequired: false, podInfoOnMount: true}) print(spec.to_dict()) # {attach_required: False, pod_info_on_mount: True, ...} print(spec.to_json()) # 输出含 attachRequired / podInfoOnMount 的 JSON # 从 dict 构建同时接受 snake_case 键 spec2 V1CSIDriverSpec.from_dict({ attach_required: False, volume_lifecycle_modes: [Persistent, Ephemeral], }) assert spec2 V1CSIDriverSpec.from_dict(spec2.to_dict())组合使用从 spec 到完整 CSIDriver 对象V1CSIDriverSpec不会单独使用它是 V1CSIDriver 模型 的spec字段类型。V1CSIDriver还包含api_version如storage.k8s.io/v1、kindCSIDriver与metadataV1ObjectMeta。构建完整对象后通过 StorageV1Api 提供的create_csi_driver/read_csi_driver/list_csi_driver/patch_csi_driver/replace_csi_driver/delete_csi_driver等方法操作集群中的CSIDriver资源。以下示例展示如何创建一个声明了多种能力的 CSIDriver同步客户端from kubernetes import client, config from kubernetes.client.models.v1_csi_driver import V1CSIDriver from kubernetes.client.models.v1_csi_driver_spec import V1CSIDriverSpec from kubernetes.client.models.storage_v1_token_request import StorageV1TokenRequest config.load_kube_config() api client.StorageV1Api() spec V1CSIDriverSpec( attach_requiredFalse, # 无需 attach如基于主机路径的驱动 pod_info_on_mountTrue, # NodePublishVolume 时传递 Pod 信息 storage_capacityTrue, # 调度时考虑 CSIStorageCapacity se_linux_mountFalse, requires_republishTrue, # 周期性重新发布卷内容配合令牌刷新 token_requests[StorageV1TokenRequest( # 申请 audience 为 kubelet 的令牌 audiencekubelet, expiration_seconds600, )], volume_lifecycle_modes[Persistent], # 仅支持持久卷默认模式 fs_group_policyReadWriteOnceWithFSType, prevent_pod_scheduling_if_missingFalse, ) driver V1CSIDriver( api_versionstorage.k8s.io/v1, kindCSIDriver, metadataclient.V1ObjectMeta(nameexample.csi.storage.k8s.io), specspec, ) created api.create_csi_driver(bodydriver) print(created.spec.to_dict())create_csi_driver还支持pretty、dry_run如All、field_manager长度小于 128 字符的可打印字符与field_validationIgnore/Warn/Strict等查询参数成功时返回V1CSIDriverHTTP 200/201/202。更新不可变字段如attach_required、volume_lifecycle_modes时服务端会拒绝请求这与字段定义中的 immutable 约束一致。异步aio用法仓库同时提供完整的异步客户端kubernetes.aio其模型与 API 方法位于独立包中kubernetes/aio/client/models/v1_csi_driver_spec.py 与 kubernetes/aio/client/api/storage_v1_api.py。异步 API 方法以async def声明例如async def create_csi_driver(...)其余签名与同步版一致import asyncio from kubernetes import config from kubernetes.aio import client as aio_client async def main(): await aio_client.config.load_kube_config() # 或按需使用 load_incluster_config api aio_client.StorageV1Api() driver aio_client.V1CSIDriver( api_versionstorage.k8s.io/v1, kindCSIDriver, metadataaio_client.V1ObjectMeta(nameexample.csi.storage.k8s.io), specaio_client.V1CSIDriverSpec( attach_requiredFalse, volume_lifecycle_modes[Persistent], ), ) created await api.create_csi_driver(bodydriver) print(created.spec.volume_lifecycle_modes) await api.close() asyncio.run(main())实践建议与注意事项善用不可变约束attach_required与volume_lifecycle_modes不可变创建前必须一次配置正确fs_group_policy、pod_info_on_mount、storage_capacity在较新 Kubernetes≥1.29 / 1.22中可变可后续调整。令牌传递二选一service_account_token_in_secrets必须配合token_requests使用且驱动端需相应升级读取位置若使用旧的VolumeContext传递方式注意敏感令牌可能进入日志。容量感知开启storage_capacity的驱动需持续发布CSIStorageCapacity对象否则延迟绑定的卷供应会暂停等待。特性门控依赖node_allocatable_update_period_seconds依赖MutableCSINodeAllocatableCountprevent_pod_scheduling_if_missing依赖VolumeLimitScaling使用前需确认集群已启用对应 feature gate本文模型基于release-1.37的 scripts/swagger.json 生成。别名兼容由于AliasChoices同时接受 camelCase 与 snake_case且extraforbid拒绝未知字段从 API 响应反序列化时可直接使用V1CSIDriverSpec.from_dict(response[spec])无需手工转换键名。参考资料仓库内文档入口doc/source/kubernetes.aio.client.models.v1_csi_driver_spec.rst模型实现异步/同步kubernetes/aio/client/models/v1_csi_driver_spec.py、kubernetes/client/models/v1_csi_driver_spec.py父对象与依赖模型kubernetes/client/models/v1_csi_driver.py、kubernetes/client/models/storage_v1_token_request.pyAPI 方法同步/异步kubernetes/client/api/storage_v1_api.py、kubernetes/aio/client/api/storage_v1_api.pyMarkdown 版模型文档kubernetes/docs/V1CSIDriverSpec.mdOpenAPI 定义来源scripts/swagger.jsonv1.CSIDriverSpec定义Kubernetes release-1.37赞分享后端云原生容器编排【免费下载链接】pythonOfficial Python client library for kubernetes项目地址https://gitcode.com/gh_mirrors/python1/python点击查看免费下载相关推荐LightDash 数据库层实战指南基于 Knex.js 与 PostgreSQL 的类型安全实体、分页与迁移机制LightDash 数据库层实战指南基于 Knex.js 与 PostgreSQL 的类型安全实体、分页与迁移机制 本文围绕 LightDash 后端 pac后端云原生容器编排鸣潮终极自动化指南3分钟解放双手智能战斗与声骸管理全解析鸣潮终极自动化指南3分钟解放双手智能战斗与声骸管理全解析 还在为《鸣潮》中重复刷副本、做日常任务而感到疲惫吗ok ww是一款专为《鸣潮》玩家设计的后台自动GUI 自动化计算机视觉RPA人工智能Kubernetes 官方 Python 客户端解析ResourceV1ResourceClaim 模型与 DRA 资源声明编程指南Kubernetes 官方 Python 客户端解析ResourceV1ResourceClaim 模型与 DRA 资源声明编程指南 本篇技术指南以 doc/后端云原生容器编排上一篇SillyTavern Launcher 安装与快速上手从零到跑通的完整教程下一篇告别网盘下载慢LinkSwift 网盘直链解析指南三步覆盖九大云盘创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
