Airflow·Cloud Composer API와 외부 연동 플러그인 검토

Cloud Composer와 Airflow를 외부에서 제어할 수 있는 API를 조사했습니다. 같은 Airflow 환경을 다루더라도 Composer 환경을 만들고 조회하는 API와 그 안의 DAG를 실행하는 API는 역할이 달랐습니다.

당시 기록의 Composer 이미지는 composer-1.2.0-airflow-1.9.0이었습니다. 이 글은 그 시점에 확인한 API와 응답을 정리한 것입니다. Airflow 1.x 전체에 실행 상태 조회 기능이 없었다는 의미로 일반화하지는 않습니다.

Cloud Composer 환경 관리 API

먼저 Composer 환경과 장기 실행 작업을 조회했습니다.

환경 조회 응답에는 GKE 클러스터와 DAG 저장 경로, 이미지 버전, Airflow 웹 주소 등이 들어 있었습니다. 다음은 구조를 설명하기 위해 필요한 필드만 남기고 주소를 예시로 바꾼 응답입니다.

{
  "environments": [
    {
      "name": "projects/example-project/locations/us-central1/environments/example-composer",
      "config": {
        "dagGcsPrefix": "gs://example-bucket/dags",
        "softwareConfig": {
          "imageVersion": "composer-1.2.0-airflow-1.9.0"
        },
        "airflowUri": "https://airflow.example.com"
      },
      "state": "RUNNING"
    }
  ]
}

이 응답으로 환경 상태는 확인할 수 있었지만 필요한 DAG 제어 기능을 모두 얻을 수는 없었습니다. 환경의 RUNNING 상태와 개별 DAG의 실행 상태도 다른 정보입니다.

Airflow Experimental API

당시 원문에서 확인한 엔드포인트는 다음 두 가지입니다.

Task 조회 응답에는 Task ID와 재시도, SQL, 트리거 규칙 같은 설정이 있었습니다. 이 Task 정의 응답만으로 특정 실행이 성공했는지 판단할 수는 없습니다.

버전 차이도 중요합니다. 공식 1.10.2 문서에는 DAG Run 조회와 특정 Task Instance 조회가 추가로 설명돼 있습니다. 따라서 당시 조사한 엔드포인트 두 개를 근거로 모든 1.x 버전에 실행 상태 API가 없었다고 설명하면 부정확합니다.

추가 플러그인 검토

필요한 기능을 맞출 수 있는지 외부 REST API 플러그인도 비교했습니다. 원문에는 CLI 출력을 이용하는 방식과 Executor 플러그인 호환성에 대한 검토가 남아 있습니다.

당시 조사는 필요한 제어 기능과 반환 형식을 확인하는 데 집중했습니다. 플러그인별 반환 형식과 실행 환경도 이어서 비교했습니다.

CLI 기반 REST API 플러그인

teamclairvoyant/airflow-rest-api-plugin은 Airflow CLI를 REST 엔드포인트로 제공하는 구성입니다. 당시 기록에는 CLI 결과를 파싱해 보여주는 방식이라 데이터를 외부 서비스에서 활용하기 애매했다고 남아 있습니다.

HTTP로 호출할 수 있다는 점과 결과가 원하는 상태 모델로 제공된다는 점은 다릅니다. 외부 UI에서 실행 상태를 사용할 때는 정상 응답뿐 아니라 CLI의 로그와 오류, 버전별 출력 형식도 고려해야 합니다.

이 검토 결과를 모든 버전에서 오동작한다는 평가로 확대하지는 않습니다. 필요한 반환 형식과 당시 환경에서 사용하기 어려웠던 부분을 정리한 것입니다.

Executor 플러그인 호환성

airflow-plugins/airflow_api_plugin에는 Executor 플러그인을 사용하는 경우 동작하지 않는다는 제약을 기록했습니다. 기본 CeleryExecutor와 별도로 설치하는 Executor 플러그인은 구성이 다르므로, CeleryExecutor 전체에 해당하는 제약으로 볼 수는 없습니다.

연동 전 확인할 항목

당시에는 API 응답 조사와 플러그인 비교를 진행했습니다. 기능 이름을 비교하는 것 외에 결과 형식과 실행 환경까지 확인해야 한다는 점이 남았습니다.

• 필요한 조회와 제어 기능이 있는지
• 반환값에서 상태와 오류를 구분할 수 있는지
• 사용 중인 Executor 구성과 호환되는지
• 설치할 Airflow와 플러그인 버전에서 같은 동작을 제공하는지

CLI를 HTTP로 감싸는 것만으로 모든 외부 연동 조건이 해결되지는 않습니다. 이 항목을 나눠 봐야 어떤 부분을 그대로 사용하고 어떤 처리를 추가할지 정할 수 있습니다.

참고 자료

• Airflow 1.10.2 Experimental REST API 
• teamclairvoyant/airflow-rest-api-plugin 
• airflow-plugins/airflow_api_plugin