requirements.txt에서의 Python 종속성 관리 - Amazon Managed Workflows for Apache Airflow
Amazon MWAA CLI 유틸리티를 사용한 DAG 테스트Pypi.org 요구 사항 파일 형식을 이용한 Python 종속성 설치Amazon MWAA 콘솔에서 로그를 활성화합니다.CloudWatch Logs 콘솔에서 로그 보기Apache Airflow UI에서 오류 보기예제 requirements.txt 시나리오

requirements.txt에서의 Python 종속성 관리

이 페이지에서는 Amazon Managed Workflows for Apache Airflow 환경을 위해 requirements.txt 파일에 Python 종속성을 설치 및 관리하기 위해 권장하는 모범 사례를 설명합니다.

Amazon MWAA CLI 유틸리티를 사용한 DAG 테스트

  • 명령줄 인터페이스(CLI) 유틸리티는 Amazon Managed Workflows for Apache Airflow 환경을 로컬로 복제합니다.

  • CLI는 Amazon MWAA 프로덕션 이미지와 유사한 Docker 컨테이너 이미지를 로컬로 구축합니다. 이를 통해 Amazon MWAA에 배포하기 전에 로컬 Apache Airflow 환경을 실행하여 DAG, 사용자 지정 플러그인 및 종속성을 개발하고 테스트할 수 있습니다.

  • CLI를 실행하려면 GitHub의 aws-mwaa-local-runner를 참조하십시오.

Pypi.org 요구 사항 파일 형식을 이용한 Python 종속성 설치

다음 섹션에서는 Pypi.org 요구 사항 파일 형식에 따라 Python 종속성을 설치하는 다양한 방법을 설명합니다.

옵션 1: Python 패키지 인덱스의 Python 종속성

다음 섹션에서는 requirements.txt 파일의 Python 패키지 인덱스에서 Python 종속성을 지정하는 방법을 설명합니다.

Apache Airflow v2

  1. 로컬 테스트. requirements.txt 파일을 생성하기 전에 라이브러리를 반복적으로 추가하여 패키지와 버전의 적절한 조합을 찾습니다. Amazon MWAA CLI 유틸리티를 실행하려면, GitHub의 aws-mwaa-local-runner를 참조하십시오.

  2. Apache Airflow 패키지 엑스트라를 검토합니다. Amazon MWAA에서 Apache Airflow v2용으로 설치된 패키지 목록을 보려면 GitHub 웹 사이트의 Amazon MWAA 로컬 러너requirements.txt를 참조하십시오.

  3. 제약 조건 문을 추가합니다. requirements.txt 파일 상단에 Apache Airflow v2 환경에 대한 제약 조건 파일을 추가합니다. Apache Airflow 제약 조건 파일은 Apache Airflow 릴리스 당시 사용할 수 있는 공급자 버전을 지정합니다.

    Apache Airflow v2.7.2부터 요구 사항 파일에 --constraint 문이 포함되어야 합니다. 제약 조건을 제공하지 않으면 Amazon MWAA에서 요구 사항에 나열된 패키지가 사용 중인 Apache Airway 버전과 호환되도록 제약 조건을 지정합니다.

    다음 예제에서는 {environment-version}을 사용자 환경의 버전 번호로 바꾸고 {Python-version}을 사용자 환경과 호환되는 Python의 버전으로 바꿉니다.

    Apache Airflow 환경과 호환되는 Python 버전에 대한 자세한 내용은 Apache Airflow 버전 단원을 참조하세요.

    --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-{Airflow-version}/constraints-{Python-version}.txt"

    제약 조건 파일에서 xyz==1.0 패키지가 사용자 환경의 다른 패키지와 호환되지 않는 것으로 확인되면 호환되지 않는 라이브러리가 환경에 설치되는 것을 방지하기 위해 pip3 install이 실패합니다. 패키지 설치에 실패하는 경우, CloudWatch Logs의 해당 로그 스트림에서 각 Apache Airflow 구성 요소(스케줄러, 작업자, 웹 서버)에 대한 오류 로그를 볼 수 있습니다. 로그 형식에 대한 자세한 내용은 Amazon CloudWatch에서 Airflow 로그 보기 섹션을 참조하십시오.

  4. Apache Airflow 패키지 패키지 엑스트라 및 버전(==)을 추가합니다. 이렇게 하면 이름은 같지만 버전이 다른 패키지가 사용자 환경에 설치되는 것을 방지할 수 있습니다.

    apache-airflow[package-extra]==2.5.1

  5. Python 라이브러리. requirements.txt 파일에 패키지 이름과 버전(==)을 추가합니다. 이렇게 하면 Pypi.org의 향후 주요 업데이트가 자동으로 적용되는 것을 방지하는 데 도움이 됩니다.

    library == version
    예 Boto3 및 psycopg2-binary

    이 예제는 데모용으로 제공됩니다. boto 및 psycopg2-binary 라이브러리는 Apache Airflow v2 기본 설치에 포함되어 있으며 requirements.txt 파일에서 지정할 필요가 없습니다.

    boto3==1.17.54
boto==2.49.0
botocore==1.20.54
psycopg2-binary==2.8.6

    버전 정보 없이 패키지를 지정한 경우 Amazon MWAA는 PyPI.org의 최신 버전의 패키지를 설치합니다. 이 버전은 requirements.txt에 있는 다른 패키지와 충돌할 수 있습니다.

Apache Airflow v1

  1. 로컬 테스트. requirements.txt 파일을 생성하기 전에 라이브러리를 반복적으로 추가하여 패키지와 버전의 적절한 조합을 찾습니다. Amazon MWAA CLI 유틸리티를 실행하려면, GitHub의 aws-mwaa-local-runner를 참조하십시오.

  2. Airflow 패키지 추가 내용을 검토합니다. https://raw.githubusercontent.com/apache/airflow/constraints-1.10.12/constraints-3.7.txt에서 Apache Airflow v1.10.12에 사용할 수 있는 패키지 목록을 검토합니다.

  3. 제약조건 파일 추가 requirements.txt 파일 상단에 Apache Airflow v1.10.12의 제약 조건 파일을 추가합니다. 제약 조건 파일에서 xyz==1.0 패키지가 사용자 환경의 다른 패키지와 호환되지 않는 것으로 확인되면 pip3 install은 호환되지 않는 라이브러리가 환경에 설치되는 것을 막을 수 없습니다.

    --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-1.10.12/constraints-3.7.txt"

  4. Apache Airflow v1.10.12 패키지. Airflow 패키지 엑스트라 및 Apache Airflow v1.10.12 버전(==)을 추가합니다. 이렇게 하면 이름은 같지만 버전이 다른 패키지가 사용자 환경에 설치되는 것을 방지할 수 있습니다.

    apache-airflow[package]==1.10.12
    예 Secure Shell(SSH)

    다음 예제 requirements.txt 파일은 Apache Airflow v1.10.12용 SSH를 설치합니다.

    apache-airflow[ssh]==1.10.12

  5. Python 라이브러리. requirements.txt 파일에 패키지 이름과 버전(==)을 추가합니다. 이렇게 하면 Pypi.org의 향후 주요 업데이트가 자동으로 적용되는 것을 방지하는 데 도움이 됩니다.

    library == version
    예 Boto3

    다음 예제 requirements.txt 파일은 Apache Airflow v1.10.12용 Boto3 라이브러리를 설치합니다.

    boto3 == 1.17.4

    버전 정보 없이 패키지를 지정한 경우 Amazon MWAA는 PyPI.org의 최신 버전의 패키지를 설치합니다. 이 버전은 requirements.txt에 있는 다른 패키지와 충돌할 수 있습니다.

옵션 2: Python 휠(.whl)

Python 휠은 컴파일된 아티팩트와 함께 라이브러리를 배포하도록 설계된 패키지 형식입니다. Amazon MWAA에 종속성을 설치하는 방법으로 휠 패키지를 사용하면 여러 가지 이점이 있습니다.

  • 빠른 설치 - WHL 파일을 단일 ZIP으로 컨테이너에 복사하여 로컬에 설치하므로 각 파일을 다운로드할 필요가 없습니다.

  • 충돌 감소 - 패키지의 버전 호환성을 미리 확인할 수 있습니다. 따라서, pip가 호환되는 버전을 재귀적으로 찾아낼 필요가 없습니다.

  • 복원성 향상 - 외부에서 호스팅되는 라이브러리를 사용하면 다운스트림 요구 사항이 변경되어 Amazon MWAA 환경의 컨테이너 간 버전이 호환되지 않는 문제가 발생할 수 있습니다. 외부 소스의 종속성에 의존하지 않기 때문에 각 컨테이너가 예시된 시기에 관계없이 모든 컨테이너가 동일한 라이브러리를 갖게 됩니다.

Python 휠 아카이브(.whl)의 Python 종속성을 설치하려면 사용자의 requirements.txt에서 다음 메서드를 사용하는 것이 좋습니다.

Amazon S3 버킷에서 plugins.zip 파일 사용

Apache Airflow 스케줄러, 작업자 및 웹 서버(Apache Airflow v2.2.2 이상의 경우)는 AWS-managed Fargate 컨테이너에서 시작하는 동안 /usr/local/airflow/plugins/*의 사용자 환경에 맞는 사용자 지정 플러그인을 찾습니다. 이 프로세스는 Python 종속성과 Apache Airflow 서비스 시작을 위한 Amazon MWAA의 pip3 install -r requirements.txt 이전에 시작됩니다. 환경 실행 중에 지속적으로 변경되지 않기를 바라는 파일, 또는 DAG를 작성하는 사용자에게 액세스 권한을 부여하고 싶지 않은 모든 파일에는 plugins.zip 파일을 사용합니다. 예를 들면, Python 라이브러리 휠 파일, 인증서 PEM 파일, 구성 YAML 파일이 있습니다.

다음 섹션에서는 Amazon S3 버킷의 plugins.zip 파일에 있는 휠을 설치하는 방법을 설명합니다.

  1. 필요한 WHL 파일 다운로드 Amazon MWAA 로컬 러너 또는 다른 Amazon Linux 2 컨테이너에 있는 기존 requirements.txt와 함께 pip download를 이용하여 필요한 Python 휠 파일을 확인하고 다운로드할 수 있습니다.

    $ pip3 download -r "$AIRFLOW_HOME/dags/requirements.txt" -d "$AIRFLOW_HOME/plugins"
$ cd "$AIRFLOW_HOME/plugins"
$ zip "$AIRFLOW_HOME/plugins.zip" *

  2. requirements.txt에서의 경로 지정 다음 그림과 같이 --find-links를 사용하여 requirements.txt 상단에 플러그인 디렉터리를 지정하고, --no-index를 사용하여 pip이 다른 소스에서 설치하지 않도록 지시합니다.

    --find-links /usr/local/airflow/plugins
--no-index
    예 requirements.txt의 휠

    다음 예제는 Amazon S3 버킷의 루트에 있는 plugins.zip 파일에 휠을 업로드했다고 가정합니다. 예:

    --find-links /usr/local/airflow/plugins
--no-index

numpy

    Amazon MWAA가 plugins 폴더에서 numpy-1.20.1-cp37-cp37m-manylinux1_x86_64.whl 휠을 가져와 사용자 환경에 설치합니다.

URL에 호스팅된 WHL 파일 사용

다음 섹션에서는 URL에서 호스팅되는 휠 설치 방법을 설명합니다. URL은 공개적으로 액세스할 수 있거나 Amazon MWAA 환경을 위해 명시한 사용자 지정 Amazon VPC 내에서 액세스할 수 있어야 합니다.

  • URL 제공 requirements.txt 내 휠에 URL을 입력합니다.

    예 퍼블릭 URL의 휠 아카이브

    다음 예에서는 퍼블릭 사이트에서 휠을 다운로드합니다.

    --find-links https://files.pythonhosted.org/packages/
--no-index

    Amazon MWAA는 지정한 URL에서 휠을 가져와 사용자 환경에 설치합니다.

    참고

    Amazon MWAA v2.2.2 이상의 요구 사항을 설치하는 프라이빗 웹 서버에서는 URL에 액세스할 수 없습니다.

DAG에서의 WHL 파일 생성

Apache Airflow v2.2.2 이상을 사용하는 프라이빗 웹 서버가 있고, 환경에서 외부 리포지토리에 액세스할 수 없어 요구 사항을 설치할 수 없는 경우, 다음 DAG를 사용하여 기존 Amazon MWAA 요구 사항을 가져와 Amazon S3에 패키징할 수 있습니다.

from airflow import DAG
from airflow.operators.bash_operator import BashOperator
from airflow.utils.dates import days_ago

S3_BUCKET = 'my-s3-bucket'
S3_KEY = 'backup/plugins_whl.zip' 

with DAG(dag_id="create_whl_file", schedule_interval=None, catchup=False, start_date=days_ago(1)) as dag:
    cli_command = BashOperator(
        task_id="bash_command",
        bash_command=f"mkdir /tmp/whls;pip3 download -r /usr/local/airflow/requirements/requirements.txt -d /tmp/whls;zip -j /tmp/plugins.zip /tmp/whls/*;aws s3 cp /tmp/plugins.zip s3://{S3_BUCKET}/{S3_KEY}"
    )

DAG를 실행한 후, 옵션으로 이 새 파일을 Amazon MWAA plugins.zip으로 사용하고, 옵션으로 다른 플러그인과 함께 패키징할 수 있습니다. 그런 다음, --constraint를 추가하지 않고 --find-links /usr/local/airflow/plugins와 --no-index가 앞에 나오는 requirements.txt를 업데이트합니다.

이 방법을 사용하면 동일한 라이브러리를 오프라인에서 사용할 수 있습니다.

옵션 3: 프라이빗 Pypi/PEP-503 호환 리포지토리에서 호스팅되는 Python 종속성

다음 섹션에서는 인증을 통해 프라이빗 URL에 호스팅되는 Apache Airflow 엑스트라를 설치하는 방법을 설명합니다.

  1. 사용자 이름과 암호를 Apache Airflow 구성 옵션으로 추가합니다. 예:

    • foo.user : YOUR_USER_NAME

    • foo.pass : YOUR_PASSWORD

  2. requirements.txt 파일 생성 다음 예제의 자리 표시자를 프라이빗 URL과 Apache Airflow 구성 옵션으로 추가한 사용자 이름 및 암호로 대체합니다. 예:

    --index-url https://${AIRFLOW__FOO__USER}:${AIRFLOW__FOO__PASS}@my.privatepypi.com

  3. requirements.txt 파일에 라이브러리를 추가합니다. 예:

    --index-url https://${AIRFLOW__FOO__USER}:${AIRFLOW__FOO__PASS}@my.privatepypi.com
my-private-package==1.2.3

Amazon MWAA 콘솔에서 로그를 활성화합니다.

Amazon MWAA 환경의 실행 역할에는 로그를 CloudWatch Log에 전송할 수 있는 권한이 필요합니다. 실행 역할의 권한을 업데이트하려면 Amazon MWAA 실행 역할 섹션을 참조하십시오.

INFO, WARNING, ERROR, 또는 CRITICAL 수준에서 Apache Airflow 로그를 활성화할 수 있습니다. 로그 수준을 선택하면 Amazon MWAA에서 해당 수준 및 더 높은 모든 심각도 수준에 대한 로그를 전송합니다. 예를 들어, INFO 수준에서 로그를 활성화하면 Amazon MWAA는 INFO 로그 및 WARNING, ERROR, CRITICAL 로그 수준을 CloudWatch Log로 보냅니다. 스케줄러가 requirements.txt를 위해 수신한 로그를 볼 수 있도록 INFO 수준에서 Apache Airflow 로그를 활성화하는 것이 좋습니다.

이 이미지는 INFO 수준에서 로그를 활성화하는 방법을 보여줍니다.

CloudWatch Logs 콘솔에서 로그 보기

워크플로우를 예약하고 dags 폴더를 구문 분석하는 스케줄러에 대한 Apache Airflow 로그를 볼 수 있습니다. 다음 단계에서는 Amazon MWAA 콘솔에서 스케줄러에 대한 로그 그룹을 여는 방법과 CloudWatch Logs 콘솔에서 Apache Airflow 로그를 보는 방법을 설명합니다.

requirements.txt에 대한 로그를 보려면

  1. Amazon MWAA 콘솔에서 환경 페이지를 엽니다.

  2. 환경을 선택합니다.

  3. 모니터링 창에서 Airflow 스케줄러 로그 그룹을 선택합니다.

  4. 로그 스트림에서 requirements_install_ip 로그를 선택합니다.

  5. /usr/local/airflow/.local/bin에서 환경에 설치된 패키지 목록을 볼 수 있습니다. 예:

    Collecting appdirs==1.4.4 (from -r /usr/local/airflow/.local/bin (line 1))
Downloading https://files.pythonhosted.org/packages/3b/00/2344469e2084fb28kjdsfiuyweb47389789vxbmnbjhsdgf5463acd6cf5e3db69324/appdirs-1.4.4-py2.py3-none-any.whl  
Collecting astroid==2.4.2 (from -r /usr/local/airflow/.local/bin (line 2))

  6. 패키지 목록을 검토하고 설치 중에 오류가 발생했는지 여부를 검토합니다. 문제가 발생한 경우, 다음과 비슷한 오류가 표시될 수 있습니다.

    2021-03-05T14:34:42.731-07:00
No matching distribution found for LibraryName==1.0.0 (from -r /usr/local/airflow/.local/bin (line 4))
No matching distribution found for LibraryName==1.0.0 (from -r /usr/local/airflow/.local/bin (line 4))

Apache Airflow UI에서 오류 보기

Apache Airflow UI를 확인하여 오류가 다른 문제와 관련이 있는지 확인하는 것도 좋습니다. Amazon MWAA의 Apache Airflow에서 발생할 수 있는 가장 일반적인 오류는 다음과 같습니다.

Broken DAG: No module named x

Apache Airflow UI에 이 오류가 표시되면 requirements.txt 파일에 필수 종속성이 없는 것일 수 있습니다.

Apache Airflow에 로그인

Apache Airflow UI를 보려면 AWS Identity and Access Management(IAM)의 AWS 계정에 대한 Apache Airflow UI 액세스 정책: AmazonMWAAWebServerAccess 권한이 필요합니다.

Apache Airflow UI에 액세스하려면

  1. Amazon MWAA 콘솔에서 환경 페이지를 엽니다.

  2. 환경을 선택합니다.

  3. Airflow UI 열기를 선택합니다.

예제 requirements.txt 시나리오

requirements.txt에 다양한 형식을 믹스하여 매치할 수 있습니다. 다음 예제에서는 여러 가지 방법을 조합하여 엑스트라를 설치합니다.

예 Pypi.org의 엑스트라 및 퍼블릭 URL

PyPI.org에서 패키지를 지정할 때는 사용자 지정 PEP 503 호환 리포지토리 URL과 같은 퍼블릭 URL의 패키지 외에도 --index-url 옵션을 사용해야 합니다.

aws-batch == 0.6
phoenix-letter >= 0.3
    
--index-url http://dist.repoze.org/zope2/2.10/simple
    zopelib