Cloud Composer 1 | Cloud Composer 2 | Cloud Composer 3
이 페이지에서는 Cloud Composer 환경에서 Python 패키지를 설치하는 방법을 설명합니다.
Cloud Composer 이미지의 사전 설치된 PyPI 패키지 및 커스텀 PyPI 패키지 정보
Cloud Composer 이미지에는 사전 설치된 PyPI 패키지 및 커스텀 PyPI 패키지가 모두 포함되어 있습니다.
사전 설치된 PyPI 패키지는 해당 환경의 Cloud Composer 이미지에 포함된 패키지입니다. 각 Cloud Composer 이미지에는 Cloud Composer 및 Airflow 버전과 관련된 PyPI 패키지가 포함됩니다.
커스텀 PyPI 패키지는 사전 설치된 패키지에 추가로 환경에 설치할 수 있는 패키지입니다.
Cloud Composer 환경의 PyPI 패키지 관리 옵션
옵션 | 사용 가능한 경우 |
---|---|
PyPI에서 설치 | 환경에 패키지를 설치하는 기본 방법 |
공개 IP 주소가 있는 저장소에서 설치 | 패키지가 PyPI 이외의 Package Repository에서 호스팅됩니다. 저장소에 공개 IP 주소가 있습니다. |
Artifact Registry 저장소에서 설치 | 패키지가 Artifact Registry 저장소에서 호스팅됩니다. |
프로젝트 네트워크의 저장소에서 설치 | 환경에 공개 인터넷에 대한 액세스 권한이 없습니다. 패키지가 프로젝트 네트워크의 패키지 저장소에서 호스팅됩니다. |
로컬 Python 라이브러리로 설치 |
패키지를 PyPI에서 찾을 수 없고 라이브러리에 dist-packages 와 같은 외부 종속 항목이 없습니다. |
플러그인 설치 | 패키지가 Airflow 웹 인터페이스 수정과 같은 플러그인 관련 기능을 제공합니다. |
PythonVirtualenvOperator | 모든 Airflow 작업자에 대해 패키지를 설치하지 않거나 종속 항목이 사전 설치된 패키지와 충돌합니다. 이 패키지는 PyPI에서 찾을 수 있고 외부 종속 항목이 없습니다. |
KubernetesPodOperator 및 GKE 연산자 |
pip 에서 설치할 수 없는 외부 종속 항목(예: dist-packages )이 필요하거나 내부 pip 서버를 사용 중입니다. 이 옵션을 사용하려면 추가 설정 및 유지보수 작업이 필요합니다. 다른 옵션이 적용되지 않는 경우에만 고려하세요. |
시작하기 전에
- 환경 업데이트 작업을 트리거할 수 있는 역할이 필요합니다. 또한 해당 환경의 서비스 계정에 업데이트 작업을 수행하는 데 충분한 권한이 있는 역할이 있어야 합니다. 자세한 내용은 액세스 제어를 참조하세요.
- VPC 서비스 제어 경계가 환경을 보호하고 있다면 PyPI 종속 항목을 설치하기 전에 서비스 경계가 보호하는 서비스에 대한 액세스 권한이 있는 추가 사용자 ID를 부여하고 비공개 PyPI 저장소에 대한 지원을 사용 설정해야 합니다.
- 요구사항은 PEP-508에 지정된 형식을 따라야 합니다. 여기에는 각 요구사항은 소문자로 지정되어 있고 패키지 이름, 선택적 추가 기능 및 버전 지정자로 구성되어 있습니다.
PyPI 종속 항목을 업데이트하면 Artifact Registry에 Docker 이미지가 생성됩니다.
종속 항목 충돌로 인해 업데이트가 실패하게 되면 사용자 환경이 기존 종속 항목으로 계속 실행됩니다. 작업이 성공하면 DAG에서 새로 설치된 Python 종속 항목을 사용할 수 있습니다.
빌드를 커스텀 서비스 계정에서 실행하려면 선택한 서비스 계정으로
COMPOSER_AGENT_BUILD_SERVICE_ACCOUNT
환경 변수를 재정의하면 됩니다. 이 서비스 계정은 Cloud Build 문서별로 빌드를 실행하도록 구성되어야 하며 환경의 서비스 계정에는 이에 대한iam.serviceAccounts.actAs
권한이 있어야 합니다.Cloud Composer API가 2024년 4월 29일 이후에 사용 설정된 프로젝트 조직에서
constraints/cloudbuild.disableCreateDefaultServiceAccount
정책을 재정의하지 않는 한 새 프로젝트는 API를 사용 설정할 때 기존 Cloud Build 서비스 계정을 프로비저닝하지 않습니다. Cloud Composer 환경에 커스텀 PyPI 패키지를 설치할 때 기본적으로 Cloud Build가 사용되므로 패키지 설치가 실패할 수 있습니다. 기본적으로 환경의 서비스 계정이 대신 사용되므로 비공개 패키지에 액세스하는 데 필요한 추가 권한을 해당 서비스 계정에도 부여해야 합니다.
PyPI 패키지 목록 보기
여러 형식으로 환경의 패키지 목록을 가져올 수 있습니다.
사전 설치된 패키지 보기
환경의 사전 설치된 패키지 목록을 보려면 환경의 Cloud Composer 이미지에 대한 패키지 목록을 참조하세요.
모든 패키지 보기
환경에서 모든 패키지(사전 설치된 패키지와 커스텀 패키지 모두)를 보려면 다음 안내를 따르세요.
gcloud
다음 gcloud CLI 명령어는 환경에서 Airflow 작업자에 대해 python -m pip list
명령어 결과를 반환합니다.
--tree
인수를 사용하여 python -m pipdeptree --warn
명령어의 결과를 가져올 수 있습니다.
gcloud beta composer environments list-packages \
ENVIRONMENT_NAME \
--location LOCATION
다음과 같이 바꿉니다.
ENVIRONMENT_NAME
을 환경 이름으로 바꿉니다.LOCATION
: 환경이 위치한 리전
커스텀 PyPI 패키지 보기
콘솔
Google Cloud 콘솔에서 환경 페이지로 이동합니다.
환경 목록에서 환경 이름을 클릭합니다. 환경 세부정보 페이지가 열립니다.
PyPI 패키지 탭으로 이동합니다.
gcloud
gcloud composer environments describe ENVIRONMENT_NAME \
--location LOCATION \
--format="value(config.softwareConfig.pypiPackages)"
다음과 같이 바꿉니다.
ENVIRONMENT_NAME
을 환경 이름으로 바꿉니다.LOCATION
: 환경이 위치한 리전
Cloud Composer 환경에 커스텀 패키지 설치
이 섹션에서는 사용자 환경에 커스텀 패키지를 설치하는 다양한 방법을 설명합니다.
PyPI에서 패키지 설치
외부 종속 항목 또는 사전 설치된 패키지와의 충돌이 없으면 Python 패키지 색인에서 패키지를 설치할 수 있습니다.
사용자 환경의 Python 종속 항목을 추가, 업데이트 또는 삭제하려면 다음 안내를 따르세요.
콘솔
Google Cloud 콘솔에서 환경 페이지로 이동합니다.
환경 목록에서 환경 이름을 클릭합니다. 환경 세부정보 페이지가 열립니다.
PyPI 패키지 탭으로 이동합니다.
수정을 클릭합니다.
패키지 추가를 클릭합니다.
PyPI 패키지 섹션에서 패키지 이름과 선택적인 버전 지정자 및 추가 항목을 지정합니다.
예를 들면 다음과 같습니다.
scikit-learn
scipy
,>=0.13.3
nltk
,[machine_learning]
저장을 클릭합니다.
gcloud
gcloud CLI에는 커스텀 PyPI 패키지를 사용하기 위한 몇 가지 인수가 포함되어 있습니다.
--update-pypi-packages-from-file
은 모든 기존 커스텀 PyPI 패키지를 지정된 패키지로 바꿉니다. 지정하지 않은 패키지는 삭제됩니다.--update-pypi-package
은 하나의 패키지를 업데이트하거나 설치합니다.--remove-pypi-packages
는 지정된 패키지를 삭제합니다.--clear-pypi-packages
는 모든 패키지를 삭제합니다.
파일에서 요구사항 설치
requirements.txt
파일에는 각 요구사항 지정자가 별도의 줄에 있어야 합니다.
예를 들면 다음과 같습니다.
scipy>=0.13.3
scikit-learn
nltk[machine_learning]
환경을 업데이트하고 --update-pypi-packages-from-file
인수에 requirements.txt
파일을 지정합니다.
gcloud composer environments update ENVIRONMENT_NAME \
--location LOCATION \
--update-pypi-packages-from-file requirements.txt
다음과 같이 바꿉니다.
ENVIRONMENT_NAME
을 환경 이름으로 바꿉니다.LOCATION
: 환경이 위치한 리전
패키지 하나 설치
환경을 업데이트하고 --update-pypi-package
인수에 패키지, 버전, 추가 항목을 지정합니다.
gcloud composer environments update ENVIRONMENT_NAME \
--location LOCATION \
--update-pypi-package PACKAGE_NAMEEXTRAS_AND_VERSION
다음과 같이 바꿉니다.
ENVIRONMENT_NAME
을 환경 이름으로 바꿉니다.LOCATION
: 환경이 위치한 리전PACKAGE_NAME
: 패키지 이름EXTRAS_AND_VERSION
: 선택적인 버전 및 추가 항목 지정자. 버전 및 추가 항목을 생략하려면 빈 값을 지정합니다.
예를 들면 다음과 같습니다.
gcloud composer environments update example-environment \
--location us-central1 \
--update-pypi-package "scipy>=0.13.3"
패키지 삭제
환경을 업데이트하고 --remove-pypi-packages
인수에서 삭제할 패키지를 지정합니다.
gcloud composer environments update ENVIRONMENT_NAME \
--location LOCATION \
--remove-pypi-packages PACKAGE_NAMES
다음과 같이 바꿉니다.
ENVIRONMENT_NAME
을 환경 이름으로 바꿉니다.LOCATION
: 환경이 위치한 리전PACKAGE_NAMES
: 쉼표로 구분된 패키지 목록
예를 들면 다음과 같습니다.
gcloud composer environments update example-environment \
--location us-central1 \
--remove-pypi-packages scipy,scikit-learn
API
environments.patch
API 요청을 생성합니다.
이 요청의 작성 방법:
updateMask
매개변수에서 마스크를 지정합니다.config.softwareConfig.pypiPackages
마스크를 사용하여 모든 기존 패키지를 지정된 패키지로 바꿉니다. 지정하지 않은 패키지는 삭제됩니다.config.softwareConfig.envVariables.PACKAGE_NAME
을 사용하여 특정 패키지를 추가하거나 업데이트합니다. 여러 패키지를 추가하거나 업데이트하려면 쉼표를 사용해 여러 마스크를 지정합니다.
요청 본문에서 패키지와 버전 및 추가 항목의 값을 지정합니다.
{ "config": { "softwareConfig": { "pypiPackages": { "PACKAGE_NAME": "EXTRAS_AND_VERSION" } } } }
다음과 같이 바꿉니다.
PACKAGE_NAME
: 패키지 이름EXTRAS_AND_VERSION
: 선택적인 버전 및 추가 항목 지정자. 버전 및 추가 항목을 생략하려면 빈 값을 지정합니다.- 한 개를 초과해서 패키지를 추가하려면 패키지에 대한 추가 항목을
pypiPackages
에 추가합니다.
예를 들면 다음과 같습니다.
// PATCH https://composer.googleapis.com/v1/projects/example-project/
// locations/us-central1/environments/example-environment?updateMask=
// config.softwareConfig.pypiPackages.EXAMPLE_PACKAGE,
// config.softwareConfig.pypiPackages.ANOTHER_PACKAGE
{
"config": {
"softwareConfig": {
"pypiPackages": {
"EXAMPLE_PACKAGE": "",
"ANOTHER_PACKAGE": ">=1.10.3"
}
}
}
}
Terraform
software_config
블록의 pypi_packages
블록은 패키지를 지정합니다.
resource "google_composer_environment" "example" {
provider = google-beta
name = "ENVIRONMENT_NAME"
region = "LOCATION"
config {
software_config {
pypi_packages = {
PACKAGE_NAME = "EXTRAS_AND_VERSION"
}
}
}
}
다음과 같이 바꿉니다.
ENVIRONMENT_NAME
을 환경 이름으로 바꿉니다.LOCATION
: 환경이 위치한 리전PACKAGE_NAME
: 패키지 이름EXTRAS_AND_VERSION
: 선택적인 버전 및 추가 항목 지정자. 버전 및 추가 항목을 생략하려면 빈 값을 지정합니다.- 한 개를 초과해서 패키지를 추가하려면 패키지에 대한 추가 항목을
pypi_packages
에 추가합니다.
예를 들면 다음과 같습니다.
resource "google_composer_environment" "example" {
provider = google-beta
name = "example-environment"
region = "us-central1"
config {
software_config {
pypi_packages = {
scipy = ">=1.10.3"
scikit-learn = ""
nltk = "[machine_learning]"
}
}
}
}
공개 저장소에서 패키지 설치
공개 IP 주소가 있는 다른 저장소에 호스팅된 패키지를 설치할 수 있습니다.
기본 pip
도구로 패키지를 설치할 수 있도록 패키지를 적절하게 구성해야 합니다.
공개 주소가 있는 패키지 저장소에서 설치하려면 다음 안내를 따르세요.
pip.conf 파일을 만들고 해당하는 경우 파일에 다음 정보를 추가합니다.
- 저장소 URL(
index-url
매개변수) - 저장소에 대한 액세스 사용자 인증 정보
- 기본이 아닌
pip
설치 옵션
예를 들면 다음과 같습니다.
[global] index-url=https://example.com/
- 저장소 URL(
(선택사항) 공개 저장소에 설치하려는 특정 패키지가 포함되어 있고 PyPI에서 다른 모든 패키지를 설치하려는 경우와 같이 여러 저장소에서 패키지를 가져와야 하는 경우가 있습니다.
- Artifact Registry 가상 저장소를 구성합니다.
- 여러 저장소(필요한 경우 PyPI 포함)에 대한 구성을 추가하고
pip
가 저장소를 검색하는 순서를 정의합니다. index-url
파라미터에 가상 저장소 URL을 지정합니다.
환경 버킷의 URI를 파악합니다.
pip.conf 파일을 환경 버킷의
/config/pip/
폴더에 업로드합니다.사용 가능한 방법 중 하나를 사용하여 패키지를 설치합니다.
Artifact Registry 저장소에서 패키지 설치
프로젝트의 Artifact Registry 저장소에 패키지를 저장하고 이 저장소에서 설치하도록 환경을 구성할 수 있습니다.
역할과 권한을 구성합니다.
환경의 서비스 계정에는
iam.serviceAccountUser
역할이 있어야 합니다.Cloud Build 서비스 계정에 Artifact Registry 저장소에서 읽을 수 있는 권한이 있는지 확인합니다.
프로젝트의 다른 서비스에 대한 액세스가 환경에서 제한된 경우(예: VPC 서비스 제어를 사용하는 경우):
Artifact Registry 저장소에 대한 액세스 권한을 Cloud Build 서비스 계정 대신 환경의 서비스 계정에 할당합니다.
Artifact Registry 저장소에 대한 연결이 프로젝트에 구성되어 있는지 확인합니다.
Artifact Registry 저장소에서 커스텀 PyPI 패키지를 설치하려면 다음 안내를 따르세요.
pip.conf 파일을 만들고 해당하는 경우 파일에 다음 정보를 추가합니다.
- Artifact Registry 저장소의 URL(
index-url
매개변수) - 저장소에 대한 액세스 사용자 인증 정보
- 기본이 아닌
pip
설치 옵션
Artifact Registry 저장소의 경우 저장소 URL에
/simple/
을 추가합니다.[global] index-url = https://us-central1-python.pkg.dev/example-project/example-repository/simple/
- Artifact Registry 저장소의 URL(
(선택사항) 경우에 따라 Artifact Registry 저장소에 설치하려는 특정 패키지가 포함되어 있고 PyPI에서 다른 모든 패키지를 설치하려는 경우와 같이 여러 저장소에서 패키지를 가져와야 할 수 있습니다.
- Artifact Registry 가상 저장소를 구성합니다.
- 여러 저장소(필요한 경우 PyPI 포함)에 대한 구성을 추가하고
pip
가 저장소를 검색하는 순서를 정의합니다. index-url
파라미터에 가상 저장소 URL을 지정합니다.
이 pip.conf 파일을 환경 버킷의
/config/pip/
폴더에 업로드합니다. 예를 들면gs://us-central1-example-bucket/config/pip/pip.conf
입니다.사용 가능한 방법 중 하나를 사용하여 패키지를 설치합니다.
비공개 저장소에서 패키지 설치
프로젝트 네트워크에 비공개 저장소를 호스팅하고 이 저장소에서 Python 패키지를 설치하도록 환경을 구성할 수 있습니다.
역할과 권한을 구성합니다.
Cloud Composer 환경의 서비스 계정에
iam.serviceAccountUser
역할이 있어야 합니다.프로젝트 네트워크의 저장소에서 커스텀 PyPI 패키지를 설치하며 이 저장소에 공개 IP 주소가 없는 경우:
환경의 서비스 계정에 이 저장소에 대한 액세스 권한을 할당합니다.
이 저장소에 대한 연결이 프로젝트에 구성되어 있는지 확인합니다.
프로젝트 네트워크에 호스팅된 비공개 저장소에서 패키지를 설치하려면 다음 안내를 따르세요.
pip.conf 파일을 만들고 해당하는 경우 파일에 다음 정보를 추가합니다.
- 프로젝트 네트워크의 저장소 IP 주소
- 저장소에 대한 액세스 사용자 인증 정보
- 기본이 아닌
pip
설치 옵션
예를 들면 다음과 같습니다.
[global] index-url=https://192.0.2.10/
(선택사항) 비공개 저장소에 설치하려는 특정 패키지가 포함되어 있고 PyPI에서 다른 모든 패키지를 설치하려는 경우와 같이 여러 저장소에서 패키지를 가져와야 하는 경우가 있습니다.
- Artifact Registry 가상 저장소를 구성합니다.
- 여러 저장소(필요한 경우 PyPI 포함)에 대한 구성을 추가하고
pip
가 저장소를 검색하는 순서를 정의합니다. index-url
파라미터에 가상 저장소 URL을 지정합니다.
(선택사항) Cloud Composer 2.2.1 이상 버전에서는 비공개 저장소에서 패키지를 설치할 때 커스텀 인증서를 사용할 수 있습니다. 방법은 다음과 같습니다.
환경 버킷에서
/config/pip/
폴더에 인증서 파일을 업로드합니다.pip.conf에서
cert
매개변수에 인증서 파일 이름을 지정합니다./etc/pip/
폴더를 변경하지 않아야 합니다.예를 들면 다음과 같습니다.
[global] cert =/etc/pip/example-certificate.pem
pip.conf 파일을 환경 버킷의
/config/pip/
폴더에 업로드합니다. 예를 들면gs://us-central1-example-bucket/config/pip/pip.conf
입니다.사용 가능한 방법 중 하나를 사용하여 패키지를 설치합니다.
로컬 Python 라이브러리 설치
사내 또는 로컬 Python 라이브러리를 설치하려면 다음 안내를 따르세요.
환경 버킷에서
dags/
폴더의 하위 디렉터리에 종속 항목을 배치합니다. 하위 디렉터리에서 모듈을 가져오려면 모듈 경로의 각 하위 디렉터리에__init__.py
패키지 마커 파일이 포함되어 있어야 합니다.다음 예시에서 종속 항목은
coin_module.py
입니다.dags/ use_local_deps.py # A DAG file. dependencies/ __init__.py coin_module.py
DAG 정의 파일에서 종속 항목을 가져옵니다.
예를 들면 다음과 같습니다.
공유 객체 라이브러리에 의존하는 패키지 사용
특정 PyPI 패키지는 시스템 수준 라이브러리에 따라 달라집니다. Cloud Composer는 시스템 라이브러리를 지원하지 않지만 다음 옵션을 사용할 수 있습니다.
KubernetesPodOperator를 사용합니다. 연산자 이미지를 커스텀 빌드 이미지로 설정합니다. 시스템 종속 항목이 충족되지 않아 설치 중 실패한 패키지가 있으면 이 옵션을 사용합니다.
사용자 환경의 버킷에 공유 객체 라이브러리를 업로드합니다. PyPI 패키지가 성공적으로 설치되었지만 런타임에 실패하면 이 옵션을 사용합니다.
- PyPI 종속 항목에 대한 공유 객체 라이브러리를 수동으로 찾습니다(.so 파일).
- 환경 버킷의
/plugins
폴더에 공유 객체 라이브러리를 업로드합니다. - 다음 환경 변수를 설정합니다.
LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/airflow/gcs/plugins
비공개 IP 환경에 패키지 설치
이 섹션에서는 비공개 IP 환경에 패키지를 설치하는 방법을 설명합니다.
프로젝트 구성 방법에 따라 환경에서 공개 인터넷에 액세스하지 못할 수 있습니다.
공개 인터넷 액세스 권한이 있는 비공개 IP 환경
비공개 IP 환경에서 공개 인터넷에 액세스할 수 있는 경우 공개 IP 환경 옵션을 사용하여 패키지를 설치할 수 있습니다.
- PyPI에서 설치합니다. 이 경우에는 특별한 구성이 필요하지 않습니다. PyPI에서 패키지 설치에 설명된 절차를 따릅니다.
- 공개 IP 주소가 있는 저장소에서 설치합니다. 비공개 저장소에서 패키지 설치에 설명된 절차를 따릅니다.
- 프로젝트 네트워크에 호스팅되는 비공개 PyPI 저장소에서 설치합니다.
인터넷 액세스 권한이 없는 비공개 IP 환경
비공개 IP 환경에 공개 인터넷에 대한 액세스 권한이 없으면 다음 방법 중 하나를 사용하여 패키지를 설치할 수 있습니다.
- 프로젝트 네트워크에서 호스팅되는 비공개 PyPI 저장소를 사용합니다.
- 프로젝트 네트워크의 프록시 서버 VM을 사용하여 공개 인터넷의 PyPI 저장소에 연결합니다. 환경 버킷의
/config/pip/pip.conf
파일에 프록시 주소를 지정합니다. - 유일한 패키지 소스로 Artifact Registry 저장소를 사용합니다. 이렇게 하려면 설명대로
index-url
매개변수를 다시 정의합니다. - 보안 정책에 따라 VPC 네트워크의 외부 IP 주소에 대한 액세스가 허용되는 경우 Cloud NAT를 구성하여 공개 인터넷의 저장소에서 패키지 설치를 사용 설정할 수 있습니다.
- Python 종속 항목을 환경 버킷의
/dags
폴더에 넣어 로컬 라이브러리로 설치합니다. 종속 항목 트리가 클 때는 좋은 방법이 아닐 수 있습니다.
리소스 위치 제한에 따라 비공개 IP 환경에 설치
리소스 위치 제한 요구사항에 따라 프로젝트를 유지하면 일부 도구를 사용할 수 없습니다. 특히 Cloud Build를 패키지 설치에 사용할 수 없어서, 공개 인터넷의 저장소에 대한 직접 액세스가 방지됩니다.
이러한 환경에 Python 종속 항목을 설치하려면 인터넷 액세스 권한이 없는 비공개 IP 환경 안내를 따르세요.
VPC 서비스 제어 경계에서 비공개 IP 환경에 Python 종속 항목 설치
VPC 서비스 제어 매개변수로 프로젝트를 보호하면 보안 제한 사항이 추가됩니다. 특히 Cloud Build를 패키지 설치에 사용할 수 없어서, 공개 인터넷의 저장소에 대한 직접 액세스가 방지됩니다.
경계 내에서 비공개 IP 환경의 Python 종속 항목을 설치하려면 인터넷 액세스 권한이 없는 비공개 IP 환경의 안내를 따르세요.