后端云原生容器编排【免费下载链接】pythonOfficial Python client library for kubernetes项目地址https://gitcode.com/gh_mirrors/python1/python点击查看免费下载本篇文章基于 Kubernetes 官方 Python 客户端kubernetes包异步模块kubernetes.aio.client中V1CronJob模型及其关联文档展开系统讲解 CronJob 在 Python 客户端中的对象结构、字段语义、序列化行为并结合仓库内真实的 API 方法与示例脚本给出可直接运行的创建、查询、更新、删除完整实战流程。读完本文你将掌握用kubernetes.aio.client操作 CronJob 的全部关键 API、如何构造合法请求体以及如何理解客户端模型与 Kubernetes 服务端 OpenAPI 协议之间的对应关系。一、关联文档与源码定位本文所依据的文档为仓库中的 doc/source/kubernetes.aio.client.models.v1_cron_job.rst该 RST 文件通过 Sphinx 的automodule指令将kubernetes.aio.client.models.v1_cron_job模块的成员members、继承关系show-inheritance以及未文档化成员undoc-members自动渲染为 API 参考页.. automodule:: kubernetes.aio.client.models.v1_cron_job :members: :show-inheritance: :undoc-members:也就是说该文档的技术主体就是v1_cron_job模块本身。对应的核心源码位于 kubernetes/aio/client/models/v1_cron_job.py它由 OpenAPI Generator 根据 Kubernetesrelease-1.37的 OpenAPI 描述见 scripts/swagger.json 与kubernetes/swagger.json.unprocessed生成属于不要手工编辑的生成代码源码头部明确标注Do not edit the class manually.。整个模块定义了与 Kubernetesbatch/v1CronJob 资源一一对应的 Pydantic 数据模型可在同步kubernetes.client.models与异步kubernetes.aio.client.models两个包中分别使用二者结构一致。二、V1CronJob 模型总体结构在 v1_cron_job.py 中V1CronJob继承自pydantic.BaseModel其核心字段声明为class V1CronJob(BaseModel): CronJob represents the configuration of a single cron job. api_version: Optional[StrictStr] Field(defaultNone, validation_aliasAliasChoices(apiVersion, api_version), serialization_aliasapiVersion, ...) kind: Optional[StrictStr] Field(defaultNone, ...) metadata: Optional[V1ObjectMeta] None spec: V1CronJobSpec status: Optional[V1CronJobStatus] None它由五个部分组成与 Kubernetesbatch/v1.CronJob的 JSON 结构一一对应Python 属性JSON 字段alias类型必填含义api_versionapiVersionstr否对象所属的版本化 schema本资源固定为batch/v1kindkindstr否REST 资源类型名固定为CronJobCamelCasemetadatametadataV1ObjectMeta否名称、命名空间、标签、注解等标准元数据specspecV1CronJobSpec是定时任务的调度与执行配置statusstatusV1CronJobStatus否控制器回填的当前运行状态关键点spec是唯一必填字段apiVersion、kind在客户端构造请求体时通常仍要显式给出见下文实战示例服务端会据此校验资源类型。status由 kube-controller-manager 维护客户端一般只读不回填。__properties列表v1_cron_job.py声明了允许的五个顶层属性名[apiVersion, kind, metadata, spec, status]配合model_config中的extraforbidv1_cron_job.py意味着构造模型时传入未知字段会直接报错这能提前拦截拼写错误的字段名避免把错误请求发到集群。2.1 嵌套模型V1CronJobSpecV1CronJobSpec定义在 kubernetes/aio/client/models/v1_cron_job_spec.py其 docstring 说明它描述任务执行的外观以及实际何时运行。字段如下Python 属性JSON 字段类型默认值说明scheduleschedulestr必填无Cron 格式调度表达式见 Wikipedia 的 Cron 说明job_templatejobTemplateV1JobTemplateSpec必填无每次触发时生成的 Job 模板concurrency_policyconcurrencyPolicystrAllow并发执行策略Allow默认允许并发、Forbid禁止并发上次未完成则跳过本次、Replace取消正在运行的 Job 并替换为新 Jobsuspendsuspendboolfalse是否挂起后续执行不影响已经开始执行的实例starting_deadline_secondsstartingDeadlineSecondsint无因故错过调度时间后允许延迟启动 Job 的秒数上限错过的执行会计为失败successful_jobs_history_limitsuccessfulJobsHistoryLimitint3保留的已成功完成 Job 的数量必须是非负整数failed_jobs_history_limitfailedJobsHistoryLimitint1保留的失败 Job 的数量必须是非负整数time_zonetimeZonestrkube-controller-manager 所在时区IANA 时区名tz database 列表。未指定时默认使用控制器进程时区校验与执行阶段分别由 API Server 和 controller-manager 从系统时区库加载若时区名在 CronJob 生命周期内失效控制器会停止创建新 Job 并发出UnknownTimeZone原因的系统事件这里特别值得展开timeZone与concurrencyPolicy的细节timeZone是较新版本引入的能力字段描述明确指出有效时区名与偏移量由 API Server 在 CronJob 校验阶段、controller-manager 在执行阶段从系统级时区数据库加载找不到系统库时会改用捆绑的时区数据库。因此跨时区集群中若要保证每天 8 点这类语义一致应显式设置timeZone而不是依赖控制器的本地时区。concurrencyPolicy三个取值直接决定调度器在上一轮尚未结束、新一轮调度已到时的行为Forbid场景下错过的执行会计为失败Replace则先取消旧 Job。选择时需根据业务是否允许重复执行、是否需要最新一次结果来定。job_template对应的V1JobTemplateSpeckubernetes/aio/client/models/v1_job_template_spec.py仅含两个字段metadata: Optional[V1ObjectMeta]与spec: Optional[V1JobSpec]。也就是说CronJob 的模板本质上就是一份 Job 定义容器、镜像、命令、restartPolicy等都写在jobTemplate.spec.template.spec.containers之下见实战示例这与kubectl create cronjob生成的 YAML 结构完全一致。2.2 嵌套模型V1CronJobStatusV1CronJobStatus定义在 kubernetes/aio/client/models/v1_cron_job_status.pydocstring 为CronJobStatus represents the current state of a cron job只读字段如下Python 属性JSON 字段类型说明activeactiveList[V1ObjectReference]指向当前正在运行的 Job 的对象引用列表last_schedule_timelastScheduleTimedatetime上次成功调度 Job 的时间last_successful_timelastSuccessfulTimedatetime上次 Job 成功完成的时间V1ObjectReference记录了 Job 的kind、namespace、name、uid等定位信息客户端可以通过它构造后续的读取/删除请求。lastScheduleTime与lastSuccessfulTime常被用于监控脚本判断任务是否按预期周期运行。三、模型的双别名机制与序列化行为由 OpenAPI Generator 生成的这套模型在字段访问与 JSON 序列化之间做了两层设计理解它有助于避免踩坑双别名AliasChoices每个字段既接受 PEP 8 风格的下划线命名也接受 Kubernetes 风格的驼峰命名。以concurrency_policy为例构造对象时传concurrency_policyForbid或concurrencyPolicyForbid均可from_dict内部的__preprocess_input_namesv1_cron_job_spec.py会在校验前把concurrency_policy归一化为concurrencyPolicy。V1CronJob.from_dict同样会对apiVersion/api_version做归一化v1_cron_job.py。序列化输出to_dict(serializeTrue)返回使用 wire name驼峰的字典适合直接作为 HTTP 请求体发送to_dict()默认返回 Python 风格键名便于本地调试阅读。to_json()则直接输出 alias 形式的 JSON 字符串v1_cron_job.py。模型配置ConfigDict统一为validate_by_nameTrue、validate_by_aliasTrue、validate_assignmentTrue、extraforbid、protected_namespaces()v1_cron_job.py。含义是字段按名称或别名均参与校验属性赋值时立即校验类型未知字段一律拒绝同时解除 Pydantic 对model_前缀等受保护命名空间的限制避免与model_config等保留名冲突。四、异步 APIBatchV1Api 中的 CronJob 操作V1CronJob模型最终是通过BatchV1Api与集群交互的。异步版本位于 kubernetes/aio/client/api/batch_v1_api.py其中与 CronJob 相关的方法全部以async定义形成一个完整的增删改查矩阵操作方法备注创建create_namespaced_cron_jobbatch_v1_api.py读取read_namespaced_cron_jobbatch_v1_api.py列表list_namespaced_cron_jobbatch_v1_api.py更新全量替换replace_namespaced_cron_jobbatch_v1_api.py局部更新patch_namespaced_cron_jobbatch_v1_api.py删除delete_namespaced_cron_jobbatch_v1_api.py状态子资源读写read_namespaced_cron_job_status/replace_namespaced_cron_job_status/patch_namespaced_cron_job_status操作.status子资源每个方法都有对应的_with_http_info与_without_preload_content变体分别用于获取底层 HTTP 响应详情与原始响应体。以create_namespaced_cron_job为例其签名batch_v1_api.py为async def create_namespaced_cron_job( self, namespace: Annotated[StrictStr, Field(descriptionobject name and auth scope...)], body: V1CronJob, pretty: Annotated[Optional[StrictStr], ...] None, dry_run: Annotated[Optional[StrictStr], ...] None, field_manager: Annotated[Optional[StrictStr], ...] None, field_validation: Annotated[Optional[StrictStr], ...] None, _request_timeout: Union[None, StrictFloat, Tuple[StrictFloat, StrictFloat]] None, _request_auth: Optional[Dict[StrictStr, Any]] None, _content_type: Optional[StrictStr] None, _headers: Optional[Dict[StrictStr, Any]] None, _host_index: Annotated[StrictInt, Field(ge0, le0)] 0, ) - V1CronJob:值得说明的进阶参数dry_runAll执行全部校验与处理流程但不持久化用于提前验证请求体合法性field_manager与 Server-Side Apply 关联的标识字符串≤128 个可打印字符field_validationIgnore静默丢弃未知字段v1.23 前默认、Warn丢弃未知字段但返回警告头v1.23 默认、Strict遇到未知/重复字段直接报BadRequest三档可用于在提交前严格校验请求体_preload_contentFalse对应_without_preload_content变体返回原始 HTTP 响应而不自动解析为模型对象适合需要拿到原始 JSON 或流式响应的场景。五、完整实战用 Python 客户端增删改查 CronJob仓库中的 examples/cronjob_crud.py 提供了可运行的同步版本完整流程创建→删除→再创建→Patch 更新与异步 API 方法一一对应。下面将其拆解为可直接复用的四个步骤。5.1 构造 CronJob 请求体核心是get_cronjob_body函数examples/cronjob_crud.py。它返回一个与V1CronJob字段完全对齐的字典body { apiVersion: batch/v1, kind: CronJob, metadata: { name: name, namespace: namespace }, spec: { schedule: */1 * * * *, # 每分钟触发一次 concurrencyPolicy: Allow, # 允许并发执行 suspend: False, jobTemplate: { spec: { template: { spec: { containers: [ { name: name, image: busybox:1.35, command: command } ], restartPolicy: Never } } } }, successfulJobsHistoryLimit: 3, failedJobsHistoryLimit: 1 } }对照上一节的字段表可以确认schedule与jobTemplate是 spec 中唯二的必填项concurrencyPolicy、suspend、两个*HistoryLimit均为可选并有默认值。容器命令来自调用方传入的列表例如container_command [ /bin/sh, -c, date; echo Hello from the Kubernetes cluster; hostname ]在异步场景下可以把该字典直接喂给V1CronJob.from_dict(...)获得模型实例或直接作为body参数传入客户端内部同样会走from_dict归一化流程。5.2 创建与查询创建前先判断目标 CronJob 是否已存在judge_crontab_existsexamples/cronjob_crud.py避免重复创建随后调用 APIv1 client.BatchV1Api() ret v1.create_namespaced_cron_job( namespacenamespace, bodycronjob_json, prettytrue, _preload_contentFalse) ret_dict json.loads(ret.data)查询使用list_namespaced_cron_jobexamples/cronjob_crud.py返回对象中items数组的每个元素都是V1CronJob或原始 JSON 中的metadata.name可统计数量并据此判断资源是否存在ret v1.list_namespaced_cron_job( namespacenamespace, prettytrue, _preload_contentFalse) cron_job_list json.loads(ret.data) print(fcronjob number{len(cron_job_list[items])})对应的异步写法只需在函数前加async并使用await方法名与参数完全相同见 kubernetes/aio/client/api/batch_v1_api.py例如from kubernetes.aio import client as aio_client v1 aio_client.BatchV1Api() ret await v1.list_namespaced_cron_job(namespacedefault) for item in ret.items: print(item.metadata.name, item.spec.schedule)5.3 更新与删除更新采用 Patch局部替换语义先判断存在再调用patch_namespaced_cron_jobret v1.patch_namespaced_cron_job( namename, namespacenamespace, bodycronjob_json, _preload_contentFalse)示例中通过修改container_command[2]来变更容器执行的命令字符串再重新生成 body 完成一次配置漂移修复式的更新examples/cronjob_crud.py。注意patch_namespaced_cron_job默认以 JSON Patch 语义发送body 中仅需包含要变更的字段若需要整体替换则应使用replace_namespaced_cron_job。删除同样先检查存在性v1 client.BatchV1Api() ret v1.delete_namespaced_cron_job( namename, namespacenamespace, _preload_contentFalse)主流程examples/cronjob_crud.py依次为列出所有 CronJob → 删除旧的hostname→ 等待 2 秒 → 创建新 CronJob → Patch 更新其命令。这个顺序也体现了生产环境中常见的幂等处理模式删除前先确认存在、创建前先查重。六、同步与异步双包结构说明仓库中 CronJob 相关模型同时存在于两个包中同步包kubernetes.client.models.v1_cron_job文档见 doc/source/kubernetes.client.models.v1_cron_job.rstAPI 文档页见 doc/html/kubernetes.client.models.v1_cron_job.html异步包kubernetes.aio.client.models.v1_cron_job即本文主题。两者字段定义完全一致区别仅在于异步包对应的BatchV1Api方法为async且依赖aiohttp见 requirements-asyncio.txt。异步包的全部模块由 kubernetes/aio/client/models/init.py 汇总导出API 文档索引见 doc/source/kubernetes.aio.client.models.rst 与 doc/html/kubernetes.aio.client.models.html。此外V1CronJobList批量列表模型、V1CronJobSpec、V1CronJobStatus也都有独立的 RST 文档页doc/source/kubernetes.aio.client.models.v1_cron_job_list.rst、doc/source/kubernetes.aio.client.models.v1_cron_job_spec.rst、doc/source/kubernetes.aio.client.models.v1_cron_job_status.rst构成完整的 API 参考体系。七、小结V1CronJob是 Kubernetesbatch/v1CronJob 资源在 Python 客户端中的一等公民表达它由V1CronJobSpec调度与执行策略、V1CronJobStatus运行状态、V1ObjectMeta元数据嵌套组合而成并通过 Pydantic 的双别名、严格校验extraforbid与from_dict/to_dict/to_json等便捷方法让Python 字典 ↔ 集群 JSON之间的转换完全透明。配合BatchV1Api的 create/read/list/patch/replace/delete 方法族以及仓库 examples/cronjob_crud.py 提供的完整示例开发者可以快速实现基于 CronJob 的定时任务管理调度表达式与并发策略的正确配置、Job 模板的构造、历史记录上限的调优以及timeZone带来的跨时区调度能力全部都能在数十行代码内落地。赞分享后端云原生容器编排【免费下载链接】pythonOfficial Python client library for kubernetes项目地址https://gitcode.com/gh_mirrors/python1/python点击查看免费下载相关推荐Kubernetes Python 异步客户端 BatchV1Api 完全指南Job 与 CronJob 的增删改查、Watch 与底层实现Kubernetes Python 异步客户端 BatchV1Api 完全指南Job 与 CronJob 的增删改查、Watch 与底层实现 BatchV1A后端云原生容器编排深入解析 Kubernetes Python 异步客户端模型 AdmissionregistrationV1ServiceReference深入解析 Kubernetes Python 异步客户端模型 AdmissionregistrationV1ServiceReference 导读 Admiss后端云原生容器编排Kubernetes Python 客户端 NodeV1Api 异步接口全解析RuntimeClass 的增删改查与 Watch 操作指南Kubernetes Python 客户端 NodeV1Api 异步接口全解析RuntimeClass 的增删改查与 Watch 操作指南 本指南以 Kube后端云原生容器编排上一篇如何在5分钟内快速上手vue-monaco从安装到实现代码高亮的完整教程下一篇提升90%开发效率零门槛前端二维码生成工具实战指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考