Cloud Composer 1은 사후 유지보수 모드 상태입니다. Google은 Airflow의 새 버전, 버그 수정, 보안 업데이트를 비롯한 Cloud Composer 1 추가 업데이트를 출시하지 않습니다. Cloud Composer 2로 마이그레이션하는 것이 좋습니다.

Cloud Composer에 대한 Python 종속 항목 설치

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 이미지가 생성됩니다.

경고: Artifact Registry 또는 저장소 자체에서 Cloud Composer로 빌드된 이미지를 수정하거나 삭제하지 마세요. 자체 이미지를 저장소에 업로드하지 마세요. 대신 이미지에 대한 자체 저장소를 만들고 유지관리해야 합니다(예: KubernetesPodOperator에서 사용되는 이미지). 이 저장소를 직접 삭제하지 마세요. 환경을 삭제하면 저장소가 삭제됩니다.
종속 항목 충돌로 인해 업데이트가 실패하게 되면 사용자 환경이 기존 종속 항목으로 계속 실행됩니다. 작업이 성공하면 DAG에서 새로 설치된 Python 종속 항목을 사용할 수 있습니다.

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" {
  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" {
  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/
```
(선택사항) 공개 저장소에 설치하려는 특정 패키지가 포함되어 있고 PyPI에서 다른 모든 패키지를 설치하려는 경우와 같이 여러 저장소에서 패키지를 가져와야 하는 경우가 있습니다.
1. Artifact Registry 가상 저장소를 구성합니다.
2. 여러 저장소(필요한 경우 PyPI 포함)에 대한 구성을 추가하고 pip가 저장소를 검색하는 순서를 정의합니다.
3. index-url 파라미터에 가상 저장소의 URL을 지정합니다.
환경 버킷의 URI를 파악합니다.
pip.conf 파일을 환경 버킷의 /config/pip/ 폴더에 업로드합니다.
사용 가능한 방법 중 하나를 사용하여 패키지를 설치합니다.

Artifact Registry 저장소에서 패키지 설치

프로젝트의 Artifact Registry 저장소에 패키지를 저장하고 이 저장소에서 설치하도록 환경을 구성할 수 있습니다.

역할과 권한을 구성합니다.

환경의 서비스 계정에는 iam.serviceAccountUser 역할이 있어야 합니다.
Cloud Build 서비스 계정에 Artifact Registry 저장소에서 읽을 수 있는 권한이 있는지 확인합니다.
프로젝트의 다른 서비스에 대한 액세스가 환경에서 제한된 경우(예: VPC 서비스 제어를 사용하는 경우):
1. Artifact Registry 저장소에 대한 액세스 권한을 Cloud Build 서비스 계정 대신 환경의 서비스 계정에 할당합니다.
2. 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 저장소에 설치하려는 특정 패키지가 포함되어 있고 PyPI에서 다른 모든 패키지를 설치하려는 경우와 같이 여러 저장소에서 패키지를 가져와야 할 수 있습니다.
1. Artifact Registry 가상 저장소를 구성합니다.
2. 여러 저장소(필요한 경우 PyPI 포함)에 대한 구성을 추가하고 pip가 저장소를 검색하는 순서를 정의합니다.
3. index-url 파라미터에 가상 저장소의 URL을 지정합니다.
이 pip.conf 파일을 환경 버킷의 /config/pip/ 폴더에 업로드합니다. 예를 들면 gs://us-central1-example-bucket/config/pip/pip.conf입니다.
사용 가능한 방법 중 하나를 사용하여 패키지를 설치합니다.

비공개 저장소에서 패키지 설치

프로젝트 네트워크에 비공개 저장소를 호스팅하고 이 저장소에서 Python 패키지를 설치하도록 환경을 구성할 수 있습니다.

역할과 권한을 구성합니다.

Cloud Composer 환경의 서비스 계정에 iam.serviceAccountUser 역할이 있어야 합니다.
프로젝트 네트워크의 저장소에서 커스텀 PyPI 패키지를 설치하며 이 저장소에 공개 IP 주소가 없는 경우:
1. 환경의 서비스 계정에 이 저장소에 대한 액세스 권한을 할당합니다.
2. 이 저장소에 대한 연결이 프로젝트에 구성되어 있는지 확인합니다.

프로젝트 네트워크에 호스팅된 비공개 저장소에서 패키지를 설치하려면 다음 안내를 따르세요.

pip.conf 파일을 만들고 해당하는 경우 파일에 다음 정보를 추가합니다.
- 프로젝트 네트워크의 저장소 IP 주소
- 저장소에 대한 액세스 사용자 인증 정보
- 기본이 아닌 pip 설치 옵션
예:
```
[global]
index-url=https://192.0.2.10/
```
(선택사항) 비공개 저장소에 설치하려는 특정 패키지가 포함되어 있고 PyPI에서 다른 모든 패키지를 설치하려는 경우와 같이 여러 저장소에서 패키지를 가져와야 하는 경우가 있습니다.
1. Artifact Registry 가상 저장소를 구성합니다.
2. 여러 저장소(필요한 경우 PyPI 포함)에 대한 구성을 추가하고 pip가 저장소를 검색하는 순서를 정의합니다.
3. index-url 파라미터에 가상 저장소의 URL을 지정합니다.
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 정의 파일에서 종속 항목을 가져옵니다.

예를 들면 다음과 같습니다.

from dependencies import coin_module

공유 객체 라이브러리에 의존하는 패키지 사용

특정 PyPI 패키지는 시스템 수준 라이브러리에 따라 달라집니다. Cloud Composer는 시스템 라이브러리를 지원하지 않지만 다음 옵션을 사용할 수 있습니다.

KubernetesPodOperator를 사용합니다. 연산자 이미지를 커스텀 빌드 이미지로 설정합니다. 시스템 종속 항목이 충족되지 않아 설치 중 실패한 패키지가 있으면 이 옵션을 사용합니다.
사용자 환경의 버킷에 공유 객체 라이브러리를 업로드합니다. PyPI 패키지가 성공적으로 설치되었지만 런타임에 실패하면 이 옵션을 사용합니다.
1. PyPI 종속 항목에 대한 공유 객체 라이브러리를 수동으로 찾습니다(.so 파일).
2. 환경 버킷의 /plugins 폴더에 공유 객체 라이브러리를 업로드합니다.
3. 다음 환경 변수를 설정합니다. 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 환경의 안내를 따르세요.

Cloud Composer에 대한 Python 종속 항목 설치

Cloud Composer 이미지의 사전 설치된 PyPI 패키지 및 커스텀 PyPI 패키지 정보

Cloud Composer 환경의 PyPI 패키지 관리 옵션

시작하기 전에

PyPI 패키지 목록 보기

사전 설치된 패키지 보기

모든 패키지 보기

gcloud

커스텀 PyPI 패키지 보기

콘솔

gcloud

Cloud Composer 환경에 커스텀 패키지 설치

PyPI에서 패키지 설치

콘솔

gcloud

API

Terraform

공개 저장소에서 패키지 설치

Artifact Registry 저장소에서 패키지 설치

비공개 저장소에서 패키지 설치

로컬 Python 라이브러리 설치

공유 객체 라이브러리에 의존하는 패키지 사용

비공개 IP 환경에 패키지 설치

공개 인터넷 액세스 권한이 있는 비공개 IP 환경

인터넷 액세스 권한이 없는 비공개 IP 환경

리소스 위치 제한에 따라 비공개 IP 환경에 설치

VPC 서비스 제어 경계에서 비공개 IP 환경에 Python 종속 항목 설치

다음 단계