Airflow

Secrets Backend 탐색 순서

Airflow UI는 메타데이터 DB에 저장된 Connection과 Variable만 보여주며, 다른 방식으로 저장된 값은 보여주지 않는다 - 대체 secrets backend를 사용한다면 그 백엔드 내부를 직접 확인해 값을 봐야 한다.

Connection/Variable을 조회할 때 기본적으로 Airflow는 환경 변수를 먼저, 메타스토어 DB를 그다음으로 검색한다. 대체 secrets backend를 활성화하면 그 백엔드가 가장 먼저 검색되고, 그다음 환경 변수, 그다음 메타스토어 순서가 된다 - 이 탐색 순서는 설정으로 바꿀 수 없다(다만 일부 대체 백엔드는 어떤 connection/variable/config를 그 백엔드에서 검색할지 필터링하는 옵션을 자체적으로 제공할 수 있다). 워커 전용 secrets backend가 정의되어 있다면, 워커의 조회 순서에서는 워커 전용 백엔드가 가장 높은 우선순위를 갖고 그다음이 일반 secrets backend다.

환경 변수나 대체 secrets backend로 시크릿/변수를 저장할 때 키 충돌이 생길 수 있다. 백엔드 간 키가 중복된 경우, 모든 쓰기 연산은 메타스토어의 값을 갱신하지만, 모든 읽기 연산은 커스텀 백엔드부터 시작해 환경 변수, 마지막으로 메타스토어 순으로 요청된 키의 첫 매치를 반환한다.

[secrets]/[workers] 설정과 backend_kwargs

``[secrets]`` 섹션은 ``backend``(활성화할 백엔드의 fully qualified 클래스 이름)와 ``backend_kwargs``(JSON으로 백엔드 ``__init__``에 전달될 인자) 두 옵션을 갖는다. 현재 설정된 백엔드는 ``airflow config get-value secrets backend`` 명령으로 확인할 수 있다.

모든 kwargs를 하나의 JSON 블롭으로 인코딩하는 대신, ``AIRFLOW__SECRETS__BACKEND_KWARG__<KEY>`` 접두사로 각 kwarg를 개별 환경 변수로 설정할 수도 있다(Kubernetes Secret과 함께 쓰기 유리하다). 개별 kwarg 환경 변수는 ``BACKEND_KWARGS``의 동일 키를 덮어쓰며, 값은 JSON으로 파싱되지 않는 원시 문자열로 취급된다. 워커에는 ``AIRFLOW__WORKERS__SECRETS_BACKEND_KWARG__<KEY>`` 접두사를 사용한다. 이 kwarg 환경 변수들은 시작 시 로그에서 ``BACKEND_KWARGS``와 동일한 방식으로 마스킹된다.

Airflow 3부터는 워커를 위한 별도의 secrets backend를 ``[workers] secrets_backend``/``secrets_backend_kwargs``로 구성할 수 있다. 현재 워커 secrets backend 설정은 ``airflow config get-value workers secrets_backend``로 확인할 수 있다.

커스텀 Secrets Backend 구현

Secrets backend는 :py:class:`airflow.secrets.base_secrets.BaseSecretsBackend`의 서브클래스이며, Connection 조회를 위해 ``get_connection`` 또는 ``get_conn_value`` 중 하나를, Variable 조회를 위해 ``get_variable``을, Airflow 설정 조회를 위해 ``get_config``를 구현해야 한다. 백엔드 클래스를 작성한 뒤에는 ``airflow.cfg``의 ``[secrets]`` 섹션 ``backend`` 키에 fully qualified 클래스 이름을 지정하면 된다. 추가 인자는 ``backend_kwargs``에 JSON 문자열로 제공한다.

기본 Secrets backend 구현은 Connection을 저장할 때 Airflow 고유 포맷(JSON 또는 Airflow Connection URI 포맷)을 요구한다. 하지만 일부 조직은 동일한 자격증명 저장소를 여러 데이터 플랫폼에서 공유해야 하거나, Airflow 포맷과 맞지 않는 자체 자격증명 로테이션 메커니즘을 쓰는 서비스를 사용해야 할 수 있다. 이런 경우 기존 secrets backend를 확장하거나 조직의 스킴에 맞게 조정한 자체 secrets backend를 만들어야 한다.

Local Filesystem Secrets Backend

이 백엔드는 두 가지 유즈케이스에 특히 유용하다: 개발 환경에서는 모든 터미널 창 간 데이터 동기화를 보장하면서도(DB와 동일) 동시에 DB 재시작 후에도 값이 유지된다(환경 변수와 동일). Kubernetes 환경에서는 Kubernetes Secret에 시크릿을 저장하거나, 사이드카 컨테이너와 공유 볼륨을 이용해 값을 동기화할 수 있다.

Local Filesystem에서 Variable과 Connection을 사용하려면 ``[secrets]``의 ``backend``에 :py:class:`~airflow.secrets.local_filesystem.LocalFilesystemBackend`를 지정한다. ``backend_kwargs``에서 사용 가능한 파라미터는 ``variables_file_path``, ``connections_file_path``, ``configs_file_path``이며, 모두 선택적이다 - 경로가 주어지지 않으면 백엔드는 빈 컬렉션을 반환한다. 파일 포맷으로는 JSON, YAML, ``.env``를 지원한다.

Connection 파일은 키가 Connection ID이고 값이 URI 문자열이거나 JSON 객체인 형태다. extra 파라미터는 ``extra_dejson``(JSON 객체) 또는 ``extra``(JSON 문자열) 키로 제공하며 이 둘은 상호 배타적이다. Variable 파일은 키가 Variable 이름이고 값이 Variable 값인 간단한 key-value 구조다. Config 파일은 ``_secret`` 접미사가 붙은 설정 옵션이 가리키는 값 이름을 키로, 실제 설정값을 값으로 갖는다(예: ``database.sql_alchemy_conn_secret``에 지정된 값 이름을 키로 하여 실제 DB 연결 문자열을 값으로 저장). 세 파일 모두 JSON, YAML, ``.env`` 포맷을 동일하게 지원하며, ``.env`` 형식에서는 각 줄이 ``키=값`` 형태다.