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

Cloud Composer 1 | Cloud Composer 2 | Cloud Composer 3

이 페이지에서는 Cloud Composer 환경에서 Python 패키지를 설치하는 방법을 설명합니다.

Cloud Composer의 패키지 정보

이 섹션에서는 Cloud Composer에서 PyPI 패키지가 작동하는 방식을 설명합니다.

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

Cloud Composer 이미지에는 사전 설치된 PyPI 패키지 및 커스텀 PyPI 패키지가 모두 포함되어 있습니다.

• 사전 설치된 PyPI 패키지는 해당 환경의 Cloud Composer 이미지에 포함된 패키지입니다. 각 Cloud Composer 이미지에는 Cloud Composer 및 Airflow 버전과 관련된 PyPI 패키지가 포함됩니다.

• 커스텀 PyPI 패키지는 사전 설치된 패키지에 추가로 환경에 설치할 수 있는 패키지입니다.

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

시작하기 전에

• 환경 업데이트 작업을 트리거할 수 있는 역할이 필요합니다. 또한 해당 환경의 서비스 계정에 업데이트 작업을 수행하는 데 충분한 권한이 있는 역할이 있어야 합니다.

• 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 beta composer environments list-packages \
    ENVIRONMENT_NAME \
    --location LOCATION

커스텀 PyPI 패키지 보기

gcloud composer environments describe ENVIRONMENT_NAME \
  --location LOCATION \
  --format="value(config.softwareConfig.pypiPackages)"

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

이 섹션에서는 사용자 환경에 커스텀 패키지를 설치하는 다양한 방법을 설명합니다.

PyPI에서 패키지 설치

외부 종속 항목 또는 사전 설치된 패키지와의 충돌이 없으면 Python 패키지 색인에서 패키지를 설치할 수 있습니다.

사용자 환경의 Python 종속 항목을 추가, 업데이트 또는 삭제하려면 다음 안내를 따르세요.

scipy>=0.13.3
scikit-learn
nltk[machine_learning]

gcloud composer environments update ENVIRONMENT_NAME \
    --location LOCATION \
     --update-pypi-packages-from-file requirements.txt

gcloud composer environments update ENVIRONMENT_NAME \
    --location LOCATION \
     --update-pypi-package PACKAGE_NAMEEXTRAS_AND_VERSION

gcloud composer environments update example-environment \
    --location us-central1 \
    --update-pypi-package "scipy>=0.13.3"

gcloud composer environments update ENVIRONMENT_NAME \
    --location LOCATION \
     --remove-pypi-packages PACKAGE_NAMES

gcloud composer environments update example-environment \
    --location us-central1 \
    --remove-pypi-packages scipy,scikit-learn

// 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"
      }
    }
  }
}

resource "google_composer_environment" "example" {
  provider = google-beta
  name = "ENVIRONMENT_NAME"
  region = "LOCATION"

  config {

    software_config {

      pypi_packages = {
          PACKAGE_NAME = "EXTRAS_AND_VERSION"
      }

    }
  }
}

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 도구로 패키지를 설치할 수 있도록 패키지를 적절하게 구성해야 합니다.

공개 주소가 있는 패키지 저장소에서 설치하려면 다음 안내를 따르세요.

1. pip.conf 파일을 만들고 해당하는 경우 파일에 다음 정보를 추가합니다.

   • 저장소 URL(index-url 매개변수)
   • 저장소에 대한 액세스 사용자 인증 정보
   • 기본이 아닌 pip 설치 옵션

   예:

   [global]
   index-url=https://example.com/
   

2. (선택사항) 공개 저장소에 설치하려는 특정 패키지가 포함되어 있고 PyPI에서 다른 모든 패키지를 설치하려는 경우와 같이 여러 저장소에서 패키지를 가져와야 하는 경우가 있습니다.

   1. Artifact Registry 가상 저장소를 구성합니다.
   2. 여러 저장소(필요한 경우 PyPI 포함)에 대한 구성을 추가하고 pip가 저장소를 검색하는 순서를 정의합니다.
   3. index-url 매개변수에 가상 저장소 URL을 지정합니다.

3. 환경 버킷의 URI를 파악합니다.

4. pip.conf 파일을 환경 버킷의 /config/pip/ 폴더에 업로드합니다.

5. 사용 가능한 방법 중 하나를 사용하여 패키지를 설치합니다.

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

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

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

1. 환경의 서비스 계정에는 iam.serviceAccountUser 역할이 있어야 합니다.

2. Cloud Build 서비스 계정에 Artifact Registry 저장소에서 읽을 수 있는 권한이 있는지 확인합니다.

3. 프로젝트의 다른 서비스에 대한 액세스가 환경에서 제한된 경우(예: VPC 서비스 제어를 사용하는 경우):

   1. Artifact Registry 저장소에 대한 액세스 권한을 Cloud Build 서비스 계정 대신 환경의 서비스 계정에 할당합니다.

   2. Artifact Registry 저장소에 대한 연결이 프로젝트에 구성되어 있는지 확인합니다.

Artifact Registry 저장소에서 커스텀 PyPI 패키지를 설치하려면 다음 안내를 따르세요.

1. 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/
   

2. (선택사항) 경우에 따라 Artifact Registry 저장소에 설치하려는 특정 패키지가 포함되어 있고 PyPI에서 다른 모든 패키지를 설치하려는 경우와 같이 여러 저장소에서 패키지를 가져와야 할 수 있습니다.

   1. Artifact Registry 가상 저장소를 구성합니다.
   2. 여러 저장소(필요한 경우 PyPI 포함)에 대한 구성을 추가하고 pip가 저장소를 검색하는 순서를 정의합니다.
   3. index-url 매개변수에 가상 저장소 URL을 지정합니다.

3. 이 pip.conf 파일을 환경 버킷의 /config/pip/ 폴더에 업로드합니다. 예를 들면 gs://us-central1-example-bucket/config/pip/pip.conf입니다.

4. 사용 가능한 방법 중 하나를 사용하여 패키지를 설치합니다.

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

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

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

1. Cloud Composer 환경의 서비스 계정에 iam.serviceAccountUser 역할이 있어야 합니다.

2. 프로젝트 네트워크의 저장소에서 커스텀 PyPI 패키지를 설치하며 이 저장소에 공개 IP 주소가 없는 경우:

   1. 환경의 서비스 계정에 이 저장소에 대한 액세스 권한을 할당합니다.

   2. 이 저장소에 대한 연결이 프로젝트에 구성되어 있는지 확인합니다.

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

1. pip.conf 파일을 만들고 해당하는 경우 파일에 다음 정보를 추가합니다.

   • 프로젝트 네트워크의 저장소 IP 주소
   • 저장소에 대한 액세스 사용자 인증 정보
   • 기본이 아닌 pip 설치 옵션

   예:

   [global]
   index-url=https://192.0.2.10/
   

2. (선택사항) 비공개 저장소에 설치하려는 특정 패키지가 포함되어 있고 PyPI에서 다른 모든 패키지를 설치하려는 경우와 같이 여러 저장소에서 패키지를 가져와야 하는 경우가 있습니다.

   1. Artifact Registry 가상 저장소를 구성합니다.
   2. 여러 저장소(필요한 경우 PyPI 포함)에 대한 구성을 추가하고 pip가 저장소를 검색하는 순서를 정의합니다.
   3. index-url 매개변수에 가상 저장소 URL을 지정합니다.

3. (선택사항) Cloud Composer 2.2.1 이상 버전에서는 비공개 저장소에서 패키지를 설치할 때 커스텀 인증서를 사용할 수 있습니다. 방법은 다음과 같습니다.

   1. 환경 버킷에서 /config/pip/ 폴더에 인증서 파일을 업로드합니다.

   2. pip.conf에서 cert 매개변수에 인증서 파일 이름을 지정합니다. /etc/pip/ 폴더를 변경하지 않아야 합니다.

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

      [global]
      cert =/etc/pip/example-certificate.pem
      

4. pip.conf 파일을 환경 버킷의 /config/pip/ 폴더에 업로드합니다. 예를 들면 gs://us-central1-example-bucket/config/pip/pip.conf입니다.

5. 사용 가능한 방법 중 하나를 사용하여 패키지를 설치합니다.

로컬 Python 라이브러리 설치

사내 또는 로컬 Python 라이브러리를 설치하려면 다음 안내를 따르세요.

1. 환경 버킷에서 dags/ 폴더의 하위 디렉터리에 종속 항목을 배치합니다. 하위 디렉터리에서 모듈을 가져오려면 모듈 경로의 각 하위 디렉터리에 __init__.py 패키지 마커 파일이 포함되어 있어야 합니다.

   다음 예시에서 종속 항목은 coin_module.py입니다.

   dags/
     use_local_deps.py  # A DAG file.
     dependencies/
       __init__.py
       coin_module.py
   

2. 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 환경의 안내를 따르세요.

다음 단계

• 패키지 설치 문제 해결
• 업데이트 및 업그레이드 문제 해결