Airflow Docker Compose 快速启动测试实战：Breeze 驱动、手动运行与源码级原理解析

Airflow Docker Compose 快速启动测试实战Breeze 驱动、手动运行与源码级原理解析【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflowApache Airflow 官方文档向用户提供了基于 Docker Compose 的快速启动Quick Start部署方案它允许开发者在几分钟内用docker compose up拉起一套包含 webserver、scheduler、worker、triggerer 等组件的完整 Airflow 环境。为了让这套部署方案始终可用、可复现Airflow 在 CI 中专门运行 Test docker-compose quick start 测试本文基于仓库中的 docker_compose_tests.rst 贡献者文档系统讲解如何用 Breeze 或 pytest 本地运行这套测试、如何保留并调试部署现场并结合 docker-tests 下的真实测试源码剖析这套测试的完整执行链路。读完本文你将掌握 Airflow Docker Compose 部署测试的完整运行方法、关键参数与底层实现细节。一、测试背景与设计动机Airflow 在官方文档中通过 Running Airflow in Docker 向用户推荐 Docker Compose 快速启动方式。为了让文档中展示的这份docker-compose.yaml真正可用而不是停留在纸面上Airflow 项目在 CI 中持续对它进行验证——这就是docker-compose-tests测试组存在的意义。需要特别说明的是该测试不是在 Breeze CI 镜像内部运行的而是在本地 Docker 环境中直接执行的。测试会使用COMPOSE_PROJECT_NAME设置为quick-start以避免与你本机其他正在运行的 docker compose 部署发生命名冲突。从 dev/breeze/src/airflow_breeze/commands/testing_commands_config.py 的测试分组定义可以看到docker-compose-tests被归入 Other Tests 组与system-tests、helm-tests、python-api-client-tests、airflow-e2e-tests并列属于集成验证性质的测试套件。二、测试的工作方式三步走根据原文档描述这套测试的整体流程非常直观共分三步构建 Airflow 生产镜像prod image测试必须以本地已存在的 Airflow 生产镜像为蓝本启动 Docker Compose 部署取出项目自带的docker-compose.yaml用上一步构建的镜像把整套 Airflow 环境拉起来触发示例 DAG 并校验结果通过简单的 DAG 触发测试确认 Airflow 已经正常启动并且能够真正调度、执行一个示例 DAG。从 test_docker_compose_quick_start.py 的源码注释可以看到测试的定位Simple test which reproduce setup docker-compose environment and trigger example dag即复现 docker-compose 环境的搭建并触发示例 DAG——这正是对文档描述的代码级印证。三、运行前置条件在运行 Docker Compose 测试之前需要确认以下环境就绪Docker 引擎已安装并正常运行Docker Compose 可用docker-composev1 独立命令或docker compose插件v2二者之一存在于PATH中。测试代码在 test_docker_compose_quick_start.py 中会先调用docker.compose.version()探测若抛DockerException则直接pytest.fail(docker composenot available. Make sure compose plugin is installed)即缺少 compose 时测试会立即失败并给出明确提示内存充足Airflow 的 Docker Compose 部署包含多个服务请确保 Docker Engine 分配了足够内存官方快速启动文档建议至少 4GB理想 8GB。四、用 Breeze 运行完整测试Breeze 是 Airflow 贡献者使用的开发环境管理工具它将镜像构建与测试执行封装成一条龙命令。运行完整测试只需两条命令breeze prod-image build --python 3.10 breeze testing docker-compose-tests第一条命令构建 Airflow 生产镜像以 Python 3.10 为例第二条命令执行 docker-compose 测试。测试对应的底层实现位于 dev/breeze/src/airflow_breeze/utils/run_tests.py 的run_docker_compose_tests()函数其关键逻辑包括先用docker inspect image_name检查镜像是否存在于本地若不存在会提示 The image ... does not exist locally. It should be build before running docker-compose tests.并交互式询问是否立即构建组装 pytest 命令在docker-tests目录下执行默认追加-s参数以便实时看到测试的 print 输出测试源码也通过rich.console.Console输出大量运行日志通过环境变量把参数传递给测试进程DOCKER_IMAGE指定被测镜像、SKIP_DOCKER_COMPOSE_DELETION控制是否保留部署、AIRFLOW_UID使用当前用户 uid。4.1 测试失败时的日志转储测试过程中如果失败Breeze 会把正在运行的各容器日志转储到控制台随后关闭整个 Docker Compose 部署。在测试源码中这一行为由print_diagnostics()函数实现test_docker_compose_quick_start.py它会依次输出健康检查结果、DAG Run 与 TaskInstance 状态、Docker 与 Docker Compose 版本、compose config渲染结果以及每个服务的名称、状态、配置与完整日志方便定位问题根因。4.2 保留部署以便调试默认情况下测试结束无论成功或失败都会执行compose.down(remove_orphansTrue, volumesTrue, quietTrue)删除部署。如果你需要保留部署现场进行调试有两种方式在 Breeze 命令中传递--skip-docker-compose-deletion标志或者导出环境变量SKIP_DOCKER_COMPOSE_DELETION为true。当该开关生效时测试结束会打印 Skipping docker-compose deletion并输出一条可直接复制的docker compose ...命令前缀方便你继续手动操作这套部署。4.3 容器等待超时控制可以用--wait-for-containers-timeout标志指定容器的最大等待超时时间同时也可以给命令追加-s选项将其透传给底层 pytest以便实时观察测试输出原文档特别注明该行为也可通过WAIT_FOR_CONTAINERS_TIMEOUT环境变量设置。从测试源码看DAG 状态的轮询等待上限为 400 秒for _ in range(400)循环中每秒查询一次--wait-for-containers-timeout正是用来调节这类容器就绪与执行等待窗口的参数。五、手动运行 pytest 测试除了 Breeze你也可以在本地 Python 环境中直接运行 pytestpytest docker_tests/test_docker_compose_quick_start.py手动运行的前提是本地存在一个 Airflow venv且安装了devextra确保python_on_whales、requests、rich等测试依赖可用见 docker-tests/pyproject.toml设置DOCKER_IMAGE环境变量指向你要测试的镜像export DOCKER_IMAGEghcr.io/apache/airflow/main/prod/python3.10:latest该变量在 constants.py 中定义默认值ghcr.io/apache/airflow/main/prod/python3.10:latest——正是breeze prod-image build --python 3.10默认构建出的镜像pytest fixturedefault_docker_image见 conftest.py会优先读取DOCKER_IMAGE未设置时回落为默认镜像。注意手动运行 pytest 时--skip-docker-compose-deletion与--wait-for-containers-timeout这两个开关只能通过环境变量传递即SKIP_DOCKER_COMPOSE_DELETION与WAIT_FOR_CONTAINERS_TIMEOUTBreeze 的命令行标志在纯 pytest 场景下不生效。六、调试保留下来的部署如果你使用了SKIP_DOCKER_COMPOSE_DELETION保留了部署想要用docker compose命令手动查看容器需要先设置项目名与测试保持一致export COMPOSE_PROJECT_NAMEquick-start也可以在 docker compose 命令中显式添加--project-name quick-start。由于测试代码在创建 compose 客户端时指定了compose_project_namebreeze-quick-start见 test_docker_compose_quick_start.py调试时请以实际输出的命令前缀为准。此外测试每次重新运行时会先自动compose.down关闭上一次的部署再启动新部署因此重复执行测试是安全的。七、手动运行 Docker Compose 部署独立于 pytest你还可以完全不经过 pytest手动用刚构建的镜像拉起这套 Docker Compose 环境export AIRFLOW_IMAGE_NAMEghcr.io/apache/airflow/main/prod/python3.10:latest然后按照 Running Airflow in Docker 的指引操作但务必使用仓库源码自带的 compose 文件它位于仓库的airflow-core/docs/howto/docker-compose/docker-compose.yaml测试代码也正是从AIRFLOW_ROOT_PATH / airflow-core / docs / howto / docker-compose / docker-compose.yaml复制该文件到临时目录后启动的。随后即可用常规的docker compose/docker命令调试运行中的实例也可以连接 Airflow 的 Web UI默认localhost:8080手动触发 DAG 做验证。八、源码级剖析测试到底做了什么为了帮助读者深入理解这套测试下面结合源码逐段拆解核心用例test_trigger_dag_and_wait_for_resulttest_docker_compose_quick_start.py准备临时目录用tmp_path_factory.mktemp(airflow-quick-start)创建独立目录把仓库内的docker-compose.yaml复制进去并创建dags、logs、plugins、config四个子目录对应 compose 文件中的卷挂载点写入.env文件内容为AIRFLOW_UID当前用户 uid确保容器内以当前用户身份运行避免文件权限问题compose 文件默认user: ${AIRFLOW_UID:-50000}:0清理旧部署执行compose.down(remove_orphansTrue, volumesTrue, quietTrue)保证测试从干净状态开始启动部署compose.up(detachTrue, waitTrue, ...)拉起整套服务确保 DAG 已解析在airflow-dag-processor服务中执行airflow dags reserialize强制元数据库中的 DAG 序列化数据就绪健康检查调用GET /api/v2/monitor/health断言metadatabase.status healthy触发 DAG先PATCH /api/v2/dags/example_simplest_dag将is_paused置为false再POST /api/v2/dags/example_simplest_dag/dagRuns创建一次 DAG Rundag_run_idtest_dag_run_idlogical_date固定为2020-06-11T18:00:0000:00轮询等待终态wait_for_terminal_dag_state()每秒查询一次 DAG Run 状态最多等待 400 秒直到进入success或failed断言结果最终断言 DAG Run 状态为success否则测试失败并转储全部诊断日志。所有 API 请求都通过api_request()封装test_docker_compose_quick_start.py它先借助tests_common.test_utils.api_client_helpers.generate_access_token获取 JWT 访问令牌再携带Authorization: Bearer token请求/api/v2接口——这恰好验证了 Airflow 3.x 中由 FabAuthManager 负责认证、JWT 签发访问令牌的完整链路compose 文件中也配置了AIRFLOW__CORE__AUTH_MANAGER为 FAB 认证管理器及AIRFLOW__API_AUTH__JWT_SECRET等参数。仓库还包含第二个用例test_airflow_uid_default_in_chowntest_docker_compose_quick_start.py它渲染 compose 配置并断言airflow-init服务初始化命令中的chown参数——当未显式设置AIRFLOW_UID时默认以50000作为用户 IDchown -R 50000:0 /opt/airflow/而不是空用户组写法。该用例守护了 compose 快速启动在默认参数下的文件权限正确性也是文档中AIRFLOW_UID默认值 50000 的代码级证据。九、测试运行的环境变量速查结合原文档与源码整理本测试涉及的全部环境变量与等效 Breeze 开关如下环境变量Breeze 开关默认值作用DOCKER_IMAGE--image-name间接ghcr.io/apache/airflow/main/prod/python3.10:latest被测 Airflow 生产镜像SKIP_DOCKER_COMPOSE_DELETION--skip-docker-compose-deletion未设置即删除测试结束后是否保留部署WAIT_FOR_CONTAINERS_TIMEOUT--wait-for-containers-timeout由 pytest 调用约定容器就绪等待超时COMPOSE_PROJECT_NAME--project-name调试时测试内部固定为breeze-quick-startDocker Compose 项目名避免冲突AIRFLOW_UID—50000容器内运行 Airflow 的用户 IDHOST_PORT—localhost:8080API 服务访问地址见测试源码DOCKER_COMPOSE_HOST_PORTINCLUDE_SUCCESS_OUTPUTS--include-success-outputs未设置成功后是否同样转储诊断输出十、总结Airflow 的 Docker Compose 测试是一套轻量而完整的端到端验证它构建生产镜像、拉起官方文档同款 compose 部署、通过 REST API 触发真实 DAG 并断言执行成功从而保证对外发布的快速启动方案在每次代码变更后依然开箱即用。通过 Breeze 的breeze testing docker-compose-tests或直接运行 test_docker_compose_quick_start.py任何贡献者都可以在本地复现 CI 中的这一验证环节配合SKIP_DOCKER_COMPOSE_DELETION保留现场再结合print_diagnostics转储的服务日志即可高效定位部署或镜像相关问题。关于 Airflow 更广泛的测试体系单元测试、集成测试、系统测试等可进一步阅读 09_testing.rst 测试总览文档。【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考