Dataflow에서 파이프라인 종속 항목 관리

많은 Apache Beam 파이프라인은 기본 Dataflow 런타임 환경을 사용하여 실행할 수 있습니다. 그러나 일부 데이터 처리 사용 사례에서는 추가 라이브러리나 클래스를 사용하는 이점을 얻을 수 있습니다. 이러한 경우 파이프라인 종속 항목을 관리해야 할 수 있습니다.

다음 목록은 파이프라인 종속 항목을 관리해야 할 수 있는 몇 가지 이유를 제공합니다.

기본 런타임 환경에서 제공하는 종속 항목은 사용 사례에 충분하지 않습니다.
기본 종속 항목에 버전 충돌이 있거나 파이프라인 코드와 호환되지 않는 클래스 및 라이브러리가 있습니다.
파이프라인의 특정 라이브러리 버전으로 고정해야 합니다.
일관된 종속 항목 집합을 사용하여 실행해야 하는 Python 파이프라인이 있습니다.

종속 항목 관리 방법은 파이프라인이 Java, Python, Go중 어떤 것을 사용하는지에 따라 다릅니다.

자바

호환되지 않는 클래스 및 라이브러리는 Java 종속 항목 문제를 일으킬 수 있습니다. 파이프라인에 사용자별 코드 및 설정이 포함된 경우 코드에 라이브러리의 여러 버전을 포함할 수 없습니다.

Java 종속 항목 문제

파이프라인에 Java 종속 항목 문제가 있으면 다음 오류 중 하나가 발생할 수 있습니다.

NoClassDefFoundError: 이 오류는 런타임 중에 전체 클래스를 사용할 수 없을 때 발생합니다.
NoSuchMethodError: 이 오류는 클래스 경로의 클래스가 올바른 메서드를 포함하지 않는 버전을 사용하거나 메서드 서명이 변경되었을 때 발생합니다.
NoSuchFieldError: 이 오류는 클래스 경로의 클래스가 런타임 중에 필수 필드가 없는 버전을 사용할 때 발생합니다.
FATAL ERROR: 이 오류는 기본 제공 종속 항목을 제대로 로드할 수 없을 때 발생합니다. Uber JAR 파일(음영 처리)을 사용할 때는 Conscrypt와 같이 동일한 JAR 파일에 서명을 사용하는 라이브러리를 포함하지 마세요.

종속 항목 관리

Java 파이프라인의 종속 항목 관리를 단순화하기 위해 Apache Beam은 재료명세서(BOM) 아티팩트를 사용합니다. BOM은 종속 항목 관리 도구가 호환되는 종속 항목 조합을 선택하는 데 도움이 됩니다. 자세한 내용은 Apache Beam 문서의 Java용 Apache Beam SDK 종속 항목을 참조하세요.

파이프라인에 BOM을 사용하고 종속 항목 목록에 다른 종속 항목을 명시적으로 추가하려면 SDK 아티팩트의 pom.xml 파일에 다음 정보를 추가합니다. 올바른 라이브러리 BOM을 가져오려면 beam-sdks-java-io-google-cloud-platform-bom을 사용합니다.

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.apache.beam</groupId>
      <artifactId>beam-sdks-java-google-cloud-platform-bom</artifactId>
      <version>LATEST</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
    <groupId>org.apache.beam</groupId>
    <artifactId>beam-sdks-java-core</artifactId>
  </dependency>
  <dependency>
    <groupId>org.apache.beam</groupId>
    <artifactId>beam-runners-google-cloud-dataflow-java</artifactId>
  </dependency>
  <dependency>
    <groupId>org.apache.beam</groupId>
    <artifactId>beam-sdks-java-io-google-cloud-platform</artifactId>
  </dependency>
</dependencies>

beam-sdks-java-core 아티팩트에는 핵심 SDK만 포함됩니다. I/O 및 러너와 같은 다른 종속 항목을 종속 항목 목록에 명시적으로 추가해야 합니다.

Python

Apache Beam Python SDK를 사용하여 Dataflow 작업을 실행하면 다음 시나리오에서 종속 항목 관리가 유용합니다.

파이프라인이 Python 패키지 색인(PiPy)의 공개 패키지를 사용하며 이 패키지를 원격으로 사용할 수 있도록 하려고 합니다.
재현 가능한 환경을 만들어야 합니다.
시작 시간을 줄이기 위해 런타임 시 작업자에 대한 종속 항목 설치를 피하는 것이 좋습니다.

Python 파이프라인 종속 항목 정의

단일 Python 스크립트 또는 노트북을 사용하여 Apache Beam 파이프라인을 작성할 수 있지만 Python 생태계에서 소프트웨어가 패키지로 배포되는 경우가 많습니다. 파이프라인을 더 쉽게 유지보수할 수 있도록 파이프라인 코드가 여러 파일에 걸쳐 있는 경우 파이프라인 파일을 Python 패키지로 그룹화합니다.

패키지의 setup.py 파일에서 파이프라인의 종속 항목을 정의합니다.
--setup_file 파이프라인 옵션을 사용하여 패키지를 작업자에게 스테이징합니다.

원격 작업자가 시작되면 패키지를 설치합니다. 예시를 보려면 Apache Beam GitHub에서 juliaset를 참조하세요.

파이프라인을 Python 패키지로 구조화하려면 다음 단계를 따르세요.

프로젝트의 setup.py 파일을 만듭니다. setup.py 파일에 install_requires 인수를 포함하여 파이프라인의 최소 종속 항목 집합을 지정합니다. 다음 예시에서는 기본 setup.py 파일을 보여줍니다.
```
import setuptools

setuptools.setup(
  name='PACKAGE_NAME',
  version='PACKAGE_VERSION',
  install_requires=[],
  packages=setuptools.find_packages(),
)
```
setup.py 파일, 기본 워크플로 파일, 나머지 파일이 포함된 디렉터리를 프로젝트의 루트 디렉터리에 추가합니다. 이 파일 그룹화는 파이프라인의 Python 패키지입니다. 파일 구조는 다음 예시와 같습니다.
```
root_dir/
  package_name/
    my_pipeline_launcher.py
    my_custom_transforms.py
    ...other files...
  setup.py
  main.py
```
파이프라인을 실행하려면 제출 환경에 패키지를 설치합니다. --setup_file 파이프라인 옵션을 사용하여 패키지를 작업자에게 스테이징합니다. 예를 들면 다음과 같습니다.
```
python -m pip install -e .
python main.py --runner DataflowRunner --setup_file ./setup.py  <...other options...>
```

이러한 단계는 특히 코드의 크기와 복잡성이 증가하면 파이프라인 코드 유지보수를 간소화합니다. 종속 항목을 지정하는 다른 방법은 Apache Beam 문서의 Python 파이프라인 종속 항목 관리를 참조하세요.

커스텀 컨테이너를 사용하여 런타임 환경 제어

Apache Beam Python SDK로 파이프라인을 실행하려면 Dataflow 작업자에는 인터프리터, Apache Beam SDK, 파이프라인 종속 항목이 포함된 Python 환경이 필요합니다. Docker 컨테이너 이미지는 파이프라인 코드를 실행하는 데 적합한 환경을 제공합니다.

스톡 컨테이너 이미지는 Apache Beam SDK의 각 버전과 함께 출시되며 이러한 이미지에는 Apache Beam SDK 종속 항목이 포함됩니다. 자세한 내용은 Apache Beam 문서의 Python용 Apache Beam SDK 종속 항목을 참조하세요.

파이프라인에 기본 컨테이너 이미지에 포함되지 않은 종속 항목이 필요한 경우 런타임에 해당 종속 항목을 설치해야 합니다. 런타임에 패키지를 설치하면 다음과 같은 결과가 발생할 수 있습니다.

종속 항목 확인, 다운로드, 설치로 인해 작업자 시작 시간이 증가합니다.
파이프라인을 실행하려면 인터넷에 연결해야 합니다.
비결정성은 종속 항목의 소프트웨어 출시 버전으로 인해 발생합니다.

이러한 문제를 방지하려면 커스텀 Docker 컨테이너 이미지에서 런타임 환경을 제공합니다. 파이프라인 종속 항목이 사전 설치된 커스텀 Docker 컨테이너 이미지를 사용하면 다음과 같은 이점이 있습니다.

Dataflow 작업을 시작할 때마다 파이프라인 런타임 환경에 동일한 종속 항목 집합이 포함되는지 확인합니다.
파이프라인의 런타임 환경을 제어할 수 있습니다.
시작 시 잠재적으로 시간이 오래 걸리는 종속 항목 확인을 방지합니다.

커스텀 컨테이너 이미지를 사용할 때는 다음 안내를 고려하세요.

:latest 태그와 커스텀 이미지를 사용하지 마세요. 날짜, 버전, 또는 고유 식별자로 빌드에 태그를 지정합니다. 이 단계를 사용하면 필요한 경우 알려진 작동 구성으로 되돌릴 수 있습니다.
컨테이너 이미지와 호환되는 실행 환경을 사용합니다. 커스텀 컨테이너 사용에 대한 자세한 안내는 컨테이너 이미지 빌드를 참조하세요.

Python 종속 항목 사전 설치에 대한 자세한 내용은 Python 종속 항목 사전 설치를 참조하세요.

Dataflow 템플릿으로 실행 환경 제어

파이프라인에 추가 종속 항목이 필요한 경우 런타임 환경과 실행 환경 모두에 설치해야 할 수도 있습니다. 출시 환경은 파이프라인의 프로덕션 버전을 실행합니다. 실행 환경은 런타임 환경과 호환되어야 하므로 두 환경 모두에 동일한 버전의 종속 항목을 사용합니다.

컨테이너화되고 재현 가능한 실행 환경을 만들려면 Dataflow Flex 템플릿을 사용합니다. 자세한 내용은 Flex 템플릿 빌드 및 실행을 참조하세요. Flex 템플릿을 사용할 때는 다음 요소를 고려하세요.

파이프라인을 패키지로 구성하는 경우 템플릿 Dockerfile에 패키지를 설치합니다. Flex 템플릿을 구성하려면 FLEX_TEMPLATE_PYTHON_SETUP_FILE을 지정합니다. 자세한 내용은 필요한 Dockerfile 환경 변수 설정을 참조하세요.
파이프라인에서 커스텀 컨테이너 이미지를 사용하는 경우 템플릿을 실행할 때 이 이미지를 제공합니다. 자세한 내용은 종속 항목에 커스텀 컨테이너 사용을 참조하세요.
Dataflow Flex 템플릿 Docker 이미지를 빌드하려면 기본 이미지와 동일한 커스텀 컨테이너 이미지를 사용합니다. 자세한 내용은 커스텀 컨테이너 이미지 사용을 참조하세요.

이 구조에서는 출시 환경을 재현 가능하고 런타임 환경과 호환되도록 합니다.

이 방식을 따르는 예시는 GitHub의 종속 항목 및 커스텀 컨테이너가 있는 파이프라인의 Flex 템플릿 튜토리얼을 참조하세요.

자세한 내용은 Apache Beam 문서에서 실행 환경을 런타임 환경과 호환되도록 만들기 및 파이프라인에서 사용하는 종속 항목 제어를 참조하세요.

Go

Apache Beam Go SDK를 사용하여 Dataflow 작업을 실행하면 Go 모듈을 사용하여 종속 항목을 관리합니다. 다음 파일에는 파이프라인에서 사용하는 기본 컴파일 및 런타임 종속 항목이 포함되어 있습니다.

https://raw.githubusercontent.com/apache/beam/vVERSION_NUMBER/sdks/go.sum

VERSION_NUMBER를 사용 중인 SDK 버전으로 바꿉니다.

Go 파이프라인의 종속 항목 관리에 대한 자세한 내용은 Go 문서의 종속 항목 관리를 참조하세요.