Airflow

airflow.security.permissions 폐기 배경

Airflow 3 릴리스 이후 Flask AppBuilder(FAB) 프로바이더는 더 이상 core Airflow 의존성이 아니다(AIP-79: Flask AppBuilder를 core 의존성에서 제거). 다만 FAB Auth Manager 전용으로 설계된 일부 모듈은 하위 호환을 위해 core 배포판에 그대로 남아 있으며, 그중 하나가 airflow.security.permissions다. 이 모듈은 Airflow 4에서 제거될 예정이다.

이 폐기가 실제로 영향을 미치는 경우는 두 가지다: 커스텀 RBAC 역할 정의를 위해 airflow.security.permissions에 의존하는 배포, 또는 커스텀 auth manager 로직 등 이 모듈에 의존하는 다른 커스텀 로직이 있는 배포. 반대로 수정되지 않은 FAB Auth Manager를 커스텀 역할 정의 없이 그대로 쓰거나, Simple Auth Manager나 다른 프로바이더 auth manager를 이 모듈에 의존하는 커스텀 코드 없이 쓰는 경우에는 이 폐기가 영향을 주지 않는다.

새 권한 표준으로의 마이그레이션

폐기된 모듈의 구성요소는 다음과 같이 새 표준으로 대체된다: airflow.security.permissions.ACTION_*는 airflow.api_fastapi.auth.managers.base_auth_manager.ResourceMethod로, airflow.security.permissions.RESOURCE_*는 airflow.api_fastapi.auth.managers.models.resource_details로 대체된다. 폐기된 모듈에 의존하는 커스텀 auth manager를 유지보수한다면, ResourceMethod와 resource_details 컴포넌트를 어떻게 활용할지 참고할 예시로 SimpleAuthManager의 소스 코드를 살펴볼 것을 권장한다. 커스텀 역할 정의에 의존하는 경우에는 사용 중인 auth manager의 문서를 참고해야 한다.

한편 DAG.access_control은 이들과 성격이 다르다 — 대체할 드롭인 컴포넌트가 없다. 이는 그 자체로 하나의 인가 메커니즘이 아니라 FAB auth manager에 대한 입력값이었다: DAG 파싱 시점에 그 내용이 FAB의 권한 테이블로 확장되고, 이후 인가는 DAG 인자가 아니라 그 권한 테이블을 읽어 이루어졌다.

DAG.access_control은 FAB 외 auth manager에서 조용히 무력화된다

공식 문서는 이 지점을 경고로 강조한다: Airflow는 설정된 auth manager가 FAB Auth Manager일 때만 DAG.access_control을 읽는다. 다른 어떤 auth manager 하에서도 이 인자는 파싱되고 직렬화될 뿐 인가 판단에 전혀 참조되지 않으므로, 권한을 부여하지도 거부하지도 않는다. FAB에서 다른 auth manager로 옮겨가면서 Dag에 access_control을 그대로 남겨둔 배포는 그 권한 부여가 에러 없이 조용히 더 이상 적용되지 않는 상태가 된다.

이는 실무에서 놓치기 쉬운 보안 회귀(regression) 위험이다 — 마이그레이션 후에도 코드상 access_control이 그대로 남아 있으면 여전히 작동한다고 착각하기 쉽지만 실제로는 아무 효과가 없다. 마이그레이션 시에는 그 권한 부여 내용을 새 auth manager가 참조하는 정책 소스로 직접 옮겨야 한다.

API 엔드포인트 권한 참조표 읽는 법

api_permissions_ref.rst는 stable REST API(/api/v2)의 모든 엔드포인트에 필요한 권한을 정리한 자동 생성 문서다. scripts/ci/prek/extract_permissions.py 스크립트가 소스 코드에서 직접 추출해 생성하며, prek run generate-api-permissions-doc 훅으로 재생성되므로 수동으로 편집해서는 안 된다. 각 행은 Method(HTTP 메서드), Endpoint path, Resource, Required permission 네 열로 구성된다.

Resource 열에는 DAG, DAG.RUN, DAG.TASK_INSTANCE, DAG.XCOM, DAG.CODE, DAG.WARNING, DAG.VERSION, DAG.HITL_DETAIL, DAG.TASK_LOGS, DAG.AUDIT_LOG처럼 점(.)으로 하위 범위를 표시하는 DAG 계열 리소스와, Connection/Variable/Pool/Asset/AssetAlias/Configuration 같은 독립 리소스, 그리고 View.IMPORT_ERRORS/View.JOBS/View.PLUGINS/View.PROVIDERS처럼 특정 객체가 아니라 읽기 전용 시스템 정보 페이지에 대응하는 singleton View.* 리소스가 함께 나타난다.

Method와 Required permission은 대개 GET→GET, POST→POST, DELETE→DELETE로 일치하지만, PATCH 메서드는 대체로 PUT 권한에 매핑된다(수정 작업이므로). 여러 항목을 한 번에 다루는 벌크 엔드포인트(bulk_variables류)는 Required permission이 multi로 표기된다. /auth/login, /auth/logout, /monitor/health, /version, POST /connections/enqueue-test처럼 Resource가 Public으로 표기된 엔드포인트는 Airflow 권한이 전혀 필요 없다.

일부 엔드포인트는 표에 두 번 나타나는데, 이는 하나의 엔드포인트가 서로 다른 두 리소스에 대한 권한을 동시에 요구하기 때문이다. 예를 들어 자산의 큐 이벤트를 삭제하는 DELETE /assets/{asset_id}/queuedEvents는 Asset에 대한 DELETE 권한과 DAG에 대한 PUT 권한을 모두 요구한다 — 자산 이벤트 삭제가 DAG 범위의 상태에도 영향을 주기 때문으로 볼 수 있다. 또한 GET /eventLogs(감사 로그 조회)에 필요한 권한은 이 표에서 DAG.AUDIT_LOG로 표기되는데, 이는 새 auth manager 체계의 리소스 명명 규칙이며 audit_logs.rst에서 언급된 FAB 시절의 권한명인 "Audit Logs.can_read"와는 이름이 다르다 — 앞서 다룬 RESOURCE_*/ACTION_* → resource_details/ResourceMethod 마이그레이션이 실제로 리소스 명명에 반영된 사례로 볼 수 있다.