Flex 템플릿 구성

이 페이지에서는 권한, 필수 Dockerfile 환경 변수, Dataflow Flex 템플릿에 지원되는 파이프라인 옵션에 대한 정보를 제공합니다.

샘플 Flex 템플릿을 구성하려면 Flex 템플릿 튜토리얼을 참조하세요.

Flex 템플릿 권한 이해

Flex 템플릿을 사용하는 경우, 다음 세 가지 권한 집합이 있습니다.

  • 리소스를 만들 수 있는 권한
  • Flex 템플릿을 빌드할 권한
  • Flex 템플릿을 실행할 수 있는 권한

리소스를 만들 수 있는 권한

Flex 템플릿 파이프라인을 개발하고 실행하려면 다양한 리소스(예: 스테이징 버킷)를 만들어야 합니다. 일회성 리소스 생성 작업에는 기본 소유자 역할을 사용할 수 있습니다.

Flex 템플릿을 빌드할 권한

Flex 템플릿의 개발자는 사용자가 Flex 템플릿을 사용할 수 있도록 템플릿을 빌드해야 합니다. 빌드에는 템플릿 사양을 Cloud Storage 버킷에 업로드하고 파이프라인을 실행하는 데 필요한 코드와 종속 항목으로 Docker 이미지를 프로비저닝하는 작업이 포함됩니다. Flex 템플릿을 빌드하려면 Cloud Storage에 대한 읽기 및 쓰기 권한과 Container Registry에 대한 읽기 및 쓰기 권한이 있어야 합니다. 다음 역할을 할당하여 권한을 부여할 수 있습니다.

  • 스토리지 관리자(roles/storage.admin)
  • Cloud Build 편집자(roles/cloudbuild.builds.editor)

참고: Artifact Registry를 사용하여 이미지를 저장할 수도 있습니다. Artifact Registry 권한에 대한 자세한 내용은 액세스 제어 구성을 참조하세요.

Flex 템플릿을 실행할 수 있는 권한

Flex 템플릿을 실행하면 Dataflow가 자동으로 작업을 만듭니다. 작업을 만들려면 Dataflow 서비스 계정에 다음 권한이 필요합니다.

  • dataflow.serviceAgent

Dataflow를 처음 사용할 때 서비스가 자동으로 이 역할을 할당하므로 위의 권한을 부여하는 데 필요한 작업이 없습니다.

기본적으로 Compute Engine 서비스 계정은 런처 VM 및 작업자 VM에 사용됩니다. 서비스 계정에는 다음과 같은 역할 및 기능이 필요합니다.

  • 스토리지 객체 관리자(roles/storage.objectAdmin)
  • 뷰어(roles/viewer)
  • Dataflow 작업자(roles/dataflow.worker)
  • 스테이징 버킷에 대한 읽기 및 쓰기 권한
  • Flex 템플릿 이미지에 대한 읽기 권한입니다.

스테이징 버킷에 대한 읽기 및 쓰기 권한을 부여하려면 스토리지 객체 관리자(roles/storage.objectAdmin) 역할을 사용하면 됩니다. 자세한 내용은 Cloud Storage의 IAM 역할을 참조하세요.

Flex 템플릿 이미지에 대한 읽기 권한을 부여하려면 스토리지 객체 뷰어(roles/storage.objectViewer) 역할을 사용하면 됩니다. 자세한 내용은 액세스 제어 구성을 참조하세요.

필요한 Dockerfile 환경 변수 설정

Flex 템플릿 작업에 자체 Docker 파일을 만들려면 다음 환경 변수를 지정해야 합니다.

자바

Dockerfile에서 FLEX_TEMPLATE_JAVA_MAIN_CLASSFLEX_TEMPLATE_JAVA_CLASSPATH를 지정해야 합니다.

ENV 설명 필수
FLEX_TEMPLATE_JAVA_MAIN_CLASS Flex 템플릿을 시작하기 위해 실행할 자바 클래스를 지정합니다.
FLEX_TEMPLATE_JAVA_CLASSPATH 클래스 파일 위치를 지정합니다.
FLEX_TEMPLATE_JAVA_OPTIONS Flex 템플릿을 실행하는 동안 전달할 자바 옵션을 지정합니다. 아니요

Python

Dockerfile에서 FLEX_TEMPLATE_PYTHON_PY_FILE을 지정해야 합니다. 또한 Dockerfile에서 FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE, FLEX_TEMPLATE_PYTHON_PY_OPTIONS, FLEX_TEMPLATE_PYTHON_SETUP_FILE, FLEX_TEMPLATE_PYTHON_EXTRA_PACKAGES를 설정할 수도 있습니다.

예를 들어 Python Flex 템플릿 튜토리얼에서 스트리밍에서 다음 환경 변수를 설정합니다.

ENV FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE="${WORKDIR}/requirements.txt"
ENV FLEX_TEMPLATE_PYTHON_PY_FILE="${WORKDIR}/streaming_beam.py"
ENV 설명 필수
FLEX_TEMPLATE_PYTHON_PY_FILE Flex 템플릿을 시작하기 위해 실행할 Python 파일을 지정합니다.
FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE 시작에 대한 종속 항목을 설치할 요구사항 파일을 지정합니다. FLEX_TEMPLATE_PYTHON_SETUP_FILE을 지정하는 경우 이 변수를 설정하지 마세요. 아니요
FLEX_TEMPLATE_PYTHON_SETUP_FILE 시작에 대한 종속 항목을 설치할 설정 파일을 지정합니다. 설정 파일 사용에 대한 자세한 내용은 여러 파일 종속 항목을 참조하세요. 아니요
FLEX_TEMPLATE_PYTHON_EXTRA_PACKAGES

공개적으로 제공되지 않는 패키지를 지정합니다. 추가 패키지 사용 방법에 대한 자세한 내용은 로컬 또는 비 PyPI 종속 항목을 참조하세요.

아니요
FLEX_TEMPLATE_PYTHON_PY_OPTIONS Flex 템플릿을 실행하는 동안 전달할 Python 옵션을 지정합니다. 아니요

기본 이미지 선택

Google에서 제공하는 기본 이미지를 사용하여 Docker로 템플릿 컨테이너 이미지를 패키징할 수 있습니다. Flex 템플릿 기본 이미지에서 최신 태그를 선택합니다. latest 대신 특정 이미지 태그를 사용하는 것이 좋습니다.

기본 이미지를 다음 형식으로 지정합니다.

gcr.io/dataflow-templates-base/IMAGE_NAME:TAG

다음을 바꿉니다.

커스텀 컨테이너 이미지 사용

파이프라인에서 커스텀 컨테이너 이미지를 사용하는 경우 커스텀 이미지를 Flex 템플릿 Docker 이미지의 기본 이미지로 사용하는 것이 좋습니다. 이렇게 하려면 Google에서 제공하는 템플릿 런처 이미지에서 커스텀 이미지로 Flex 템플릿 런처 바이너리를 복사합니다. 예시 Dockerfile:

FROM gcr.io/dataflow-templates-base/IMAGE_NAME:TAG as template_launcher
FROM USER_CUSTOM_IMAGE

COPY --from=template_launcher /opt/google/dataflow/python_template_launcher /opt/google/dataflow/python_template_launcher

ARG WORKDIR=/dataflow/template
RUN mkdir -p ${WORKDIR}
WORKDIR ${WORKDIR}

COPY streaming_beam.py .

ENV FLEX_TEMPLATE_PYTHON_PY_FILE="${WORKDIR}/streaming_beam.py"

ENTRYPOINT ["/opt/google/dataflow/python_template_launcher"]

Flex 템플릿 런처 이미지를 상위 요소로 지정하여 새 Dockerfile을 만들고 맞춤설정을 추가합니다. Dockerfile 작성에 대한 자세한 내용은 Dockerfile 작성 권장사항을 참조하세요. 자세한 내용은 커스텀 컨테이너 사용 가이드를 참조하세요.

다음을 바꿉니다.

  • IMAGE_NAME: Google에서 제공하는 런처 이미지. 바이너리는 Debian GNU/Linux 운영체제용으로 빌드되었습니다.
  • TAG: Flex 템플릿 런처 이미지 참조에 있는 런처 이미지의 버전 이름, 안정성을 높이고 문제를 해결하려면 latest를 사용하지 말고 특정 버전 태그에 고정합니다.
  • USER_CUSTOM_IMAGE: 커스텀 컨테이너 이미지

파이프라인 옵션 지정

Flex 템플릿에서 직접 지원하는 파이프라인 옵션에 대한 자세한 내용은 파이프라인 옵션을 참조하세요.

모든 Apache Beam 파이프라인 옵션을 간접적으로 사용할 수도 있습니다. Flex 템플릿 작업에 metadata.json 파일을 사용하는 경우 파일에 다음 파이프라인 옵션을 포함합니다. 이 메타데이터 파일은 TemplateMetadata의 형식을 따라야 합니다. metadata.json 파일 예시는 SQL Flex 템플릿 샘플 스트리밍을 참조하세요.

그렇지 않으면 Flex 템플릿 작업을 시작할 때 매개변수 필드를 사용하여 파이프라인 옵션을 전달합니다.

API

parameters 필드를 사용하여 파이프라인 옵션을 포함합니다.

gcloud

parameters 플래그를 사용하여 파이프라인 옵션을 포함합니다.

List 또는 Map 유형의 매개변수를 전달할 경우 YAML 파일의 매개변수를 정의하고 flags-file를 사용해야 할 수 있습니다. 이 방식의 예시는 이 솔루션의 '매개변수로 파일 만들기...' 단계를 참조하세요.

다음 단계

  • 기본 및 Flex 템플릿과 사용 사례 시나리오에 대한 자세한 내용은 Dataflow 템플릿을 참조하세요.
  • Flex 템플릿 문제 해결 정보는 일반적인 오류 안내를 참조하세요.
  • Google Cloud에 대한 참조 아키텍처, 다이어그램, 튜토리얼, 권장사항을 살펴보세요. Cloud 아키텍처 센터 살펴보기