Airflow

Public Interface의 정의와 airflow.sdk로의 전환

Apache Airflow의 Public Interface는 그 변경이 시맨틱 버저닝(semantic versioning)으로 관리되는 인터페이스와 동작들의 집합이다. 사용자는 Dag를 만들고 관리하거나, 태스크와 의존성을 관리하거나, 새로운 executor·플러그인·오퍼레이터·프로바이더를 작성해 Airflow 기능을 확장하는 방식으로 이 Public Interface와 상호작용한다. Public Interface는 커스텀 도구나 다른 시스템과의 통합을 구축하고, Airflow 워크플로의 특정 부분을 자동화하는 데 유용하다.

Dag 작성자와 태스크 실행을 위한 1차 Public Interface는 task SDK, 즉 ``airflow.sdk`` 네임스페이스다(`AIP-72 <https://cwiki.apache.org/confluence/display/AIRFLOW/AIP-72+Task+Execution+Interface+aka+Task+SDK>`_ 에 정의됨). 태스크 코드에서 메타데이터 데이터베이스에 직접 접근하는 것은 더 이상 허용되지 않는다 - 대신 Stable REST API, Python Client, 또는 Task Context 메서드를 사용해야 한다.

``_``나 ``__``로 시작하는 클래스/메서드(각각 protected/private Python 메서드로 불림)는 Public Airflow Interface에 포함되지 않으며 언제든 바뀔 수 있다. 이 문서에 명시적으로 언급된 클래스와 함수만 MAJOR 버전 내에서 하위 호환 시그니처와 동작을 유지하도록 보장된다.

Public Interface의 예로는: 자신만의 오퍼레이터/훅을 작성할 때(필요한 훅/오퍼레이터가 없거나, 있어도 커스터마이징이 필요할 때), Dag 빌딩 블록을 넘어서는 기능을 확장하는 Plugin(Secrets, Timetable, Trigger, Listener 등, 보통 Airflow 인스턴스를 관리하는 사용자가 함)을 작성할 때, 커스텀 Operator/Hook/Plugin을 프로바이더로 묶어 배포할 때, TaskFlow API로 태스크를 작성할 때, Airflow 객체의 일관된 동작에 의존할 때 등이 있다.

Public Interface는 :doc:`Stable REST API <stable-rest-api-ref>`(OpenAPI 명세 기반)를 통해서도 사용할 수 있다. 특정 요구가 있다면 :doc:`Airflow CLI <cli-and-env-variables-ref>`도 쓸 수 있지만, 출력 형식이나 사용 가능한 플래그 같은 세부 동작이 바뀔 수 있으므로 프로그래밍적으로 의존하려면 Stable REST API가 권장된다.

airflow.sdk의 주요 임포트와 Airflow 2.x로부터의 마이그레이션

``airflow.sdk``의 주요 클래스로는 ``Asset``, ``BaseHook``, ``BaseNotifier``, ``BaseOperator``, ``BaseOperatorLink``, ``BaseSensorOperator``, ``Connection``, ``Context``, ``DAG``, ``EdgeModifier``, ``Label``, ``ObjectStoragePath``, ``Param``, ``TaskGroup``, ``Variable``가 있다. 데코레이터/함수로는 ``asset``, ``dag``, ``task``, ``task_group``, ``setup``, ``teardown``, ``result``, ``chain``, ``chain_linear``, ``cross_downstream``, ``get_current_context``, ``get_parsing_context``가 있다.

Airflow 2.x에서 3.x로의 상세한 마이그레이션 방법(임포트 변경과 다른 破괴적 변경 포함)은 마이그레이션 가이드를 참고한다. 사용 가능한 클래스/데코레이터/함수의 전체 목록은 ``airflow.sdk.__all__``에서 확인할 수 있다.

모든 Dag는 내부 Airflow 모듈을 직접 참조하는 대신 ``airflow.sdk``를 쓰도록 임포트를 갱신해야 한다. 레거시 임포트 경로(예: ``airflow.models.dag.DAG``, ``airflow.decorator.task``)는 지원 종료(deprecated) 상태이며 향후 버전에서 제거될 예정이다.

Dags, Operators, Task Instances, Hooks의 공개 범위

Dag는 Airflow의 핵심 엔티티로 반복되는 워크플로를 나타낸다. Dag 파일에서 :class:`~airflow.sdk.DAG` 클래스를 인스턴스화해 만들며, :class:`~airflow.sdk.Param` 클래스로 파라미터를 지정할 수 있다. 권장되는 Dag 생성 방식은 ``airflow.sdk`` 네임스페이스의 :func:`~airflow.sdk.dag` 데코레이터를 쓰는 것이다. :class:`~airflow.models.dagbag.DagBag`은 Airflow가 파일/폴더에서 Dag를 로드하는 데 내부적으로 사용하는 클래스이며, Dag 작성자는 대신 ``airflow.sdk``의 ``DAG`` 클래스를 사용해야 한다. 마찬가지로 :class:`~airflow.models.dagrun.DagRun`도 내부적으로 Dag run 관리에 쓰이며, Dag 작성자는 :func:`~airflow.sdk.get_current_context`를 통한 Task Context나 :class:`~airflow.sdk.types.DagRunProtocol`을 통해 Dag run 정보에 접근해야 한다.

Operators: 기반 클래스인 :class:`~airflow.sdk.BaseOperator`와 :class:`~airflow.sdk.BaseSensorOperator`는 공개(public)이며 새 오퍼레이터를 만들기 위해 확장될 수 있다. 다만 Apache Airflow에 게시된 BaseOperator의 하위 클래스들은 *동작(behavior)* 측면에서는 공개지만 *구조(structure)* 측면에서는 아니다 - 즉 오퍼레이터의 파라미터와 동작은 semver로 관리되지만, 메서드는 언제든 바뀔 수 있다.

Task Instances: Dag(의 Dag Run) 안에서 단일 태스크의 개별 실행을 말한다. :func:`~airflow.sdk.get_current_context`를 통한 Task Context로 접근하며, 직접적인 데이터베이스 접근은 불가능하다. Task Instance Keys는 Dag(Dag Run) 안에서 태스크 인스턴스를 식별하는 고유 식별자로, ``dag_id``, ``task_id``, ``run_id``, ``try_number``, ``map_index``로 구성된 튜플이다. :class:`~airflow.models.taskinstance.TaskInstance` 모델을 통한 직접 접근은 태스크 코드에서 더 이상 허용되지 않으며, 대신 ``get_current_context()``로 얻은 Task Context(``context["ti"]``)의 ``dag_id``, ``task_id``, ``run_id``, ``try_number``, ``map_index`` 속성을 사용해야 한다. :class:`~airflow.models.taskinstancekey.TaskInstanceKey`도 내부적으로만 쓰이는 클래스다.

Hooks: 외부 플랫폼·데이터베이스에 대한 인터페이스로, 가능한 공통 인터페이스를 구현하며 오퍼레이터의 빌딩 블록 역할을 한다. 모든 Hook은 :class:`~airflow.sdk.bases.hook.BaseHook`에서 파생된다. 공개로 취급되는 Hook 집합이 있으며, 자유롭게 확장할 수 있다.