Airflow 설치부터 Docker Compose 연결: 문제 정리

Airflow를 처음 세팅하면서 단순히 “설치만 하면 되겠지”라고 생각했지만,
실제로는 의존성 관리, Provider 설치 방식, Docker 네트워크 구조까지 함께 이해하지 않으면 여러 문제를 마주치게 된다.
이번 글에서는 Airflow 환경을 구성하며 직접 겪었던 문제와, 그 과정에서 정리한 핵심 개념들을 기록해본다.

 

1. Airflow 설치 시 Constraints 파일이 중요한 이유

Airflow는 단순한 Python 패키지가 아니다.
Airflow는 Python 버전에 따라 의존 라이브러리 조합이 달라지며, 이 조합이 조금만 어긋나도 실행 중 에러가 발생하기 쉽다.

그래서 Airflow 공식 문서에서는 다음 방식을 권장한다.

Airflow는 Python 버전에 따라 의존성이 달라지므로, constraints 파일을 사용해 의존성을 고정하여 설치한다.

즉,

• Airflow 버전
• Python 버전

이 두 가지가 정해지면,
그 조합에 맞는 constraints 파일을 기준으로 설치를 진행해야 한다는 것이다.

pip install apache-airflow==2.6.2 \
  --constraint https://raw.githubusercontent.com/apache/airflow/constraints-2.6.2/constraints-3.10.txt

이 constraints 파일은 사실상

“이 조합에서 검증된 의존성 목록”
이라고 보면 된다.

 

2. Provider 설치 시에도 Constraints는 필수

Airflow core 설치가 끝났다고 해서 모든 설정이 끝나는 것은 아니다.
Postgres, MySQL, S3 등 외부 시스템을 사용하려면 Provider 패키지를 추가로 설치해야 한다.

 

이때도 중요한 점은 동일하다.

 

Airflow Provider는 core Airflow와 동일한 constraints 파일을 적용하여 설치해야 의존성 충돌을 방지할 수 있다.

예를 들어 Postgres Provider를 설치할 경우:

pip install apache-airflow-providers-postgres \
  --constraint "${CONSTRAINT_URL}"

처음에는 Provider를 단독으로 설치했다가
SQLAlchemy, packaging, email-validator 등에서 의존성 충돌 경고를 직접 겪었고,
결국 원인은 constraints 없이 설치한 것이었다.

 

3. Docker Compose 환경에서 Provider Connection 설정

Airflow와 Postgres를 Docker Compose로 구성한 이후,
다음으로 마주친 문제는 Connection 설정이었다.

 

처음에는 Host에 127.0.0.1이나 포트 매핑 값을 넣었지만,
Airflow가 컨테이너 내부에서 실행 중이라는 점을 간과하고 있었다.

 

Docker Compose 환경에서는 중요한 규칙이 있다.

Docker Compose를 사용하여 컨테이너를 구성한 경우,
Provider Connection의 Host에는 서비스 이름(Container Name)을 사용할 수 있다.

이는 Docker Compose가 내부적으로 다음과 같은 구조를 제공하기 때문이다.

Docker Compose로 구성된 환경에서는 서비스 이름이 도메인 이름처럼 동작하고,
Docker의 내부 DNS가 그 서비스 이름을 기반으로 실제 IP를 찾아준다.

즉,

Host = postgres
Port = 5432

처럼 서비스 이름 기반 연결이 가능하다.

 

4. Docker Compose 없이 컨테이너를 띄웠을 때의 문제

이번 과정에서 가장 직접적으로 겪은 문제는 여기였다.

Docker Compose 없이 컨테이너를 각각 띄우면,
기본적으로는 서비스 이름으로 서로를 찾을 수 없다.

 

실제로 Airflow 컨테이너에서 Postgres 컨테이너로 연결할 때,

• 서비스 이름을 Host로 사용했지만
• 내부 DNS 해석이 되지 않아 connection refused 에러가 발생했다.

이 경우 선택지는 다음과 같다.

• 컨테이너 IP를 직접 사용
• 호스트 포트를 통해 접근
• 또는 공통 사용자 정의 네트워크를 구성

하지만 이런 방식은 관리 측면에서 불안정하므로,
결론적으로는 Docker Compose를 통한 구성 + 서비스 이름 기반 연결이 가장 안정적인 방법이라는 점을 다시 한 번 체감했다.

 

 

5. 정리하며

 

이번 Airflow 환경 구성 과정에서 얻은 핵심 정리는 다음과 같다.

• Airflow 설치 시 constraints 파일은 선택이 아니라 필수
• Provider 설치 시에도 반드시 동일한 constraints 파일 사용
• Docker Compose 환경에서는 서비스 이름 기반 연결이 정석
• Compose 없이 컨테이너를 띄우면 DNS 기반 연결이 기본적으로 제공되지 않음

결국 문제의 대부분은

“개념을 몰라서가 아니라, 어디까지 자동으로 제공되는지 몰랐기 때문”
에 가까웠다.

 

이 글이 앞으로 Airflow + Docker 환경을 처음 구성하는 사람들에게
조금이나마 삽질을 줄이는 참고 자료가 되기를 바란다