설정 옵션 설정하기

설정 옵션 설정하기 (Setting Configuration Options)

Airflow 설정을 airflow.cfg 파일이나 환경 변수로 구성하는 방법을 설명하는 문서예요. 기본 설정 생성, 환경 변수 형식(AIRFLOW__{SECTION}__{KEY}), _cmd/_secret 접미사로 런타임에 값을 파생하는 방법, 설정 우선순위, 그리고 로컬 설정(airflow_local_settings.py) 구성까지 살펴볼게요.

출처: 문서

본문

Airflow를 처음 실행하면 $AIRFLOW_HOME 디렉토리(기본 ~/airflow)에 airflow.cfg라는 파일을 만들어요. 이는 airflow 설정을 쉽게 "가지고 놀" 수 있게 하기 위함이에요.

다만 프로덕션의 경우에는 커맨드라인으로 구성 파일을 생성하는 것을 권장해요:

airflow config list --defaults

이 명령은 구성 파일에 복사해서 편집할 수 있는 출력을 만들어요. 모든 기본 구성 옵션을 예시와 함께, 깔끔하게 주석 처리된 형태로 포함할 것이므로, 변경하려는 것만 주석을 풀고 수정하면 돼요. 이렇게 하면 기본값에서 변경한 모든 구성 옵션을 쉽게 추적할 수 있고, 새 버전의 Airflow가 나왔을 때 설치를 쉽게 업그레이드하고 기존 옵션이 거기서 변경됐다면 자동으로 기본값을 사용할 수 있어요.

구성 파일로 리다이렉트해 편집할 수 있어요:

airflow config list --defaults > "${AIRFLOW_HOME}/airflow.cfg"

AIRFLOW__{SECTION}__{KEY} 형식(이중 밑줄 참고)을 사용해 환경 변수로 옵션을 설정할 수도 있어요.

예를 들어 메타데이터 데이터베이스 연결 문자열은 airflow.cfg에서 이렇게 설정하거나:

[database]
sql_alchemy_conn = my_conn_string

이에 대응하는 환경 변수를 만들어 설정할 수 있어요:

export AIRFLOW__DATABASE__SQL_ALCHEMY_CONN=my_conn_string

섹션 이름에 점(dot)이 있으면 환경 변수를 설정할 때 점을 밑줄로 바꿔야 한다는 점을 참고하세요. 예를 들어 가상의 섹션 providers.some_provider를 생각해 봐요:

[providers.some_provider]
this_param = true

export AIRFLOW__PROVIDERS_SOME_PROVIDER__THIS_PARAM=true

키에 _cmd를 붙여 런타임에 연결 문자열을 파생할 수도 있어요:

[database]
sql_alchemy_conn_cmd = bash_command_to_run

키에 _secret을 붙여 런타임에 연결 문자열을 파생할 수도 있어요:

[database]
sql_alchemy_conn_secret = sql_alchemy_conn
# You can also add a nested path
# example:
# sql_alchemy_conn_secret = database/sql_alchemy_conn

이렇게 하면 Hashicorp Vault 같은 Secret Backend에서 구성 옵션을 가져와요. 자세한 내용은 Secrets Backends를 참고하세요.

다음 구성 옵션들이 이 _cmd와 _secret 버전을 지원해요:

[database] 섹션의 sql_alchemy_conn
[core] 섹션의 fernet_key
[celery] 섹션의 broker_url
[celery] 섹션의 flower_basic_auth
[celery] 섹션의 result_backend
[atlas] 섹션의 password
[smtp] 섹션의 smtp_password
[api] 섹션의 secret_key
[api_auth] 섹션의 jwt_secret

_cmd 구성 옵션은 일반 구성 옵션과 같은 방식으로 대응하는 환경 변수로도 설정할 수 있어요. 예를 들어:

export AIRFLOW__DATABASE__SQL_ALCHEMY_CONN_CMD=bash_command_to_run

마찬가지로 _secret 구성 옵션도 대응하는 환경 변수로 설정할 수 있어요. 예를 들어:

export AIRFLOW__DATABASE__SQL_ALCHEMY_CONN_SECRET=sql_alchemy_conn

참고 (Note)

구성 옵션은 secrets backend 내에 정의된 구성 프리픽스 명명 규칙을 따라야 해요. 즉 sql_alchemy_conn은 connection 프리픽스가 아니라 config 프리픽스로 정의돼요. 예를 들어 airflow/config/sql_alchemy_conn처럼 이름을 지어야 해요.

이 아이디어의 배경은 박스에 비밀번호를 평문 텍스트 파일로 저장하지 않으려는 것이에요.

모든 구성 옵션의 보편적 우선순위는 다음과 같아요:

환경 변수로 설정 (AIRFLOW__DATABASE__SQL_ALCHEMY_CONN)
커맨드 환경 변수로 설정 (AIRFLOW__DATABASE__SQL_ALCHEMY_CONN_CMD)
시크릿 환경 변수로 설정 (AIRFLOW__DATABASE__SQL_ALCHEMY_CONN_SECRET)
airflow.cfg에 설정
airflow.cfg의 명령(command)
airflow.cfg의 시크릿 키(secret key)
Airflow의 내장 기본값

참고 (Note)

Airflow 2.2.1 이상, 2.3.0 미만 버전에서는 일부 상황에서 Airflow의 내장 기본값이 airflow.cfg의 command와 secret key보다 우선했어요.

현재 구성은 airflow config list 명령으로 확인할 수 있어요.

하나의 옵션 값만 보고 싶다면 아래 예시처럼 airflow config get-value 명령을 사용할 수 있어요.

$ airflow config get-value core executor
LocalExecutor

참고 (Note)

구성 옵션에 대한 자세한 내용은 Configuration Reference를 참고하세요.

참고 (Note)

Python과 Airflow가 모듈을 관리하는 방법에 대한 자세한 내용은 Modules Management를 참고하세요.

참고 (Note)

다른 Airflow 컴포넌트는 다른 구성 파라미터를 요구할 수 있어요. 보안을 개선하기 위해 모든 컴포넌트에 모든 구성을 공유하기보다 민감한 구성을 필요로 하는 컴포넌트에만 제한하세요. 일부 값은 특정 컴포넌트 간에 일관적이어야 해요 — 예를 들어 JWT 서명 키는 토큰을 생성·검증하는 컴포넌트 간에 일치해야 해요. 하지만 데이터베이스 연결 문자열, Fernet 키, secrets backend 자격 증명 같은 민감한 파라미터는 실제로 필요한 컴포넌트에만 제공해야 해요.

보안에 민감한 배포에서는 개별 컴포넌트에 스코프된 환경 변수로 구성 값을 전달하세요. 구성 파라미터 제한에 대한 자세한 지침은 Airflow Security Model을 참고하세요.

Airflow 컴포넌트를 실행하는 모든 머신의 시간이 동기화되어 있는지(예: ntpd 사용) 확인하세요. 그렇지 않으면 로그에 접근하거나 API 호출을 할 때 "forbidden" 오류가 발생할 수 있어요.

로컬 설정 구성하기 (Configuring local settings)

일부 Airflow 구성은 로컬 설정을 통해 구성돼요. Airflow가 초기화될 때 실행되는 코드의 변경을 요구하기 때문이에요. 보통 상세 문서에서 그러한 로컬 설정을 어디에서 구성할 수 있는지 언급돼요 — 보통 airflow_local_settings.py 파일에서 해요.

airflow_local_settings.py 파일을 만들어 sys.path의 디렉토리나 $AIRFLOW_HOME/config 폴더에 두어야 해요. (Airflow는 초기화될 때 $AIRFLOW_HOME/config를 sys.path에 추가해요.)

Airflow 2.10.1부터 초기화 시 $AIRFLOW_HOME/dags 폴더는 더 이상 sys.path에 포함되지 않으므로 그 폴더의 로컬 설정은 import되지 않아요. airflow_local_settings.py가 초기화 중 sys.path의 일부인 경로(예: $AIRFLOW_HOME/config)에 위치하도록 보장하세요. 이 변경에 대한 자세한 맥락은 메일링 리스트 공지를 참고하세요.

이런 로컬 설정의 예시를 여기서 볼 수 있어요:

이렇게 구성할 수 있는 예시 설정:

설정 옵션 설정하기

설정 옵션 설정하기 (Setting Configuration Options)

본문

로컬 설정 구성하기 (Configuring local settings)

더 알아보기 (Learn more)