Apache Airflow CNCF Kubernetes Provider 版本演进全解析从 1.0.0 到 10.22.0 的架构变迁与关键能力【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflow本指南以 Apache Airflow 仓库中 cncf.kubernetes provider 官方变更日志 为骨架系统梳理该 provider 从 1.0.0 初始版本到 10.22.0 的完整演进脉络。读者将掌握KubernetesPodOperator核心参数如durable、on_finish_action、deferrable的语义变迁、各主要版本的破坏性变更与迁移要点、KubernetesExecutor 的配置项如pod_launch_failure_retries、task_publish_max_retries及运维命令如airflow kubernetes cleanup-pods的用法并理解 XCom sidecar、任务级重试与 Pod 生命周期管理在源码层面的实现逻辑。一、Provider 概览与文档定位apache-airflow-providers-cncf-kubernetes下文简称 cncf.kubernetes是 Apache Airflow 中面向 Kubernetes 生态的核心 provider其当前版本号为10.22.0见 provider.yaml 中维护的版本列表。该 provider 承载了四类核心能力Pod 执行类 OperatorKubernetesPodOperatoroperators/pod.py、KubernetesPodExecOperator、KubernetesJobOperator、KubernetesCreateResourceOperator/KubernetesDeleteResourceOperator、SparkKubernetesOperator等KubernetesExecutor 与 LocalKubernetesExecutorexecutors/kubernetes_executor.py自 7.4.0 起从 Airflow 核心迁移到本 providerHook、Trigger 与 Secret BackendKubernetesHook、AsyncKubernetesHook、KubernetesPodTrigger、Kubernetes Secrets Backend 等CLI 命令如airflow kubernetes cleanup-podscli/kubernetes_command.py。变更日志本身由 release manager 半自动维护是了解该 provider 行为变更、新功能与升级影响的第一手资料。下文按近期版本详解 → 里程碑破坏性变更 → 核心组件演进 → 升级路线四个维度展开。二、近期版本详解10.17.1 ~ 10.22.02.1 10.22.0新增 KubernetesPodExecOperator10.22.0 是本 changelog 记录的最新版本其核心新增是KubernetesPodExecOperator对应 operators/pod_exec.py。该 Operator 面向对已存在的 Kubernetes Pod 执行命令的场景对应 PR #71244区别于KubernetesPodOperator的创建新 Pod 执行任务模型。同时该版本修复了两个与 XCom 相关的问题XCom sidecar 辅助函数不再改动调用方的 Pod volumes#72522此前 sidecar 挂载逻辑会直接修改传入的 Pod 对象导致多任务复用同一 Pod 定义时出现意外副作用当container_logs为字符串时 KubernetesPodOperator 的 XCom 丢失问题#72502。Misc 层面validate_key重构为直接抛出ValueError而非AirflowException#68890provider 内剩余时区导入统一迁移到common.compat.sdk#71209。2.2 10.21.1 与 10.21.0durable 执行惰性化与 cleanup-pods 竞态修复10.21.1 的关键修复是在 Airflow 3.3 以下版本中使 KubernetesPodOperator 的 durable 执行保持惰性#71492。该版本还统一了同步/异步 k8s API 客户端对显式None的_request_timeout处理#69611。10.21.0 有一个直接影响运维行为的重要变更changelog 中的 noteairflow kubernetes cleanup-pods现在接受--min-completed-minutes参数默认值为 1。终态 Pod 不再被立即删除传入--min-completed-minutes 0可恢复旧行为。该延迟修复了一个竞态cleanup 可能在await_pod_completion读取 Pod 最终状态之前就删除了 Pod。在源码 kubernetes_command.py 中可以看到该逻辑min_completed_minutes args.min_completed_minutes清理判定为current_time - _get_pod_completion_time(pod) timedelta(minutesmin_completed_minutes)。也就是说只有完成时间距今超过设定分钟数的 Pod 才会被清理。该版本还引入了 KubernetesExecutor 的可选的并发 Pod 创建#68480并修复了 deferrable 模式下 KubernetesPodOperator 日志解析阻塞 triggerer 事件循环的问题#69661、dry_run 模式仍需要真实 API client 的问题#70234。2.3 10.20.0pod_launch_failure_retries 与 durable 参数登场10.20.0 是本 changelog 中行为变更最密集的版本之一包含两条重要 note其一KubernetesExecutor 的 Pod 启动失败透明重排requeue机制。当 worker Pod 在任务进程启动之前失败如节点排空、autoscaler 缩容、节点启动竞态、镜像拉取瞬时失败等Executor 不再在首次 Pod 失败时直接标记任务失败而是透明地重新入队。该行为由新增配置项控制配置项默认值说明[kubernetes_executor] pod_launch_failure_retries1透明重排次数0恢复立即失败旧行为-1表示无限重试需谨慎若 Pod 每次启动都失败在delete_worker_pods_on_failure False默认值下失败 Pod 不会被清理而持续累积[kubernetes_executor] pod_launch_failure_excluded_container_reasonsError逗号分隔的容器终止原因列表命中这些原因的 Pod 不进入重排路径改走正常任务重试上述两个配置项在 get_provider_info.py 中有完整定义version_added: 10.20.0在 kubernetes_executor.py 中通过conf.getint(kubernetes_executor, pod_launch_failure_retries, fallback1)读取。关键语义重排不消耗任务级重试次数因为此时任务实例仍处于queued状态、尚未执行任何任务代码。其二reattach_on_restart被durable参数取代。变更日志明确说明durable与reattach_on_restart语义相同默认值同为True在 Airflow 3.3 上仍传入reattach_on_restart会继续生效且优先级更高但会触发AirflowProviderDeprecationWarning未来版本将移除——建议在 DAG包括default_args中改用durableAirflow 3.3 上的重连机制本身也变了Operator 不再按 label 搜索 Pod而是使用持久化在 task state store 中的 Pod 身份pod_identifier重连消除了多个匹配 Pod 时的歧义失败旧版 Airflow 仍保持 label 搜索行为。源码 pod.py 中定义了POD_IDENTIFIER_STATE_KEY pod_identifier并注释说明在已部署的 Operator 上重命名该 key 会破坏进行中的重试因为旧 key 已存储。同时类属性__supports_durable_execution: ClassVar[bool] True表明该 Operator 原生支持 durable 执行通过 task_state_store 在重试时重连而非重新提交。10.20.0 的其他特性还包括KubernetesExecutor 的流式任务日志支持#69300、running_pod_log_lines配置项#69301、XCom sidecar 容器的 security context 可配置#69613。2.4 10.19.0 与 10.18.0稳定化与延迟模式完善10.19.0 聚焦修复KubernetesExecutor 读取运行中任务日志时的 Manager 进程泄漏#68800、completed-pod adoption 集合永不排空#68674、in-cluster 下 cncf.kubernetes 模型反序列化的可 pickle 性#68848以及先执行await_pod_start再await_init_containers_completion以修复流式 init-container 日志时的挂起#68450。10.18.0 的亮点是deferrable KubernetesPodOperator 强制执行execution_timeout#67229并修复了 KubernetesExecutor completed-pod adoption 导致 scheduler 崩溃循环的问题#67850、KubernetesJobOperator的监控 Pod 泄漏#67333以及 mapped TI 上KubernetesPodTrigger.get_task_state的 KeyError#67296。2.5 10.17.1XCom sidecar 默认镜像固定为 alpine:3.2310.17.1 有一条对部署和 CI 影响直接的重要 note默认 xcom-sidecar 镜像现在固定为alpine:3.23。此前KubernetesPodOperator在do_xcom_pushTrue时使用的默认 sidecar 镜像是未固定的alpine解析为alpine:latest。固定后kubelet 的默认imagePullPolicy由Always变为IfNotPresent节点上已缓存镜像时不会在每次任务执行时重复拉取——从而保护部署和 CI 免受 Docker Hub 匿名拉取速率限制。影响面与对策通过xcom_sidecar_container_image参数或[kubernetes] xcom_sidecar_container_image配置显式覆盖镜像的部署不受影响依赖未固定默认值的部署将被固定到alpine:3.23直到下次升级如需其他 alpine 版本、私有镜像源或其他基础镜像请显式设置xcom_sidecar_container_image。该版本还修复了 deferrable 模式下 Pod 在 re-entry 前被 GC 时的 crash#66716、Pod API 调用的延迟与状态指标#66806以及将 Pod 清理从 trigger 的cleanup()调整到on_kill()的相关逻辑10.17.0 特性 #65741。三、里程碑版本的破坏性变更升级必读3.1 10.0.0大规模移除弃用特性10.0.0 是清理式大版本changelog 用两个 warning 块列出全部移除项可归为四类Helpers移除add_pod_suffix改用add_unique_suffix、make_unique_pod_id改用add_unique_suffix、create_pod_id改用create_unique_id、gen_pod、add_xcom_sidecar改用airflow.providers.cncf.kubernetes.utils.xcom_sidecar.add_xcom_sidecarPodGenerator.from_obj不再接受 dict 形式的 executor_config移除from_legacy_obj与整个pod_launcher_deprecated模块改用 utils/pod_manager.pyOperatorsoperators.kubernetes_pod模块移除改用 operators/pod.py移除is_delete_operator_pod参数改用on_finish_action、progress_callback参数改用callbacks、execute_complete方法改用trigger_reentrySparkKubernetesOperator的xcom_push参数移除改用do_xcom_pushTriggersKubernetesPodTrigger.should_delete_pod参数移除改用on_finish_actionUtilsPodManager.progress_callback移除、follow_container_logs移除改用fetch_container_logs。另一条破坏性变更task.kubernetes装饰器的namespace默认值改为None——当in_clusterTrue时使用集群命名空间因此使用该装饰器时必须显式指定 namespace如需保持旧行为设置namespacedefault。3.2 9.0.0 与 8.0.0Pod 识别与配额错误重试策略9.0.0移除了通过 execution_date 识别 Pod的能力该能力原用于 Airflow 1 向 2 的升级场景。变更日志警告Airflow 1 发起的任务可能因此启动重复 Pod但只会有一个任务 Pod 成功。8.0.0针对 Kube API 配额超限quota exceeded错误引入task_publish_max_retries标志默认行为由无限重试改为 0不重试-1表示无限重试任意正整数表示固定次数。该配置项的定义见 get_provider_info.py用于因配额错误入队失败时、标记任务失败前的最多重试次数。3.3 7.4.0KubernetesExecutor 迁入 provider7.4.0 是架构里程碑KubernetesExecutor 与 LocalKubernetesExecutor 从核心apache-airflow包迁移到 cncf.kubernetes provider 包#32767。自此使用 KubernetesExecutor 必须安装本 provider。同期还引入了 [AIP-51] 执行器 CLI 命令分发机制#29055和termination_message_policy参数#32885。3.4 5.0.0彻底脱离 Airflow 核心配置5.0.0 完成了一次解耦KubernetesPodOperator不再读取 Airflow 配置kubernetes段的设置4.1.0 起已弃用本版本移除。如需非默认的客户端配置必须在 Airflow Connection 中定义并通过kubernetes_conn_id让 KPO 使用不再支持以 dict 形式提供resource应使用container_resourcesV1ResourceRequirements移除node_selectors参数改用node_selector移除airflow.kubernetes.backcompat.*四个兼容模块必须改用 kubernetes 库原生对象。功能层面5.0.0 起name与namespace变为可选name缺省时使用task_idnamespace的解析顺序为 KPO 参数/pod 模板 → Airflow connection → 集群内自动推断 →default。Connection 的 extra 字段不再强制extra__kubernetes__前缀。3.5 4.0.0 与 3.0.0Airflow 版本门槛与 PodLauncher 重构4.0.0起 provider 仅支持Airflow 2.3原因是依赖了比 Airflow 2.1/2.2 更新的 kubernetes 库版本3.0.0是一次内部大重构is_delete_operator_pod默认值由False改为True任务结束后默认删除 Pod避免集群中 Pod 无限累积PodLauncher更名为PodManagerPodStatus枚举更名为PodPhase值不再小写化执行流程被拆分为两个阶段get_or_create_pod先按 TI 专属 label 用find_pod查找找不到则create_pod与等待完成阶段await_pod_start→follow_container_logs/await_container_completion→ 提取 XCom →await_pod_completionhandle_pod_overlap、create_new_pod_for_operator等方法被移除start_pod拆分为create_pod与await_pod_startmonitor_pod拆分为三个等待方法pod_mutation_hook的调用点从PodManager.run_pod_async移到KubernetesPodOperator.build_pod_request_obj。3.6 2.0.0、1.0.0 与 YANKED 版本2.0.0因移除apply_default装饰器要求Airflow 2.1.0新增pod_template_file的 Jinja 模板支持#15942与将 pod 名称写入 XCom#157551.0.0为 provider 初始版本值得注意的教训3.1.2 / 3.1.1 / 3.1.0 / 3.0.2 / 3.0.1 五个版本均被 yank原因是在 Airflow 2.1、2.2 上允许安装不受支持的 kubernetes 库 11.0.0。changelog 以.. warning::明确标注了 yank 原因升级时应跳过这些版本。四、核心组件能力演进时间线4.1 KubernetesPodOperator 参数演进源码佐证operators/pod.py 中__init__的完整签名印证了 changelog 中的演进结果当前版本的关键参数包括参数默认值语义要点kubernetes_conn_idKubernetesHook.default_conn_name即kubernetes_default自 6.0.0 起默认使用kubernetes_defaultconnection7.0.0 起若该 connection 不存在行为等同于conn_idNone缓解 6.0.0 的破坏性变更durable/reattach_on_restartTrue10.20.0 起以durable为准3.3重连基于 task state store 中的 pod 身份on_finish_actiondelete_pod可选delete_pod/delete_succeeded_pod/keep_pod/delete_active_pod后者 10.12.0 新增on_kill_actiondelete_pod任务被用户 kill 时的清理策略10.15.0 补充cancel_on_kill支持deferrable读取[operators] default_deferrable默认False5.2.0 引入 deferrable 模式10.18.0 起强制执行execution_timeoutstartup_timeout_seconds/startup_check_interval_seconds/schedule_timeout_seconds120/5/None10.5.0 起区分调度超时与启动超时get_logs/container_logs/init_container_logsTrue/ base /None7.3.0 起支持多容器日志8.0.0 起logging_interval支持周期性地记录容器日志do_xcom_pushFalse推送/airflow/xcom/return.json内容依赖 xcom sidecar默认镜像alpine:3.23见 10.17.1base_container_nameNone类常量base4.0.0 起进入template_fields可被模板化skip_on_exit_codeNone6.1.0 起支持多退出码集合判定 skippedcallbacksNone7.14.0 起支持通用回调类10.2.0 支持多个回调同时template_fieldspod.py已扩展至 21 个字段包括image、name、namespace、env_vars、volumes、volume_mounts、node_selector、config_file、cluster_context、kubernetes_conn_id、container_resources、trigger_kwargs等体现了多年间可模板化字段持续扩充的演进主线如 2.2.0 的namespace、5.0.0 的container_resources、7.13.0 的config_file、9.0.1 的kubernetes_conn_id与node_selector。4.2 Deferrable延迟执行模式的完善deferrable 模式是本 provider 近几版的重头戏演进脉络清晰5.2.0KubernetesPodOperator引入 deferrable 模式#290178.1.0KubernetesJobOperator实现 deferrable 模式#38251并新增wait_until_job_complete参数#3799810.10.0KubernetesPodTriggerer直接读取 Pod 日志而非由 Operator 读取#57531并统一了 KPO 与 Triggerer 的 Pod 启动追踪逻辑#5687510.9.0新增 deferrable 回调#4710810.18.0deferrable 模式强制执行execution_timeout#67229期间持续修复 deferrable 路径下的日志阻塞10.21.0 #69661、Pod 被 GC10.17.1 #66716、mapped TI KeyError10.18.0 #67296等问题。4.3 task.kubernetes 装饰器与 KubernetesJobOperator 家族task.kubernetes装饰器decorators/kubernetes.py自 4.4.0 引入5.2.1 修复其输入输出传递10.0.0 调整namespace默认值语义task.kubernetes_cmd于 10.5.0 引入#4691310.12.0 修复其在TaskGroup.expand下 mapping 的模板化问题#59292KubernetesJobOperator 家族自 8.0.0 起建立KubernetesJobOperator、KubernetesDeleteJobOperator、KubernetesPatchJobOperator、GKE 系列 Job 操作符10.15.0 起禁止parallelism0与wait_until_job_completeTrue的组合此前会造成永不完成的 Job 并无限失败任务10.12.1 起支持parallelism0在wait_until_job_completeFalse场景如一次性清理任务SparkKubernetesOperatoroperators/spark_kubernetes.py自 7.14.0 起基于 CRD 实现#22253并持续增强driver/executor Pod 标签、reattach_on_restart的上下文标签8.0.1 前、spark 名称规范化10.11.0 #58391、防止重复 Pod10.12.4 #61110等。4.4 XCom sidecar 机制XCom sidecar 是本 provider 最复杂也最常出问题的子系统之一实现见 utils/xcom_sidecar.pychangelog 中相关修复贯穿多个版本6.0.0 允许设置 XCom 容器资源限制#281254.3.0 修复 xcom_sidecar 卡死#249934.4.0 等待 sidecar 容器启动后再执行 exec#2505510.6.0 增加 sidecar 终止检测#5114410.12.1 在读取 XCom 前检查 sidecar 是否在运行#6031910.17.1 固定默认镜像alpine:3.23详见 2.5 节10.20.0 允许配置 sidecar 容器 security context#6961310.22.0 修复 sidecar 辅助函数改动调用方 Pod volumes 的问题#72522。五、运维与配置要点汇总5.1 CLIairflow kubernetes cleanup-pods10.21.0 起新增--min-completed-minutes默认1终态 Pod 延迟清理避免与await_pod_completion的读取竞态传0恢复立即清理10.17.1 修复其忽略--verbose的问题#659558.3.0 将 Kubernetes CLI 整体迁移到 provider 包#39587。5.2 Executor 配置项[kubernetes_executor] 段配置项默认值引入版本用途pod_launch_failure_retries110.20.0启动前失败的 worker Pod 透明重排次数不消耗任务级重试pod_launch_failure_excluded_container_reasonsError10.20.0命中即走正常任务重试的容器终止原因列表task_publish_max_retries08.0.0Kube API 配额错误入队失败的最大重试次数-1无限delete_worker_pods_on_failureFalse—失败 worker Pod 是否删除与无限重排组合时需注意累积running_pod_log_lines—10.20.0运行中 Pod 的日志行数配置另注意 10.14.0 起 KubernetesExecutor 支持 multi-team#6179810.19.0 起指标带team_name标签#69046。5.3 连接与安全6.0.0 起 KPO 默认使用kubernetes_defaultconnection7.0.0 起连接缺失时等同于conn_idNone5.0.0 起 connection extra 字段不再强制extra__kubernetes__前缀前缀与非前缀字段冲突时采用非前缀值10.13.0 新增Kubernetes Secrets Backend#61527文档见 secrets-backends/kubernetes-secrets-backend.rst10.17.0 支持多 team 查找#6569410.5.0 为KubernetesHook新增test_connection方法#47881。六、升级建议与查阅指引基于 changelog 的版本纪律升级 cncf.kubernetes provider 时建议按以下清单核对确认 Airflow 版本门槛1.0.0 无门槛 → 2.0.0 要求 2.1 → 4.0.0 要求 2.3 → 8.4.0 要求 2.8 → 10.5.0 要求 2.10 → 10.11.0 要求 2.11。provider 官方支持策略详见仓库根目录 PROVIDERS.rst跳过 yanked 版本3.1.2 / 3.1.1 / 3.1.0 / 3.0.2 / 3.0.1检查弃用参数is_delete_operator_pod→on_finish_action、progress_callback→callbacks、reattach_on_restart→durable、xcom_push→do_xcom_push、node_selectors→node_selector、resource(dict)→container_resources核对行为默认值变更Pod 默认删除3.0.0、task_publish_max_retries08.0.0、启动失败重排 1 次10.20.0、xcom sidecar 镜像固定alpine:3.2310.17.1、cleanup 延迟 1 分钟10.21.0若子类化 KubernetesPodOperator关注 3.0.0 的方法重构get_or_create_pod、await_pod_start、await_container_completion、await_pod_completion、build_pod_request_obj与 10.0.0 的模块迁移。若需更深入的使用细节可继续阅读本 provider 的 operators.rstOperator 用法与参数指南、kubernetes_executor.rstExecutor 配置、connections/kubernetes.rstConnection 定义、kubernetes_rbac.rstRBAC 权限10.21.0 起补充文档以及单元测试tests/unit/cncf/kubernetes与系统测试tests/system/cncf/kubernetes来验证各版本行为。七、结语从 1.0.0 到 10.22.0cncf.kubernetes provider 的演进主线清晰可辨执行模型上从单一KubernetesPodOperator走向 Pod/Job/Spark/Kueue/Resource 全家桶可靠性上围绕 deferrable 模式、durable 重连、Pod 启动失败重排、清理竞态持续加固边界上彻底解耦 Airflow 核心配置、全面收敛弃用 API。这份 changelog 既是升级手册也是理解 Kubernetes 任务执行在 Airflow 中如何被一步步打磨为生产级能力的绝佳样本。【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考