기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# requirements.txt에서의 Python 종속성 관리
이 주제에서는 Amazon Managed Workflows for Apache Airflow 환경을 위해 `requirements.txt` 파일에 Python 종속성을 설치 및 관리하는 방법을 설명합니다.
**Contents**
+ [Amazon MWAA CLI 유틸리티를 사용한 DAG 테스트](#best-practices-dependencies-cli-utility)
+ [Pypi.org 요구 사항 파일 형식을 이용한 Python 종속성 설치](#best-practices-dependencies-different-ways)
+ [옵션 1: Python 패키지 인덱스의 Python 종속성](#best-practices-dependencies-pip-extras)
+ [옵션 2: Python 휠(.whl)](#best-practices-dependencies-python-wheels)
+ [Amazon S3 버킷에서 `plugins.zip` 파일 사용](#best-practices-dependencies-python-wheels-s3)
+ [URL에 호스팅된 WHL 파일 사용](#best-practices-dependencies-python-wheels-url)
+ [DAG에서의 WHL 파일 생성](#best-practices-dependencies-python-wheels-dag)
+ [옵션 3: 프라이빗 Pypi/PEP-503 호환 리포지토리에서 호스팅되는 Python 종속성](#best-practices-dependencies-custom-auth-url)
+ [Amazon MWAA 콘솔에서 로그를 활성화합니다.](#best-practices-dependencies-troubleshooting-enable)
+ [CloudWatch Logs 콘솔에서 로그 액세스](#best-practices-dependencies-troubleshooting-view)
+ [Apache Airflow UI에서 오류 액세스](#best-practices-dependencies-troubleshooting-aa)
+ [Apache Airflow에 로그인](#airflow-access-and-login)
+ [예제 `requirements.txt` 시나리오](#best-practices-dependencies-ex-mix-match)
## Amazon MWAA CLI 유틸리티를 사용한 DAG 테스트
+ 명령줄 인터페이스(CLI) 유틸리티는 Amazon Managed Workflows for Apache Airflow 환경을 로컬로 복제합니다.
+ CLI는 Amazon MWAA 프로덕션 이미지와 유사한 Docker 컨테이너 이미지를 로컬로 구축합니다. 이를 사용해 Amazon MWAA에 배포하기 전에 로컬 Apache Airflow 환경을 실행하여 DAG, 사용자 지정 플러그인 및 종속성을 개발하고 테스트할 수 있습니다.
+ CLI를 실행하려면 GitHub의 [aws-mwaa-docker-images](https://github.com/aws/amazon-mwaa-docker-images)를 참조하세요.
## Pypi.org 요구 사항 파일 형식을 이용한 Python 종속성 설치
다음 섹션에서는 Pypi.org [요구 사항 파일 형식](https://pip.pypa.io/en/stable/reference/pip_install/#requirements-file-format)에 따라 Python 종속성을 설치하는 다양한 방법을 설명합니다.
### 옵션 1: Python 패키지 인덱스의 Python 종속성
다음 섹션에서는 `requirements.txt` 파일의 [Python 패키지 인덱스](https://pypi.org/)에서 Python 종속성을 지정하는 방법을 설명합니다.
------
#### [ Apache Airflow v3 ]
1. **로컬 테스트**. `requirements.txt` 파일을 생성하기 전에 라이브러리를 반복적으로 추가하여 패키지와 버전의 적절한 조합을 찾습니다. Amazon MWAA CLI 유틸리티를 실행하려면 GitHub의 [aws-mwaa-docker-images](https://github.com/aws/amazon-mwaa-docker-images)를 참조하세요.
1. **Apache Airflow 패키지 엑스트라를 검토합니다.** Amazon MWAA의 Apache Airflow v3에 설치된 패키지 목록에 액세스하려면 GitHub 웹 사이트의 [aws-mwaa-docker-images`requirements.txt`](https://github.com/aws/amazon-mwaa-docker-images/blob/main/requirements.txt)를 참조하세요.
1. **제약 조건 문을 추가합니다**. 파일 상단에 Apache Airflow v3 환경의 제약 조건 `requirements.txt` 파일을 추가합니다. Apache Airflow 제약 조건 파일은 Apache Airflow 릴리스 당시 사용할 수 있는 공급자 버전을 지정합니다.
다음 예제에서는 *\$1environment-version\$1*을 사용자 환경의 버전 번호로 바꾸고 *\$1Python-version\$1*을 사용자 환경과 호환되는 Python의 버전으로 바꿉니다.
Apache Airflow 환경과 호환되는 Python 버전에 대한 자세한 내용은 [Apache Airflow 버전](airflow-versions.md#airflow-versions-official)을 참조하세요.
```
--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 로그 액세스](monitoring-airflow.md) 섹션을 참조하세요.
1. **Apache Airflow 패키지** [패키지 엑스트라](http://airflow.apache.org/docs/apache-airflow/2.5.1/extra-packages-ref.html) 및 버전(`==`)을 추가합니다. 이렇게 하면 이름은 같지만 버전이 다른 패키지가 사용자 환경에 설치되는 것을 방지할 수 있습니다.
```
apache-airflow[package-extra]==2.5.1
```
1. **Python 라이브러리**. `requirements.txt` 파일에 패키지 이름과 버전(`==`)을 추가합니다. 이렇게 하면 [Pypi.org](https://pypi.org)의 향후 주요 업데이트가 자동으로 적용되는 것을 방지하는 데 도움이 됩니다.
```
library == version
```
**Example Boto3 및 psycopg2-binary**
이 예제는 데모용으로 제공됩니다. boto 및 psycopg2-binary 라이브러리는 Apache Airflow v3 기본 설치에 포함되어 있으며 `requirements.txt` 파일에서 지정할 필요가 없습니다.
```
boto3==1.17.54
boto==2.49.0
botocore==1.20.54
psycopg2-binary==2.8.6
```
버전 정보 없이 패키지를 지정한 경우 Amazon MWAA는 [PyPI.org](https://pypi.org)의 최신 버전의 패키지를 설치합니다. 이 버전은 `requirements.txt`에 있는 다른 패키지와 충돌할 수 있습니다.
------
#### [ Apache Airflow v2 ]
1. **로컬 테스트**. `requirements.txt` 파일을 생성하기 전에 라이브러리를 반복적으로 추가하여 패키지와 버전의 적절한 조합을 찾습니다. Amazon MWAA CLI 유틸리티를 실행하려면 GitHub의 [aws-mwaa-docker-images](https://github.com/aws/amazon-mwaa-docker-images)를 참조하세요.
1. **Apache Airflow 패키지 엑스트라를 검토합니다.** Amazon MWAA의 Apache Airflow v2에 설치된 패키지 목록에 액세스하려면 GitHub 웹 사이트에서 [aws-mwaa-docker-images`requirements.txt`](https://github.com/aws/amazon-mwaa-docker-images/blob/main/requirements.txt)에 액세스합니다.
1. **제약 조건 문을 추가합니다**. `requirements.txt` 파일 상단에 Apache Airflow v2 환경에 대한 제약 조건 파일을 추가합니다. Apache Airflow 제약 조건 파일은 Apache Airflow 릴리스 당시 사용할 수 있는 공급자 버전을 지정합니다.
Apache Airflow v2.7.2부터 요구 사항 파일에 `--constraint` 문이 포함되어야 합니다. 제약 조건을 제공하지 않으면 Amazon MWAA에서 요구 사항에 나열된 패키지가 사용 중인 Apache Airway 버전과 호환되도록 제약 조건을 지정합니다.
다음 예제에서는 *\$1environment-version\$1*을 사용자 환경의 버전 번호로 바꾸고 *\$1Python-version\$1*을 사용자 환경과 호환되는 Python의 버전으로 바꿉니다.
Apache Airflow 환경과 호환되는 Python 버전에 대한 자세한 내용은 [Apache Airflow 버전](airflow-versions.md#airflow-versions-official)을 참조하세요.
```
--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 로그 액세스](monitoring-airflow.md) 섹션을 참조하세요.
1. **Apache Airflow 패키지** [패키지 엑스트라](http://airflow.apache.org/docs/apache-airflow/2.5.1/extra-packages-ref.html) 및 버전(`==`)을 추가합니다. 이렇게 하면 이름은 같지만 버전이 다른 패키지가 사용자 환경에 설치되는 것을 방지할 수 있습니다.
```
apache-airflow[package-extra]==2.5.1
```
1. **Python 라이브러리**. `requirements.txt` 파일에 패키지 이름과 버전(`==`)을 추가합니다. 이렇게 하면 [Pypi.org](https://pypi.org)의 향후 주요 업데이트가 자동으로 적용되는 것을 방지하는 데 도움이 됩니다.
```
library == version
```
**Example 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](https://pypi.org)의 최신 버전의 패키지를 설치합니다. 이 버전은 `requirements.txt`에 있는 다른 패키지와 충돌할 수 있습니다.
------
### 옵션 2: Python 휠(.whl)
Python 휠은 컴파일된 아티팩트와 함께 라이브러리를 배포하도록 설계된 패키지 형식입니다. Amazon MWAA에 종속성을 설치하는 방법으로 휠 패키지를 사용하면 여러 가지 이점이 있습니다.
+ **빠른 설치** - WHL 파일을 단일 ZIP으로 컨테이너에 복사하여 로컬에 설치하므로 각 파일을 다운로드할 필요가 없습니다.
+ **충돌 감소** - 패키지의 버전 호환성을 미리 확인할 수 있습니다. 따라서, `pip`가 호환되는 버전을 재귀적으로 찾아낼 필요가 없습니다.
+ **복원성 향상** - 외부에서 호스팅되는 라이브러리를 사용하면 다운스트림 요구 사항이 변경되어 Amazon MWAA 환경의 컨테이너 간 버전이 호환되지 않는 문제가 발생할 수 있습니다. 외부 소스의 종속성에 의존하지 않기 때문에 각 컨테이너가 예시된 시기에 관계없이 모든 컨테이너가 동일한 라이브러리를 갖게 됩니다.
Python 휠 아카이브(`.whl`)의 Python 종속성을 설치하려면 사용자의 `requirements.txt`에서 다음 메서드를 사용하는 것이 좋습니다.
**Topics**
+ [Amazon S3 버킷에서 `plugins.zip` 파일 사용](#best-practices-dependencies-python-wheels-s3)
+ [URL에 호스팅된 WHL 파일 사용](#best-practices-dependencies-python-wheels-url)
+ [DAG에서의 WHL 파일 생성](#best-practices-dependencies-python-wheels-dag)
#### Amazon S3 버킷에서 `plugins.zip` 파일 사용
Apache Airflow 스케줄러, 작업자 및 웹 서버(Apache Airflow v2.2.2 이상용)는에서 환경의 AWS관리형 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 [aws-mwaa-docker-images](https://github.com/aws/amazon-mwaa-docker-images) 또는 다른 [Amazon Linux 2](https://aws.amazon.com/amazon-linux-2) 컨테이너에 있는 기존 `requirements.txt`와 함께 [https://pip.pypa.io/en/stable/cli/pip_download/](https://pip.pypa.io/en/stable/cli/pip_download/)를 이용하여 필요한 Python 휠 파일을 확인하고 다운로드할 수 있습니다.
```
pip3 download -r "$AIRFLOW_HOME/dags/requirements.txt" -d "$AIRFLOW_HOME/plugins"
cd "$AIRFLOW_HOME/plugins"
zip "$AIRFLOW_HOME/plugins.zip" *
```
1. **`requirements.txt`에서의 경로 지정** 다음 코드에 나열된 바와 같이 [https://pip.pypa.io/en/stable/cli/pip_install/#install-find-links](https://pip.pypa.io/en/stable/cli/pip_install/#install-find-links)를 사용하여 requirements.txt 상단에 플러그인 디렉터리를 지정하고, [https://pip.pypa.io/en/stable/cli/pip_install/#install-no-index](https://pip.pypa.io/en/stable/cli/pip_install/#install-no-index)를 사용하여 `pip`이 다른 소스에서 설치하지 않도록 지시합니다.
```
--find-links /usr/local/airflow/plugins
--no-index
```
**Example 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을 입력합니다.
**Example 퍼블릭 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://amzn-s3-demo-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 구성 옵션](configuring-env-variables.md)으로 추가합니다. 예제:
+ `foo.user` : `YOUR_USER_NAME`
+ `foo.pass` : `YOUR_PASSWORD`
1. `requirements.txt` 파일 생성 다음 예제의 자리 표시자를 프라이빗 URL과 [Apache Airflow 구성 옵션](configuring-env-variables.md)으로 추가한 사용자 이름 및 암호로 대체합니다. 예제:
```
--index-url https://${AIRFLOW__FOO__USER}:${AIRFLOW__FOO__PASS}@my.privatepypi.com
```
1. `requirements.txt` 파일에 라이브러리를 추가합니다. 예제:
```
--index-url https://${AIRFLOW__FOO__USER}:${AIRFLOW__FOO__PASS}@my.privatepypi.com
my-private-package==1.2.3
```
## Amazon MWAA 콘솔에서 로그를 활성화합니다.
Amazon MWAA 환경의 [실행 역할](mwaa-create-role.md)에는 로그를 CloudWatch Log에 전송할 수 있는 권한이 필요합니다. 실행 역할의 권한을 업데이트하려면 [Amazon MWAA 실행 역할](mwaa-create-role.md) 섹션을 참조하세요.
`INFO`, `WARNING`, `ERROR`, 또는 `CRITICAL` 수준에서 Apache Airflow 로그를 활성화할 수 있습니다. 로그 수준을 선택하면 Amazon MWAA에서 해당 수준 및 더 높은 모든 심각도 수준에 대한 로그를 전송합니다. 예를 들어, `INFO` 수준에서 로그를 활성화하면 Amazon MWAA는 `INFO` 로그 및 `WARNING`, `ERROR`, `CRITICAL` 로그 수준을 CloudWatch Log로 보냅니다. 스케줄러가 `requirements.txt`를 위해 수신한 로그에 액세스할 수 있도록 `INFO` 수준에서 Apache Airflow 로그를 활성화하는 것이 좋습니다.
![\[이 이미지는 INFO 수준에서 로그를 활성화하는 방법을 보여줍니다.\]](http://docs.aws.amazon.com/ko_kr/mwaa/latest/userguide/images/mwaa-console-logs-info.png)
## CloudWatch Logs 콘솔에서 로그 액세스
워크플로우를 예약하고 `dags` 폴더를 구문 분석하는 스케줄러에 대한 Apache Airflow 로그를 액세스할 수 있습니다. 다음 단계에서는 Amazon MWAA 콘솔에서 스케줄러에 대한 로그 그룹을 여는 방법과 CloudWatch Logs 콘솔에서 Apache Airflow 로그를 액세스하는 방법을 설명합니다.
**`requirements.txt`에 대한 로그에 액세스하려면**
1. Amazon MWAA 콘솔에서 [환경 페이지](https://console.aws.amazon.com/mwaa/home#/environments)를 엽니다.
1. 환경을 선택합니다.
1. **모니터링** 창에서 **Airflow 스케줄러 로그 그룹**을 선택합니다.
1. **로그 스트림**에서 `requirements_install_ip` 로그를 선택합니다.
1. `/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))
```
1. 패키지 목록을 검토하고 설치 중에 오류가 발생했는지 여부를 검토합니다. 문제가 발생한 경우, 다음과 비슷한 오류가 표시될 수 있습니다.
```
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 계정 in AWS Identity and Access Management (IAM)에 대한 [Apache Airflow UI 액세스 정책: AmazonMWAAWebServerAccess](access-policies.md#web-ui-access) 권한이 필요합니다.
**Apache Airflow UI에 액세스하려면**
1. Amazon MWAA 콘솔에서 [환경 페이지](https://console.aws.amazon.com/mwaa/home#/environments)를 엽니다.
1. 환경을 선택합니다.
1. **Airflow UI 열기**를 선택합니다.
## 예제 `requirements.txt` 시나리오
`requirements.txt`에 다양한 형식을 믹스하여 매치할 수 있습니다. 다음 예제에서는 여러 가지 방법을 조합하여 엑스트라를 설치합니다.
**Example 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
```