Python 종속 항목 설치

Cloud Composer 1 | Cloud Composer 2

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

사전 설치된 및 커스텀 PyPI 패키지 정보

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

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

Python 패키지 관리 옵션

옵션 사용 가능한 경우
PyPI에서 설치 패키지에 외부 종속 항목이 없고 Cloud Composer 종속 항목과 충돌하지 않습니다.
비공개 저장소에서 설치 패키지가 인터넷에서 사용할 수 있는 비공개 패키지 저장소에 호스팅되어 있습니다.
로컬 Python 라이브러리로 설치 Python 패키지 색인에서 패키지를 찾을 수 없고 라이브러리에 dist-packages와 같은 외부 종속 항목이 없습니다.
플러그인 설치 패키지가 Airflow 웹 인터페이스 수정과 같은 플러그인 관련 기능을 제공합니다.
PythonVirtualenvOperator 모든 작업자에 대해 패키지를 설치하지 않거나 종속 항목이 사전 설치된 패키지와 충돌합니다. 패키지를 Python 패키지 색인에서 찾을 수 있고 외부 종속 항목이 없습니다.
KubernetesPodOperator pip에서 설치할 수 없는 외부 종속 항목(예: dist-packages)이 필요하거나 내부 pip 서버를 사용 중인 경우 이 옵션은 추가 설정 및 유지보수 작업이 필요하며, 일반적으로 다른 옵션이 적용되지 않는 경우에만 고려해야 합니다.

시작하기 전에

  • 환경 업데이트 작업을 트리거할 수 있는 역할이 필요합니다. 또한 해당 환경의 서비스 계정에 업데이트 작업을 수행하는 데 충분한 권한이 있는 역할이 있어야 합니다. 자세한 내용은 액세스 제어를 참조하세요.
  • VPC 서비스 제어 경계가 환경을 보호하고 있다면 PyPI 종속 항목을 설치하기 전에 서비스 경계가 보호하는 서비스에 대한 액세스 권한이 있는 추가 사용자 ID를 부여하고 비공개 PyPI 저장소에 대한 지원을 사용 설정해야 합니다.
  • 요구사항은 PEP-508에 지정된 형식을 따라야 합니다. 여기에는 각 요구사항이 소문자로 지정되어 있고, 패키지 이름과 선택적 추가 기능 및 버전 지정자로 구성되어 있습니다.
  • PyPI 종속 항목을 업데이트하면 Artifact Registry에 Docker 이미지가 생성됩니다. 이미지를 수정하거나 삭제하지 마세요.
  • 종속 항목 충돌로 인해 업데이트가 실패하게 되면 사용자 환경이 기존 종속 항목으로 계속 실행됩니다. 작업이 성공하면 DAG에서 새로 설치된 Python 종속 항목을 사용할 수 있습니다.

패키지 목록 보기

여러 형식으로 환경의 패키지 목록을 가져올 수 있습니다.

사전 설치된 패키지

환경의 사전 설치된 패키지 목록을 보려면 환경의 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 패키지

Console

  1. Google Cloud Console에서 환경 페이지로 이동합니다.

    환경으로 이동

  2. 환경 목록에서 환경 이름을 클릭합니다. 환경 세부정보 페이지가 열립니다.

  3. PYPI 패키지 탭으로 이동합니다.

gcloud

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

다음과 같이 바꿉니다.

  • ENVIRONMENT_NAME을 환경 이름으로 바꿉니다.
  • LOCATION을 환경이 위치한 리전으로 바꿉니다.

PyPI에서 패키지 설치

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

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

Console

  1. Google Cloud Console에서 환경 페이지로 이동합니다.

    환경으로 이동

  2. 환경 목록에서 환경 이름을 클릭합니다. 환경 세부정보 페이지가 열립니다.

  3. 환경 구성 탭으로 이동합니다.

  4. 수정을 클릭합니다.

  5. 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 요청을 생성합니다.

이 요청의 작성 방법:

  1. updateMask 매개변수에서 마스크를 지정합니다.

    • config.softwareConfig.pypiPackages 마스크를 사용하여 모든 기존 패키지를 지정된 패키지로 바꿉니다. 지정하지 않은 패키지는 삭제됩니다.
    • config.softwareConfig.envVariables.PACKAGE_NAME을 사용하여 특정 패키지를 추가하거나 업데이트합니다. 여러 패키지를 추가하거나 업데이트하려면 쉼표를 사용해 여러 마스크를 지정합니다.
  2. 요청 본문에서 패키지와 버전 및 추가 항목의 값을 지정합니다.

    {
      "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 블록의 env_variables 블록은 환경 변수를 지정합니다.

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

  config {

    software_config {

      env_variables = {
        VAR_NAME = "VAR_VALUE"
      }

    }
  }
}

다음과 같이 바꿉니다.

  • ENVIRONMENT_NAME을 환경 이름으로 바꿉니다.
  • LOCATION을 환경이 위치한 리전으로 바꿉니다.
  • VAR_NAME을 환경 변수의 이름으로 바꿉니다.
  • VAR_VALUE를 환경 변수 값으로 바꿉니다.
  • 변수를 두 개 이상 추가하려면 env_variables에 변수 항목을 더 추가합니다.

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

resource "google_composer_environment" "example" {
  provider = google-beta
  name = "example-environment"
  region = "us-central1"

  config {

      env_variables = {
        EXAMPLE_VARIABLE = "True"
        ANOTHER_VARIABLE = "test"
      }

  }
}

비공개 저장소에서 설치

공개 인터넷에서 사용할 수 있는 패키지 저장소에 호스팅된 패키지를 설치할 수 있습니다.

기본 pip 도구로 패키지를 설치할 수 있도록 패키지를 적절하게 구성해야 합니다.

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

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

    • 저장소 URL
    • 저장소에 대한 액세스 사용자 인증 정보
    • 기본이 아닌 pip 설치 옵션

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

    [global]
    extra-index-url=https://example.com/
    
  2. 이 pip.conf 파일을 환경 버킷의 /config/pip/ 폴더에 업로드합니다. 예를 들면 gs://us-central1-example-bucket/config/pip/pip.conf입니다.

비공개 IP 환경에 설치

비공개 IP 환경은 공개 인터넷 액세스를 제한하므로 Python 종속 항목을 설치하려면 추가 단계가 필요할 수 있습니다.

PyPI 저장소에서 종속 항목을 설치할 때는 특별한 구성이 필요하지 않습니다. PyPI에서 패키지 설치에 설명된 절차를 따릅니다. 공개 주소가 있는 비공개 저장소에서 패키지를 요청할 수도 있습니다.

또는 프로젝트 네트워크에서 비공개 PyPI 저장소를 호스팅할 수 있습니다. 종속 항목을 설치할 때 Cloud Composer는 Cloud Build를 통해 공개 IP 주소에 액세스하지 않고 환경을 호스팅하는 클러스터 내에서 작업을 실행합니다.

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

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

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

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

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

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

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

리소스 위치 제한 요구사항에 따라 프로젝트를 유지하면 일부 도구를 사용할 수 없습니다. 특히 Cloud Build를 패키지 설치에 사용할 수 없어서, 공개 인터넷의 저장소에 대한 직접 액세스가 방지됩니다.

이러한 환경에 Python 종속 항목을 설치하려면 VPC 서비스 제어 경계가 있는 비공개 IP 환경에 대한 안내를 따릅니다.

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

VPC 서비스 제어 매개변수로 프로젝트를 보호하면 보안 제한 사항이 추가됩니다. 특히 Cloud Build를 패키지 설치에 사용할 수 없어서, 공개 인터넷의 저장소에 대한 직접 액세스가 방지됩니다.

경계 내에서 비공개 IP 환경에 대해 Python 종속 항목을 설치하려면 다음을 수행합니다.

  • VPC 네트워크에서 호스팅되는 비공개 PyPI 저장소를 사용합니다.
  • VPC 네트워크의 프록시 서버 VM을 사용하여 공개 인터넷의 PyPI 저장소에 연결합니다. 환경 버킷의 /config/pip/pip.conf 파일에 프록시 주소를 지정합니다.
  • 보안 정책에 따라 외부 IP 주소로부터 VPC 네트워크에 액세스가 허용되는 경우 Cloud NAT를 구성하여 이를 사용 설정할 수 있습니다.
  • Python 종속 항목을 Cloud Storage 버킷의 dags 폴더에 배치하여 로컬 라이브러리로 설치합니다. 종속 항목 트리가 클 때는 좋은 방법이 아닐 수 있습니다.

로컬 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

다음 단계