kube-airflow 故障排查指南：5 个常见问题与解决方案

kube-airflow 故障排查指南：5 个常见问题与解决方案

【免费下载链接】kube-airflowA docker image and kubernetes config files to run Airflow on Kubernetes项目地址: https://gitcode.com/gh_mirrors/ku/kube-airflow

在 Kubernetes 上部署 Airflow 时，kube-airflow 是许多团队的首选方案——它提供了一套完整的 Docker 镜像和 Kubernetes 配置文件，帮你快速搭建包含 webserver、scheduler、Celery worker 和 Flower 的完整 Airflow 集群。然而，Airflow 在 Kubernetes 上的故障排查往往比传统部署更复杂，组件之间依赖 PostgreSQL、RabbitMQ（或 Redis）等多个基础服务，任何一个环节出问题都会让整个调度链停摆。本文总结了 kube-airflow 部署中最常见的 5 个问题，并给出可直接照做的解决方案，帮你快速定位并恢复集群。

问题一：Pod 反复重启，容器一直处于 CrashLoopBackOff

症状：kubectl get pods查看时，webserver、scheduler、worker 等多个 Pod 状态为CrashLoopBackOff或Error，日志里反复出现 "still not reachable, giving up"。

原因：kube-airflow 的启动脚本script/entrypoint.sh会在容器启动时等待 RabbitMQ 和 PostgreSQL 就绪，默认重试 10 次（TRY_LOOP），每次间隔 5 秒。如果依赖服务在 50 秒内仍未就绪，容器就会直接退出，进而触发 Kubernetes 的重启策略，形成循环崩溃。

解决方案：

1. 先用kubectl get pods -n <命名空间>确认 postgres、rabbitmq（或 redis）Pod 是否处于Running状态。
2. 如果基础服务还没就绪，可以在启动时调大重试次数：TRY_LOOP=30，让容器有更多等待时间。
3. 检查 DNS 解析，确保POSTGRES_HOST和RABBITMQ_HOST指向的服务名与airflow/templates/services.yaml中定义的一致。
4. 如果数据库一直起不来，重点排查数据卷：airflow/values.yaml中persistence.enabled开启时，需要确认 PersistentVolume 是否被正确挂载。

问题二：任务一直处于 queued 状态，迟迟不执行

症状：Web UI 中 DAG 已触发，但任务长时间停留在queued，没有任何 worker 接手。

原因：kube-airflow 默认使用 CeleryExecutor（见config/airflow.cfg中的executor = CeleryExecutor），任务要经过 broker（RabbitMQ）分发到 worker。最常见的原因是 broker 连接失败，或 worker 数量配置为 0。

解决方案：

1. 确认 worker Pod 已启动：kube-airflow 用 StatefulSet 管理 worker（见airflow/templates/statefulsets-workers.yaml），检查celery.num_workers是否大于 0。
2. 查看 RabbitMQ 管理界面（端口 15672），确认队列中有没有积压的未消费消息。
3. 检查config/airflow.cfg中的broker_url和celery_result_backend，确保账号密码与POSTGRES_CREDS、RABBITMQ_CREDS环境变量一致。
4. 用kubectl logs <worker-pod>查看 worker 日志，排查是否有 "Can't connect to amqp" 之类的报错。

问题三：DAG 不更新，或运行时突然变成新版本

症状：代码合并到 Git 仓库后，Airflow 里迟迟看不到新 DAG；或者更糟——DAG 正在运行时，执行逻辑突然变成了新代码，导致结果不一致。

原因：kube-airflow 支持通过 git-sync 自动同步 DAG（airflow/values.yaml中dags.git_sync_enabled开启后，entrypoint 会拉取指定 Git 仓库）。但 Airflow 官方已知的问题是：如果 scheduler 在 dagrun 执行中途重载了 DAG，本次运行会直接使用新版本代码，这是非常危险的。

解决方案：

1. 如果业务要求高一致性，建议改用 embedded DAGs 方式：把 DAG 直接打进 Docker 镜像，参考Dockerfile.template中的构建流程，用make build重新构建镜像。
2. 若坚持使用 git-sync，务必遵守两条铁律：DAG 不可变（不要修改已有 DAG，永远新建）；运行中禁止拉取（引入显式锁，dagrun 进行中不更新）。
3. 检查 git-sync 的拉取间隔（dags.poll_interval_sec，默认 60 秒），确认分支名dags.git_branch配置正确。

问题四：Web UI 无法查看 Worker 日志

症状：在 Airflow Web UI 中点击任务日志时报错，提示无法连接到 worker，或日志一直加载不出来。

原因：kube-airflow 的 worker 使用 StatefulSet 而非 Deployment，目的是借助 Headless Service（airflow/templates/services.yaml中的<name>-worker，clusterIP: None）获得稳定的 Pod DNS，让 webserver 能按需访问每个 worker 的日志端口 8793。如果 Headless Service 或 Pod DNS 不通，日志自然无法读取。

解决方案：

1. 确认 worker 暴露了 8793 端口（见airflow/templates/statefulsets-workers.yaml中的containerPort: 8793）。
2. 从 webserver Pod 内测试连通性：kubectl exec <web-pod> -- curl <worker-pod-dns>:8793，worker 的 Pod DNS 形如<release>-worker-0.<release>-worker。
3. 检查是否有网络策略（NetworkPolicy）阻断了 webserver 到 worker 的访问。

问题五：配置解析失败，密码或前缀带特殊字符导致崩溃

症状：容器启动后 airflow.cfg 内容异常，或服务报配置错误，重启多次依旧如此。

原因：kube-airflow 的config/airflow.cfg采用模板占位符机制（如{{ POSTGRES_CREDS }}、{{ FERNET_KEY }}），由script/entrypoint.sh在启动时用sed替换。README 中明确警告：密码和 prefix 中不要使用"、'、/、\等特殊字符，否则 sed 替换会出错，导致配置文件损坏。

解决方案：

1. 检查airflow/values.yaml中配置的密码、url_prefix、flower.url_prefix是否包含特殊字符，一律改为纯字母数字组合。
2. 自定义 airflow.cfg 时，可通过 ConfigMap 方式注入（参考airflow/myvalue-with-airflowcfg-configmap.yaml的示例），注意保留模板占位符，保证与集群中的环境变量对齐。
3. 如果密码已污染数据库连接串，修改后记得重启 postgres、scheduler 和 worker 所有相关组件。

总结与预防建议

kube-airflow 的故障排查思路可以归纳为一条链路：基础服务 → 配置解析 → 任务调度 → 日志回传。绝大多数问题都出在依赖服务未就绪、特殊字符污染配置、以及 DAG 同步策略选择不当这三个环节。

最后给出三条预防建议：一是部署前完整阅读项目根目录的 README 和airflow/Chart.yaml，了解组件清单；二是生产环境优先使用 embedded DAGs 而不是 git-sync；三是为所有密码配置统一的命名规范，坚决不出现特殊字符。做到这三点，你的 Airflow 集群在 Kubernetes 上就能稳定运行很久。

【免费下载链接】kube-airflowA docker image and kubernetes config files to run Airflow on Kubernetes项目地址: https://gitcode.com/gh_mirrors/ku/kube-airflow