Apache Airflow Helm Chart 2.x 开发分支策略与维护指南从 1.2x 到 2.0 的升级路线、Backport 机制与 Kustomize Overlay 实践【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflowApache Airflow 官方 Helm Chart 在main分支上正经历一次面向 2.x 的重大改造清理长期弃用项、将可选功能从核心 Chart 中剥离为可组合的 Kustomize overlay、并为 2.0 大版本发布做准备。本文以仓库中的 dev/README_HELM_CHART2_DEV.md 为核心骨架结合 chart/ 目录下的真实 Chart 配置、.github/workflows/ 中的自动 backport 工作流与 chart/kustomize-overlays/ 中的 overlay 实现系统讲解 2.x 与 1.2x 双分支的开发协议、PR 提交与合并规范、backport 判定标准与工具链以及 Kustomize overlay 的实战用法帮助贡献者与维护者正确选择目标分支、规范提交代码。一、分支格局main承载 2.xchart/v1-2x-test承载 1.2x 维护1.1 三条分支线从 dev/README_HELM_CHART2_DEV.md 的定义看Airflow Helm Chart 采用两条并行的发布线分支用途发布节奏mainAirflow Helm Chart 2.x 的开发分支负责 cleanup、deprecation 与 2.x 发布准备2.x 系列版本从main切出chart/v1-2x-testAirflow Helm Chart 1.2x 系列的稳定维护分支1.2x.x 版本如 1.20.0、1.21.0、1.22.0从该分支切出值得注意的是当前仓库的 chart/Chart.yaml 中version: 2.0.0、appVersion: 3.3.1也就是说仓库内main分支上的 Chart 已经演进到 2.0.0 版本线而 1.2x 系列如 keda overlay 文档中提到的helm-chart/1.21.0、kerberos overlay 的STATUS.yaml中记录的chart-version: 1.22.0则继续在chart/v1-2x-test上以独立节奏维护。1.2 为什么需要分离分支分离分支并非多此一举而是为了给两类工作流解耦1.2x 维护线需要持续合并与最新 1.2x 版本相关的 bug 修复与文档改动不能被 2.x 的重构工作阻塞2.x 准备线需要在main上持续推进清理、弃用与重构不能被必须回移植到 1.2x的负担拖住。这种分离让 1.2x 系列作为通往 2.x 的阶梯版本staircase versions平稳过渡正如文档所言Airflow Helm Chart 1.2x.x 将是 Airflow Helm Chart 2.x 的阶梯版本。二、1.2x.x 与 2.x 的本质差异2.x 不是一次简单的版本号升级。根据文档汇聚到main的重构工作Helm Refurbish包含三大类变化移除长期弃用项在 1.x 系列中一直携带 warning 的 value、模板和行为将在 2.x 中被删除。删除动作发生在main上但在此之前应先在chart/v1-2x-test上以弃用警告而非直接移除的形式落地让 1.2x 用户先得到一个版本的预告期。核心 Chart 瘦身 可 Kustomize 化 overlay如今内置于 Chart 中、靠 feature flag 模板和values.yaml开关控制的众多可选功能将被移出核心 Chart变为独立的 Kustomize overlay。核心 Chart 只保留每个 Airflow 部署都必需的组件可选功能额外集成、可选 sidecar、小众部署形态等由用户通过kustomize在渲染结果之上叠加。这样核心 Chart 更小、更易理解功能通过组合机制而非不断膨胀的values.yaml保留。结构调整与重命名模板布局、value key 重组、会改变行为的默认值等对 1.2x 用户过于破坏性的改动只进入main明确不回移植。提交前的三桶分类法当你在main上提出变更时必须在 PR 描述中先声明它属于哪一类应 cherry-pick 到chart/v1-2x-test的 bug 修复或文档修复以警告形式落到chart/v1-2x-test、以移除形式落到main的弃用项仅限main的重构/overlay 抽取1.2x 用户看不到。三、Helm Chart 2.0 的发布范围文档从 Apache Confluence 的 Release Plan 中摘录了 2.0 的具体范围清单并强调该清单是快照而非最终版More to come...放弃对 Airflow 3.1 的支持2.0 Chart 只面向 Airflow 3.1从而移除当前 Chart 中桥接 Airflow 2.x 与 3.x 的兼容分支。裁掉复杂功能并文档化 Kustomize即上文提到的 overlay 抽取工作Chart 文档将新增 Kustomize 章节说明用户如何把 overlay 组合回来。移除 Chart 内置数据库支持打包在 Chart 里的 PostgreSQL 子 Chart 将被移除对仅需简单开发/测试环境的用户提供一份文档化的简单 PostgreSQL 容器部署配方CI 也改用该配方让 Chart 自身专注于 Airflow。评估将默认 Helm 工具链升级到 4.0。考虑支持单个 Kubernetes namespace 中部署多个 Airflow 实例。判断某功能是否属于 2.0 范围时应以 Release Plan 维基页面为准而不是本文档——文档明确建议在不确定时查阅维基或到 dev list 提问。四、贡献者指南PR 该发到哪个分支4.1 为 2.x 开发为 Airflow Helm Chart 2.x 贡献时PR直接指向main分支即可。4.2 为 1.2x.x 开发chart/v1-2x-test分支严格用于维护、稳定性与兼容性不接受任何新功能或重构只接受与最新 1.2x 版本相关的 bug 修复与文档变更。新功能与重构请一律发往main若维护者判断其与最新版本相关会自行 cherry-pick 到chart/v1-2x-test。同时不会再从chart/v1-2x-test切出任何新的 major 版本。贡献 bug 修复时根据 bug 存在的位置选择目标分支这是文档给出的一套非常实用的决策框架场景 1bug 同时存在于main2.x和chart/v1-2x-test1.2x.x——最常见的情况存在较久的 bug。对main开 PR附带 2.x 的修复与测试为 PR 添加或请维护者添加backport-to-chart/v1-2x-test标签PR 合入main后.github/workflows/automatic-backport.yml 工作流会自动基于cherry-picker工具打开一个针对chart/v1-2x-test的回移植 PR你会在原 PR 的评论里看到链接若 cherry-pick 冲突机器人会把失败的 cherry-pick 留在某个分支并留言此时 committer或你自己需要手动打开针对chart/v1-2x-test的 PR并在描述中提及原mainPR 编号以建立关联。场景 2bug 只存在于chart/v1-2x-test1.2x.xmain上没有——通常是因为有问题的代码在 2.x 重构中已被删除、重写或抽取为 overlay。直接对chart/v1-2x-test开 PR在 PR 描述中简要说明为何该修复不适用于main例如该模板已在 2.x 中随 Kustomize overlay 抽取被移除帮 reviewer 省去交叉核对不要加backport-to-...标签——没有可 forward-port 的内容。场景 3bug 只存在于main2.x不在任何已发布的 1.2x.x 中——通常是重构工作本身引入的回归。对main开普通 bug 修复 PR不加backport 标签。实用技巧如果不确定 bug 属于哪个场景默认按场景 1 处理指向main并添加backport-to-chart/v1-2x-test标签。review 的 committer 若认为无需 backport 会移除标签——这比一开始就纠结成本更低。4.3 标签与核心仓库的对应关系backport-to-chart/v1-2x-test标签是 Airflow 核心仓库backport-to-v3-2-test标签的 Chart 等价物参见 dev/README_AIRFLOW3_DEV.md。automatic-backport.yml工作流是通用的——它剥离任意标签的backport-to-前缀将合并提交 cherry-pick 到同名分支因此该标签已端到端打通无需任何 Chart 专属代码。从 .github/workflows/automatic-backport.yml 的源码可以看到完整机制name: Automatic Backport on: # yamllint disable-line rule:truthy push: branches: - main jobs: get-pr-info: runs-on: ubuntu-slim steps: # 等待 GitHub 将合并提交与 PR 关联约 15 秒延迟 - name: Add delay for GitHub to process PR merge run: sleep 15 - name: Find PR information # 通过 listPullRequestsAssociatedWithCommit 找到 PR # 过滤 labels 中所有以 backport-to- 开头的标签 # 去掉前缀即得到回移植目标分支列表 ... trigger-backport: uses: ./.github/workflows/backport-cli.yml needs: get-pr-info strategy: matrix: branch: ${{ fromJSON(needs.get-pr-info.outputs.branches) }}其中关键点包括合并后先sleep 15秒等待 GitHub API 完成提交与 PR 的关联否则可能查不到刚合并的 PR 导致回移植被跳过随后读取 PR 上所有backport-to-*标签把每个去前缀后的分支名作为回移植目标通过矩阵策略逐一触发 .github/workflows/backport-cli.yml 中的Backport Commit工作流。五、Committer / PMC 合并协议与 Backport 策略5.1 合并面向 2.x 的 PR面向 Airflow Helm Chart 2.x 的 PR 应指向main由 committer 判断是否需要按下一节的政策回移植到chart/v1-2x-test。若需要在合并前添加backport-to-chart/v1-2x-test标签。automatic-backport.yml工作流在 push 到main时触发读取合并 PR 上的标签并自动打开回移植 PR若 cherry-pick 冲突工作流会在原 PR 上留言说明失败原因由 committer 自行解决冲突并打开手动回移植 PR或请原作者代为处理。5.2 什么内容值得回移植到chart/v1-2x-test回移植政策比只回移植 bug 修复更细致文档给出的判定标准如下变更类型是否回移植说明Cleanup / Deprecations按弃用政策选择性回移植1.2x 的每个 minor 版本都会包含一定程度的弃用警告若确认与最新版本相关将警告而非移除回移植到chart/v1-2x-test让 1.2x 用户在功能于 2.x 消失前得到一次预告Bug-fixes仅回移植与最新 Chart 版本相关且易应用的—CI changes大多数回移植保持 bugfix 分支 CI 常绿、工作流与 main 同步Documentation changes仅当与最新 Chart 版本相关且不涉及仅存在于main的功能—活跃区域的 Refactorings不回移植—New features不回移植—抽取为 Kustomize overlay 的功能不回移植在main上把功能从核心 Chart 移除并改为 overlay 交付对 1.2x 用户是破坏性变更这些功能在chart/v1-2x-test上保留在核心 Chart 内直到 2.x5.3 如何用cherry-pickerCLI 回移植 PR回移植的完整 CLI 操作说明见 dev/README.md 中的 How to backport PR with cherry-picker CLI 章节。cherry-picker是由 Python 开发者社区开发的工具既支持命令行也支持通过 GitHub Actions 界面触发。从 .github/workflows/backport-cli.yml 可以看出CI 中安装的版本为cherry-picker2.5.0执行的核心命令是cherry_picker ${COMMIT_SHA} ${TARGET_BRANCH}该工作流同时支持workflow_dispatch手动触发输入 commit-sha 与 target-branch与workflow_call被 automatic-backport 自动调用两种模式。若回移植失败会执行cherry_picker --abort中止并通过 dev/backport/update_backport_status.py 更新回移植状态与 PR 链接。5.4 合并 1.2x.x 的 PR面向 Airflow Chart 1.2x.x 的 PR 应指向chart/v1-2x-test只合并与最新版本相关的 bug 修复和文档变更不合并新功能与重构。六、Milestone 设置规范Airflow Helm Chart 2.0.0 milestone只加到原始 PR 上。指向main分支、涉及 cleanup / deprecation / 准备性工作或重构的 PR应被添加到Airflow Helm Chart 2.0.0milestone。Airflow Helm Chart 1.2x.x milestone只加到原始 PR 上。指向v1-2x-test分支的 PR 应添加到对应的 release milestone如1.20.0、1.21.0等具体版本取决于发布周期与维护者决定。Milestone 的作用与核心仓库一致合并 PR 的 committer 对回移植负责若某些 PR 应被回移植通过设置 milestone 让 release manager 在发布时核对所有预期已回移植的 PR并补上遗漏的 cherry-pick。七、2.x 落地实践Kustomize Overlay 实战Helm Refurbish 最核心的落地成果就是仓库中的 chart/kustomize-overlays/ 目录。该目录在 chart/kustomize-overlays/README.rst 中说明它不随 Chart 发布包分发仅作为源码仓库中的参考用户应直接按与 Chart 版本匹配的 tag 从仓库引用。7.1 Overlay 设计模式standalone additionoverlay 采用独立叠加模式——不修改 Chart 渲染出的任何资源。典型工作流是正常安装 Airflow Chart在自己的kustomization.yaml中引用 overlay并按照 overlay 的 README 做替换release name、namespace、Secret 引用用kubectl apply -k将渲染出的 manifest 应用到 Chart release 所在的 namespace。每个 overlay 目录都带一个STATUS.yaml声明其验证等级tested已在 Apache Airflow CI 中对当前 Chart 版本验证not-tested可以成功构建但无功能性 CI 覆盖仅作为起点参考deprecated计划移除message字段指向替代方案。STATUS.yaml中可选的verify:块声明 overlay 产出的资源及校验方式它是breeze k8s smoke-test-overlay name功能性 smoke test消费的契约。目前仓库提供两个 overlay。7.2 KEDA 自动扩缩容 Overlay状态not-tested PoCchart/kustomize-overlays/keda/ 为 Chart 渲染出的 Celery workers 产出ScaledObjectTriggerAuthentication是 Chart 中workers.celery.keda.enabled的 Kustomize 等价物也是希望保留 Celery 自动扩缩容但不依赖 Chart 侧模板的用户的推荐迁移路径。前置条件集群已安装 KEDAChart 以 CeleryExecutor 安装Chart 的 metadata Secretrelease-airflow-metadata对 KEDA 所在 namespace 可达通常是 Chart release 所在 namespace。产出的资源TriggerAuthentication/airflow-keda-postgres-auth直接从 Chart 的 metadata Secret 读取元数据库连接串ScaledObject/airflow-worker以运行中 排队中的 task instance 数量为指标对 Chart 渲染的 worker Deployment 扩缩容。最小用法示例来自 chart/kustomize-overlays/keda/README.rst# my-overlay/kustomization.yaml apiVersion: kustomize.config.k8s.io/v1beta1 kind: Kustomization namespace: airflow resources: - github.com/apache/airflow/chart/kustomize-overlays/keda?refhelm-chart/1.21.0 replacements: - source: kind: ConfigMap name: airflow-overlay-config fieldPath: data.releaseName targets: - select: kind: ScaledObject name: airflow-worker fieldPaths: - spec.scaleTargetRef.name options: delimiter: - index: 0 - select: kind: TriggerAuthentication name: airflow-keda-postgres-auth fieldPaths: - spec.secretTargetRef.0.name options: delimiter: - index: 0 configMapGenerator: - name: airflow-overlay-config literals: - releaseNameairflow应用方式kubectl apply -k my-overlay/快速测试时也可以直接替换占位符kustomize build chart/kustomize-overlays/keda | \ sed s/RELEASE-NAME/airflow/g | \ kubectl apply -f -调优要点README 中给出的三处常见调整默认查询假设单个名为default的 Celery 队列且worker_concurrency16。若 Chart 中配置不同需编辑 scaledobject.yaml将16替换为config.celery.worker_concurrency的值并将queue IN (default)扩展为workers.celery.queue中的全部队列values.yaml 中逗号分隔此处单引号列出。pgbouncer若启用 pgbouncer 且不想让 KEDA 经它轮询把 triggerauthentication.yaml 中的key从connection改为kedaConnection——Chart 正是为此在该 key 下写入直连 Postgres 的连接串。持久化若 worker 以 StatefulSet 部署workers.celery.persistence.enabledtrue将scaleTargetRef下的kind: Deployment改为kind: StatefulSet。从 Chart 迁移原 Chart 在workers.celery.keda.enabledtrue时渲染名为release-worker的ScaledObjectKEDA 触发器从 worker pod 的KEDA_DB_CONN或AIRFLOW_CONN_AIRFLOW_DBenv var 读取连接串。而该 overlay 的TriggerAuthentication直接从 metadata Secret 读取连接串绕开了 worker pod env var 的间接层因此无需 patch 任何 Chart 渲染的资源。迁移步骤1) 以workers.celery.keda.enabledfalse安装/升级 Chart2) 按上述替换渲染 overlay3) 应用渲染结果4) 用kubectl describe scaledobject airflow-worker -n namespace确认 KEDA 报告 Ready 且 worker 按需伸缩。若之前设置过自定义的pollingInterval、cooldownPeriod、minReplicaCount、maxReplicaCount、advanced或query请先复制进scaledobject.yaml再应用。7.3 Kerberos 测试 KDC Overlay状态testedchart/kustomize-overlays/kerberos/ 在集群内搭建一个一次性的 MIT Kerberos KDC创建airflow/airflow.namespace.svc.cluster.localservice principal并将 keytab 存入名为release-kerberos-keytab的 Secret。它是非 Airflow 组件Kerberos 基础设施以 Kustomize overlay 形式与 Chart 并存的范例产出的 keytab Secret 可直接被 Chart 现有的 kerberos sidecar 消费kerberos.enabledtrue、kerberos.keytab/etc/airflow.keytab、extraSecrets.release-kerberos-keytab: {}。安全警告KDC pod 使用固定 admin 密码且数据库存放在emptyDir中严禁将生产负载接入仅作为测试夹具。关键设计Chart 的 kerberos sidecar 固定挂载名为release-kerberos-keytab的 keytab Secret由 release fullname 经kerberos_keytab_secrethelper 渲染没有任何 Chart value 能指向其他名称的 Secret。该 overlay 恰好产出同名的 Secret因此values.yaml无需任何引用——启用 kerberos 但不设置keytabBase64ContentChart 就不会渲染自己的与之冲突的keytab Secret而是挂载 overlay 创建的这一个。values 片段示例# values.yaml fragment kerberos: enabled: true ccacheMountPath: /var/kerberos-ccache keytabPath: /etc/airflow.keytab principal: airflow/airflow.airflow.svc.cluster.localEXAMPLE.COM workers: celery: kerberosSidecar: enabled: true迁移指南原 Chart 在kerberos.enabledtrue且提供kerberos.keytabBase64Content时渲染承载用户提供 keytab 的 Secret 与用户提供krb5.conf的 ConfigMap用户需自带 KDC。而该 overlay 提供1) 同一 namespace 内可工作的测试 KDC让开发者无需搭建外部 Kerberos 服务即可端到端验证 Chart 的 kerberos sidecar2) 一个自动物化 keytab Secret 的 bootstrap Job避免 base64 blob 进入values.yaml或开发者的 shell 历史。切换步骤1) 按需设置kerberos.enabled安装/升级 Chart但不提供kerberos.keytabBase64Content2) 对同一 namespace 应用 overlay3) 等待Job/release-keytab-bootstrap完成4) 确认 Secret 存在并如上所示从 sidecar 配置引用。验证方式该 overlay 的 STATUS.yaml 声明status: tested、chart-version: 1.22.0verify:块按依赖顺序列出了待校验资源krb5-confConfigMap、kerberos-kdcDeployment/Service、keytab-bootstrapJob、kerberos-keytabSecret行为断言位于 chart/tests/overlay_tests/ 下的test_kerberos.py。本地运行 smoke testbreeze k8s deploy-cluster --rebuild-base-image # 仅首次需要 --rebuild-base-image breeze k8s deploy-airflow breeze k8s smoke-test-overlay kerberos --promote-status八、总结与开发决策速查Airflow Helm Chart 2.x 的开发遵循双线并行、按类分流的原则功能/重构/清理/弃用 →main2.x涉及 1.2x 的 bug 修复与文档 → 指向main并加backport-to-chart/v1-2x-test标签自动回移植或视情况直接指向chart/v1-2x-test新功能、重构、overlay 抽取、仅 main 的结构调整 → 永不回移植弃用项的警告与最新版本相关的 bug 修复、多数 CI 改动、相关文档 → 值得回移植2.0 的范围放弃 Airflow 3.1、核心 Chart 瘦身 Kustomize overlay 化、移除内置数据库、评估 Helm 4.0、考虑多实例支持——具体以 Release Plan 维基为准overlay 落地当前仓库已有 kedanot-tested PoC与 kerberostested两个 overlay采用不修改 Chart 资源的 standalone addition 模式通过STATUS.yaml声明验证等级并可用breeze k8s smoke-test-overlay本地验证。这套分支与回移植协议让 1.2x 用户在升级到 2.x 前获得充分预告同时保证 2.x 的重构不被历史包袱阻塞——理解并遵守它是每一位 Chart 贡献者与维护者的基本功。【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考