Dataflow에서 커스텀 컨테이너 사용

이 페이지에서는 커스텀 컨테이너 이미지를 제공하여 Dataflow 파이프라인에서 Python 사용자 코드의 런타임 환경을 맞춤설정하는 방법을 설명합니다. 커스텀 컨테이너는 Dataflow Runner v2를 사용하는 이동식 파이프라인에만 지원됩니다.

Dataflow는 작업자 VM을 시작할 때 Docker 컨테이너 이미지를 사용합니다. 기본 Apache Beam 이미지 중 하나를 사용하는 대신 커스텀 컨테이너 이미지를 지정할 수 있습니다. 커스텀 컨테이너 이미지를 지정하면 Dataflow는 지정된 이미지를 가져오는 작업자를 실행합니다. 커스텀 컨테이너를 사용하는 이유는 다음과 같습니다.

  • 파이프라인 종속 항목을 사전 설치하여 작업자 시작 시간 단축
  • 파이프라인 종속 항목을 사전 저장소에서 사용할 수 없음
  • 백그라운드에서 타사 소프트웨어 실행
  • 실행 환경 맞춤설정

커스텀 컨테이너에 대한 상세 설명은 Apache Beam 커스텀 컨테이너 가이드를 참조하세요.

시작하기 전에

Apache Beam SDK 버전 2.25.0 이상이 설치되어 있는지 확인합니다. 이 Apache Beam SDK 버전이 Python 버전을 지원하는지 확인합니다. 자세한 내용은 Apache Beam SDK 설치 가이드를 참조하세요.

컨테이너 이미지를 로컬로 테스트하려면 Docker가 설치되어 있는지 확인하세요. 자세한 내용은 Docker 가져오기를 참조하세요.

컨테이너 이미지 만들기 및 빌드

이 예시에서는 Apache Beam SDK 버전 2.25.0과 함께 Python 3.8을 사용합니다. 커스텀 컨테이너 이미지를 만들려면 Apache Beam 이미지를 상위 이미지로 지정하고 맞춤설정을 추가합니다.

  1. Dockerfile을 만들어 apache/beam_python3.8_sdk:2.25.0을 상위 항목으로 지정하고 맞춤설정을 추가합니다. Dockerfile 작성에 대한 자세한 내용은 Dockerfiles 작성을 위한 권장사항을 참조하세요.
    FROM apache/beam_python3.8_sdk:2.25.0
    # Make your customizations here, for example:
    ENV FOO=/bar
    COPY path/to/myfile ./
  2. 하위 이미지를 빌드하고 Container Registry에 푸시합니다.

    Cloud Build

    export PROJECT=PROJECT
    export REPO=REPO
    export TAG=TAG
    export REGISTRY_HOST=HOST
    export IMAGE_URI=$REGISTRY_HOST/$PROJECT/$REPO:$TAG
    
    gcloud builds submit --tag $IMAGE_URI

    Docker

    export PROJECT=PROJECT
    export REPO=REPO
    export TAG=TAG
    export REGISTRY_HOST=HOST
    export IMAGE_URI=$REGISTRY_HOST/$PROJECT/$REPO:$TAG
    
    docker build -f Dockerfile -t $IMAGE_URI ./
    docker push $IMAGE_URI
    다음을 바꿉니다.
    • PROJECT: 프로젝트 이름 또는 사용자 이름
    • REPO: 이미지 저장소 이름
    • TAG: 이미지 태그
    • HOST: 이미지 레지스트리 호스트 이름(예: gcr.io)

커스텀 컨테이너를 사용하여 작업 실행

파이프라인을 실행할 때는 예기치 않은 오류가 발생하지 않도록 커스텀 컨테이너 이미지에 포함된 것과 동일한 Python 버전과 Apache Beam SDK 버전을 사용합니다.

로컬에서 테스트

PortableRunner를 사용해서 Apache Beam wordcount 예시를 실행하여 컨테이너 이미지를 로컬에서 테스트합니다.

python -m apache_beam.examples.wordcount \
  --input=INPUT_FILE \
  --output=OUTPUT_FILE \
  --runner=PortableRunner \
  --job_endpoint=embed \
  --environment_type=DOCKER \
  --environment_config=$IMAGE_URI

다음을 바꿉니다.

  • INPUT_FILE: 텍스트 파일로 읽을 수 있는 입력 파일. 컨테이너 이미지 또는 원격 파일에 미리 로드된
    SDK 하네스 컨테이너 이미지가 이 파일에 액세스할 수 있어야 합니다.
  • OUTPUT_FILE: 출력을 쓸 파일 경로. 이 경로는 원격 경로 또는 컨테이너의 로컬 경로입니다.
  • $IMAGE_URI: 커스텀 컨테이너 이미지 URI. 변수가 여전히 범위 내에 있는 경우 이전 단계에서 구성된 셸 변수 $IMAGE_URI를 사용할 수 있습니다.

파이프라인이 성공적으로 완료되면 콘솔 로그를 보고 파이프라인이 성공적으로 완료되었는지, $IMAGE_URI로 지정된 원격 이미지가 사용되었는지 확인합니다.

이 로컬 테스트는 실제 컨테이너 이미지 자체를 확인하기 위한 것입니다. 이 단계를 수행하기 전에 컨테이너 이미지 없이 예를 들어 DirectRunner 사용하여 파이프라인 자체를 확인해야 합니다. 컨테이너의 격리된 특성으로 인해 로컬 파일 시스템과 환경 변수와 같은 로컬 구성에 액세스할 수 없습니다.

즉, 애플리케이션 기본 사용자 인증 정보 설정에 사용되는 것과 같은 로컬 입력 파일이나 사용자 인증 정보 파일 및 로컬 환경 변수는 컨테이너 자체에서 액세스할 수 없습니다. 로컬 출력은 컨테이너 파일 시스템에 기록되며 컨테이너가 종료되고 파이프라인이 완료된 후에는 액세스할 수 없습니다.

이러한 출력을 유지해야 하는 경우 원격 파일 시스템을 출력 경로로 제공하고 이 원격 파일 시스템에 대한 액세스가 컨테이너 자체에 설정되어 있는지 확인합니다. 임시 로깅을 추가하면 디버깅 용도로도 충분할 수 있습니다.

자세한 내용은 커스텀 컨테이너 이미지를 사용하여 파이프라인 실행에 대한 Apache Beam 가이드를 참조하세요.

Dataflow 작업 실행

Dataflow에서 Apache Beam 파이프라인을 시작할 때 컨테이너 이미지 경로를 지정합니다. 일괄 Python 파이프라인을 실행하는 경우 --experiment=use_runner_v2 플래그를 설정해야 합니다. 스트리밍 Python 파이프라인을 실행하는 경우 실험을 지정할 필요가 없습니다. 예를 들어 커스텀 컨테이너 이미지로 일괄 wordcount 예시를 실행하려면 다음 안내를 따르세요.

python -m apache_beam.examples.wordcount \
  --input=INPUT_FILE \
  --output=OUTPUT_FILE \
  --project=PROJECT_ID \
  --region=REGION \
  --temp_location=TEMP_LOCATION \
  --runner=DataflowRunner \
  --experiment=use_runner_v2 \
  --worker_harness_container_image=$IMAGE_URI

다음을 바꿉니다.

  • INPUT_FILE: 예시를 실행할 때 Dataflow가 읽은 Cloud Storage 입력 파일 경로
  • OUTPUT_FILE: 예시 파이프라인에서 기록한 Cloud Storage 출력 파일 경로. 여기에는 단어 수가 포함됩니다.
  • PROJECT_IDGoogle Cloud 프로젝트의 ID
  • REGION: Dataflow 작업을 배포하기 위한 리전 엔드포인트
  • TEMP_LOCATION - 파이프라인 실행 중에 생성된 임시 작업 파일을 스테이징할 Dataflow의 Cloud Storage 경로
  • $IMAGE_URI: 커스텀 컨테이너 이미지 URI. 변수가 여전히 범위 내에 있는 경우 이전 단계에서 구성된 셸 변수 $IMAGE_URI를 사용할 수 있습니다.

문제 해결

이 섹션에서는 Dataflow의 커스텀 컨테이너와 상호작용할 때 일반적으로 발생하는 문제를 해결하는 방법을 안내합니다.

지원팀에 문의하기 전에 로컬 테스트 및 다음 문제 해결 섹션의 안내에 따라 컨테이너 이미지와 관련된 문제를 제외했는지 확인하세요.

컨테이너 로그 찾기

컨테이너 로그 오류 메시지에 대한 Dataflow 작업자 로그는 로그 탐색기를 사용하여 찾을 수 있습니다.

  1. 다음 로그 이름을 선택합니다.

    • dataflow.googleapis.com/docker
    • dataflow.googleapis.com/kubelet
    • dataflow.googleapis.com/worker
  2. Dataflow Step 리소스를 선택하고 job_id를 지정합니다.

작업자가 시작되지 않음

작업자가 시작되지 않거나 작업이 시간 초과되면 Dataflow가 커스텀 컨테이너 이미지를 가져올 수 있는지 확인합니다.

다음 쿼리와 함께 로그 탐색기를 사용하여 로그 메시지 Error Syncing pod...를 사용하여 Dataflow 로그를 쿼리합니다.

resource.type="dataflow_step" AND jsonPayload.message:("$IMAGE_URI") AND severity="ERROR"

시작 시 작업자가 이미지를 가져올 수 있도록 Dataflow 작업자가 이미지에 액세스할 수 있어야 합니다. Container Registry를 사용하여 컨테이너 이미지를 호스팅하는 경우 기본 Google Cloud 서비스 계정은 이미 동일한 프로젝트의 이미지에 액세스할 수 있습니다. Dataflow가 컨테이너 이미지를 가져올 수 없는 경우 작업자는 시작할 수 없습니다.

자세한 내용은 애플리케이션 액세스 제어 구성하기를 참조하세요.