Apache Airflow에 기여하고자 할 때 익히면 매우 편한 것이 Breeze입니다.
하지만 Airflow 2.x에서 3.0으로 올라가며 많은 구조적 변화가 있어, 기존에 사용하던 방식으로는 기여 환경을 쉽게 꾸리기 어려웠습니다.
특히 인증 방식이 FastAPI 기반으로 전환되거나, Breeze 명령어 체계가 달라지는 등 문서로는 파악하기 힘든 변화들이 계속 일어났었는데요.
저희 운영진 내부로 진행하고 있는 Airflow 기여 스터디에서도 환경 설정 단계에서 많은 시행착오를 겪고 있습니다. 
이 글에서는 Airflow 3.x 기준 Breeze 설치부터 테스트, 그리고 PR을 위한 사전 작업까지의 전반적인 흐름을 정리해보았습니다.
Breeze 설치
uv tool install -e dev\breeze
Breeze 업그레이드
breeze setup self-upgrade
Breeze 실행
breeze --python 3.10 --backend postgres start-airflow --dev-mode
- Python은 3.10
- backend는 postgres
--dev-mode옵션을 통해 코드 수정을 핫 로드 가능하도록 합니다.
※ 위 옵션들은 필요에 따라 수정 가능합니다.
http://localhost:28080 으로 Airflow UI에 들어가서 admin, admin으로 로그인 해줍니다.
그리고 API 부분을 기여한다면 http://localhost:28080/docs로 Open API에 접근할 수 있습니다.
현재 Airflow의 OpenAPI는 기본적으로 인증이 필요한 상태이며, 대부분 API가 잠겨 있습니다.
인증 없이 요청할 경우 다음과 같은 401 에러가 발생합니다:
{
"detail": "Not authenticated"
}
기존에 FAB 시스템에서는 User를 만들어주고 열어주는 것이 가능했으나, Airflow 3.x부터 인증 방식이 FastAPI 기반으로 변경되었기 때문입니다.
FastAPI 시스템으로 변경되고서는 User를 만들어주는 명령어가 Breeze 내에 없습니다.
AuthManager 확인
Airflow 2.x까지는 Flask AppBuilder(FAB)를 사용했지만, 3.x부터는 FastAPI 기반으로 변경되었습니다. 따라서 현재 AuthManager 설정을 확인하고 필요 시 수정해야 합니다.
airflow config get-value core auth_manager
root@ca1bedaaf611:/opt/airflow# airflow config get-value core auth_manager
airflow.api_fastapi.auth.managers.simple.simple_auth_manager.SimpleAuthManager
그리고 API 부분을 개발할 때, Auth를 패스하고 싶다면 아래의 부분이 기본 값으로는 False로 되어있을 것인데, 인증 우회를 하기 위해 True로 변경해주어야합니다.(권장하는 방식은 아니지만, 개발 중에 인증 방식이 변경되는 부분이 있어서 인증 우회를 해두고 개발하는 편했습니다.)
# airflow-core/src/airflow/config_templates/config.yml
simple_auth_manager_all_admins:
description: |
Whether to disable authentication and allow everyone as admin in the environment.
version_added: 3.0.0
type: string
example: ~
default: "True"
airflow config get-value core simple_auth_manager_all_admins
root@721cd2acc183:/opt/airflow# airflow config get-value core simple_auth_manager_all_admins
False
이 값들은 airflow-core/src/airflow/config_templates/config.yml에서 변경이 가능합니다. (Breeze환경은 이 파일을 이용해 세팅됩니다.)
※ 이 파일의 변경사항은 Git Commit 대상에서 제외합니다.
값을 수정 후 stop_airflow 명령어로 Breeze를 중지해줍니다. 그리고 다시 Breeze를 실행해주는데
만약 수정 후에도 그대로 남아있다면 Breeze 캐시가 남아있는 것일 수 있습니다.
아래의 명령어로 캐시를 제거하고 작업을 진행하시면 됩니다.
breeze doctor
수정 후에 Breeze 환경에서 아래의 값이 True로 변경되었는지 확인합니다.
airflow config get-value core simple_auth_manager_all_admins
root@721cd2acc183:/opt/airflow# airflow config get-value core simple_auth_manager_all_admins
True
이제 Open API로 테스트하면 Auth를 패스하고 정상적으로 잘되는 것을 확인할 수 있습니다.
코드 기여
이제 자신이 작업하고 싶은 부분에서 코드 기여를 진행해줍니다.
저는 API부분을 수정해줬습니다.
기여 후 테스트 코드 작성
airflow-core/tests폴더 안에 테스트 코드가 있습니다. 이곳에서 unit 테스트 코드를 작성합니다.
저는 DAG의 DetailResponse API를 수정했기 때문에 airflow-core/tests/unit/api_fastapi/core_api/routes/public/test_dags.py 의 TestDagDetails 클래스를 수정해주었습니다.
테스트하기
Breeze 안에서 pytest가 가능합니다.
pytest airflow-core/tests/
내가 수정한 파일 정적 체크
breeze static-checks --only-my-changes
Breeze 테스트 관련 내용은 아래의 링크에서 확인가능합니다.
PR을 하기 전 Pre-commit
PR 전에 pre-commit을 반드시 실행해 체크를 통과시켜야 합니다:
pre-commit run --all-files
pre-commit에서 통과되지 못한 항목들이 좀 있을 것인데, 이는 기존 시스템과 충돌 문제 혹은 dependaBot으로 관리되는 것이나 빌드 결과물이 껴있는 경우가 있습니다. 따라서 자신이 수정한 부분에서 잘못된 것이 있는지 로그 확인 및 커밋 전 수정이 필요합니다.
마치며
Airflow 3.x 로의 변경에서 Breeze 세팅 팁이 있다면, 댓글로 알려주세요 