Flex 템플릿 구성

이 페이지에서는 다음을 포함한 다양한 Dataflow Flex 템플릿 구성 옵션을 설명합니다.

권한
Dockerfile 환경 변수
패키지 종속 항목
Docker 이미지
파이프라인 옵션
스테이징 및 임시 위치

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

Flex 템플릿 권한 이해

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

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

리소스를 만들 수 있는 권한

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

Flex 템플릿을 빌드할 권한

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

스토리지 관리자(roles/storage.admin)
Cloud Build 편집자(roles/cloudbuild.builds.editor)
Artifact Registry 작성자(roles/artifactregistry.writer)

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 템플릿 작업에 자체 Dockerfile을 만들려면 다음 환경 변수를 지정합니다.

자바

Dockerfile에서 FLEX_TEMPLATE_JAVA_MAIN_CLASS 및 FLEX_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

예를 들어 다음 환경 변수는 GitHub의 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`	파이프라인 종속 항목이 있는 요구사항 파일을 지정합니다. 자세한 내용은 Apache Beam 문서에서 PyPI 종속 항목을 참조하세요.	아니요
`FLEX_TEMPLATE_PYTHON_SETUP_FILE`	파이프라인 패키지 `setup.py` 파일의 경로를 지정합니다. 자세한 내용은 Apache Beam 문서의 여러 파일 종속 항목을 참조하세요.	아니요
`FLEX_TEMPLATE_PYTHON_EXTRA_PACKAGES`	공개적으로 제공되지 않는 패키지를 지정합니다. 추가 패키지 사용 방법에 대한 자세한 내용은 로컬 또는 비 PyPI 종속 항목을 참조하세요.	아니요
`FLEX_TEMPLATE_PYTHON_PY_OPTIONS`	Flex 템플릿을 실행하는 동안 전달할 Python 옵션을 지정합니다.	아니요

패키지 종속 항목

Dataflow Python 파이프라인에 추가 종속 항목이 사용될 때는 Dataflow 작업자 VM에서 추가 종석 항목을 설치하도록 Flex 템플릿을 구성해야 할 수 있습니다.

인터넷 액세스가 제한되는 환경에서 Flex 템플릿을 사용하는 Python Dataflow 작업을 실행할 경우 템플릿을 만들 때 종속 항목을 미리 패키징해야 합니다.

다음 옵션 중 하나를 사용하여 Python 종속 항목을 미리 패키징합니다.

Java 및 Go 파이프라인에서 파이프라인 종속 항목을 관리하는 방법은 Dataflow에서 파이프라인 종속 항목 관리를 참조하세요.

요구사항 파일을 사용하고 템플릿으로 종속 항목 미리 패키징

자체 Dockerfile을 사용하여 Flex 템플릿 이미지를 정의하는 경우 다음 단계를 수행합니다.

파이프라인 종속 항목을 나열하는 requirements.txt 파일을 만듭니다.

COPY requirements.txt /template/
ENV FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE="/template/requirements.txt"

Flex 템플릿 이미지에 종속 항목을 설치합니다.

RUN pip install --no-cache-dir -r $FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE

템플릿이 실행될 때 Dataflow 작업자로 스테이징되는 로컬 요구사항 캐시로 종속 항목을 다운로드합니다.
```
RUN pip download --no-cache-dir --dest /tmp/dataflow-requirements-cache -r $FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE
```

이 방식을 사용하면 requirements.txt 파일의 종속 항목이 런타임 시 Dataflow 작업자에 설치됩니다. Google Cloud 콘솔 추천 탭에 이 동작에 대한 통계가 표시될 수 있습니다. 런타임 시 종속 항목을 설치하지 않으려면 커스텀 컨테이너 이미지를 사용하세요.

다음은 Flex 템플릿에서 요구사항 파일을 사용하는 코드 샘플입니다.

# Copyright 2020 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#    http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

FROM gcr.io/dataflow-templates-base/python3-template-launcher-base

# Configure the Template to launch the pipeline with a --requirements_file option.
# See: https://beam.apache.org/documentation/sdks/python-pipeline-dependencies/#pypi-dependencies
ENV FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE="/template/requirements.txt"
ENV FLEX_TEMPLATE_PYTHON_PY_FILE="/template/streaming_beam.py"

COPY . /template

RUN apt-get update \
    # Install any apt packages if required by your template pipeline.
    && apt-get install -y libffi-dev git \
    && rm -rf /var/lib/apt/lists/* \
    # Upgrade pip and install the requirements.
    && pip install --no-cache-dir --upgrade pip \
    # Install dependencies from requirements file in the launch environment.
    && pip install --no-cache-dir -r $FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE \
    # When FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE  option is used,
    # then during Template launch Beam downloads dependencies
    # into a local requirements cache folder and stages the cache to workers.
    # To speed up Flex Template launch, pre-download the requirements cache
    # when creating the Template.
    && pip download --no-cache-dir --dest /tmp/dataflow-requirements-cache -r $FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE

# Set this if using Beam 2.37.0 or earlier SDK to speed up job submission.
ENV PIP_NO_DEPS=True

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

파이프라인을 패키지로 구성하고 로컬 패키지 사용

여러 Python 로컬 파일이나 모듈을 사용하는 경우 파이프라인을 패키지로 구성합니다. 파일 구조는 다음 예시와 같습니다.

main.py
pyproject.toml
setup.py
src/
  my_package/
    my_custom_dofns_and_transforms.py
    my_pipeline_launcher.py
    other_utils_and_helpers.py

최상위 진입점(예: main.py 파일)을 루트 디렉터리에 배치합니다. 나머지 파일을 src 디렉터리의 별도 폴더(예: my_package)에 배치합니다.

패키지 세부정보 및 요구사항과 함께 패키지 구성 파일을 루트 디렉터리에 추가합니다.

pyproject.toml

[project]
name = "my_package"
version = "package_version"
dependencies = [
  # Add list of packages (and versions) that my_package depends on.
  # Example:
  "apache-beam[gcp]==2.54.0",
]

setup.py

  """An optional setuptools configuration stub for the pipeline package.

  Use pyproject.toml to define the package. Add this file only if you must
  use the --setup_file pipeline option or the
  FLEX_TEMPLATE_PYTHON_SETUP_FILE configuration option.
  """

  import setuptools
  setuptools.setup()

로컬 패키지를 구성하는 방법에 대한 자세한 내용은 Python 프로젝트 패키징을 참조하세요.

파이프라인의 로컬 모듈이나 파일을 가져올 때는 my_package 패키지 이름을 가져오기 경로로 사용합니다.
```
from my_package import word_count_transform
```

Flex 템플릿 이미지에 파이프라인 패키지를 설치합니다. Flex 템플릿 Dockerfile에는 다음 예시와 유사한 콘텐츠가 포함될 수 있습니다.

Dockerfile

ENV FLEX_TEMPLATE_PYTHON_PY_FILE="${WORKDIR}/main.py"
ENV FLEX_TEMPLATE_PYTHON_SETUP_FILE="${WORKDIR}/setup.py"

# Copy pipeline, packages and requirements.
WORKDIR ${WORKDIR}
COPY main.py .
COPY pyproject.toml .
COPY setup.py .
COPY src src

# Install local package.
RUN pip install -e .

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

모든 종속 항목을 사전 설치하는 커스텀 컨테이너 사용

런타임 시 종속 항목을 설치하지 않으려면 커스텀 컨테이너를 사용하세요. 이 옵션은 인터넷에 액세스할 수 없는 환경에서 실행되는 파이프라인에 선호됩니다.

다음 단계에 따라 커스텀 컨테이너를 사용합니다.

필요한 종속 항목을 사전 설치하는 커스텀 컨테이너를 빌드합니다.
Flex 템플릿 Dockerfile에 동일한 종속 항목을 사전 설치합니다.

런타임 시 종속 항목이 설치되지 않게 하려면 Flex 템플릿 구성에서 FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE 또는 FLEX_TEMPLATE_PYTHON_SETUP_FILE 옵션을 사용하지 마세요.

수정된 Flex 템플릿 Dockerfile은 다음 예시와 같이 표시될 수 있습니다.
```
FROM gcr.io/dataflow-templates-base/python3-template-launcher-base
ENV FLEX_TEMPLATE_PYTHON_PY_FILE="/template/main.py"
COPY . /template
# If you use a requirements file, pre-install the requirements.txt.
RUN pip install --no-cache-dir -r /template/requirements.txt
# If you supply the pipeline in a package, pre-install the local package and its dependencies.
RUN pip install -e /template
```
이 방식을 사용할 때 다음을 수행합니다.
- Flex 템플릿 이미지 빌드
- 커스텀 SDK 컨테이너 이미지 빌드
- 두 이미지 모두에 같은 종속 항목 설치
또는 유지할 이미지 수를 줄이려면 커스텀 컨테이너 이미지를 Flex 템플릿의 기본 이미지로 사용합니다.
Apache Beam SDK 버전 2.49.0 이하를 사용하는 경우 파이프라인 런처에 --sdk_location=container 파이프라인 옵션을 추가합니다. 이 옵션은 파이프라인이 SDK를 다운로드하는 대신 커스텀 컨테이너의 SDK를 사용하도록 지정합니다.
```
options = PipelineOptions(beam_args, save_main_session=True, streaming=True, sdk_location="container")
```

flex-template run 명령어에서 sdk_container_image 매개변수를 설정합니다. 예를 들면 다음과 같습니다.

gcloud dataflow flex-template run $JOB_NAME \
   --region=$REGION \
   --template-file-gcs-location=$TEMPLATE_PATH \
   --parameters=sdk_container_image=$CUSTOM_CONTAINER_IMAGE \
   --additional-experiments=use_runner_v2

자세한 내용은 Dataflow에서 커스텀 컨테이너 사용을 참조하세요.

기본 이미지 선택

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

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

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

다음을 바꿉니다.

IMAGE_NAME: Google에서 제공하는 기본 이미지
TAG: Flex 템플릿 기본 이미지 참조에 있는 기본 이미지의 버전 이름

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

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

커스텀 SDK 컨테이너 이미지와 Flex 템플릿으로 사용할 수 있는 이미지의 Dockerfile 예시는 다음과 같습니다.

FROM gcr.io/dataflow-templates-base/IMAGE_NAME:TAG as template_launcher
FROM apache/beam_python3.10_sdk:2.59.0

# RUN <...Make image customizations here...>
# See: https://cloud.google.com/dataflow/docs/guides/build-container-image

# Configure the Flex Template here.
COPY --from=template_launcher /opt/google/dataflow/python_template_launcher /opt/google/dataflow/python_template_launcher
COPY my_pipeline.py /template/
ENV FLEX_TEMPLATE_PYTHON_PY_FILE="/template/my_pipeline.py"

다음을 바꿉니다.

IMAGE_NAME: Google에서 제공하는 기본 이미지 예를 들면 python311-template-launcher-base입니다.
TAG: Flex 템플릿 기본 이미지 참조에 있는 기본 이미지의 버전 태그 더 나은 안정성과 문제 해결을 위해 latest를 사용하지 마세요. 대신 특정 버전 태그에 고정합니다.

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

비공개 레지스트리에 있는 이미지 사용

비공개 레지스트리가 HTTPS를 사용하고 유효한 인증서가 있는 경우, 비공개 Docker 레지스트리에 저장된 Flex 템플릿 이미지를 빌드할 수 있습니다.

비공개 레지스트리의 이미지를 사용하려면 이미지 경로와 레지스트리의 사용자 이름 및 비밀번호를 지정합니다. 사용자 이름과 비밀번호는 Secret Manager에 저장해야 합니다. 다음 형식 중 하나로 보안 비밀을 제공할 수 있습니다.

projects/{project}/secrets/{secret}/versions/{secret_version}
projects/{project}/secrets/{secret}

두 번째 형식을 사용하면 버전을 지정하지 않으므로 Dataflow가 최신 버전을 사용합니다.

레지스트리가 자체 서명된 인증서를 사용하는 경우 Cloud Storage의 자체 서명 인증서 경로도 지정해야 합니다.

다음 표에는 비공개 레지스트리를 구성하는 데 사용할 수 있는 gcloud CLI 옵션이 설명되어 있습니다.

매개변수	설명
`image`	레지스트리의 주소입니다. 예를 들면 `gcp.repository.example.com:9082/registry/example/image:latest`입니다.
`image-repository-username-secret-id`	비공개 레지스트리에 인증할 사용자 이름의 Secret Manager 보안 비밀 ID입니다. 예를 들면 `projects/example-project/secrets/username-secret`입니다.
`image-repository-password-secret-id`	비공개 레지스트리에 인증할 비밀번호의 Secret Manager 보안 비밀 ID입니다. 예를 들면 `projects/example-project/secrets/password-secret/versions/latest`입니다.
`image-repository-cert-path`	비공개 레지스트리의 자체 서명 인증서의 전체 Cloud Storage URL입니다. 이 값은 레지스트리에서 자체 서명 인증서를 사용하는 경우에만 필요합니다. 예를 들면 `gs://example-bucket/self-signed.crt`입니다.

다음은 자체 서명된 인증서가 있는 비공개 레지스트리의 이미지를 사용하여 Flex 템플릿을 빌드하는 Google Cloud CLI 명령어 예시입니다.

gcloud dataflow flex-template build gs://example-bucket/custom-pipeline-private-repo.json
--sdk-language=JAVA
--image="gcp.repository.example.com:9082/registry/example/image:latest"
--image-repository-username-secret-id="projects/example-project/secrets/username-secret"
--image-repository-password-secret-id="projects/example-project/secrets/password-secret/versions/latest"
--image-repository-cert-path="gs://example-bucket/self-signed.crt"
--metadata-file=metadata.json

자체적으로 Flex 템플릿을 빌드하려면 예시 값을 바꿔야 하며 다른 옵션 또는 추가 옵션을 지정해야 할 수도 있습니다. 자세한 내용은 다음 리소스를 참조하세요.

파이프라인 옵션 지정

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

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

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

API

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

gcloud

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

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

Flex 템플릿을 사용할 때는 파이프라인 초기화 중 일부 파이프라인 옵션을 구성할 수 있지만 다른 파이프라인 옵션을 변경할 수 없습니다. Flex 템플릿에 필요한 명령줄 인수를 덮어쓰면 작업이 템플릿 런처로 전달된 파이프라인 옵션을 무시, 재정의, 폐기할 수 있습니다. 작업이 실행되지 않거나 Flex 템플릿을 사용하지 않는 작업이 실행될 수 있습니다. 자세한 내용은 작업 파일 읽기 실패를 참조하세요.

파이프라인을 초기화하는 동안 다음 파이프라인 옵션을 변경하지 마세요.

자바

runner
project
jobName
templateLocation
region

Python

runner
project
job_name
template_location
region

Go

runner
project
job_name
template_location
region

메타데이터 기반 SSH 키를 사용하는 VM에서 프로젝트 SSH 키 차단

VM에서 프로젝트 SSH 키를 차단하여 VM이 프로젝트 메타데이터에 저장된 SSH 키를 허용하지 않도록 할 수 있습니다. additional-experiments 플래그를 block_project_ssh_keys 서비스 옵션과 함께 사용합니다.

--additional-experiments=block_project_ssh_keys

자세한 내용은 Dataflow 서비스 옵션을 참조하세요.

메타데이터

템플릿을 실행할 때 커스텀 매개변수를 검증할 수 있도록 추가 메타데이터로 템플릿을 확장할 수 있습니다. 템플릿의 메타데이터를 만들려면 다음 단계를 수행합니다.

메타데이터 매개변수의 매개변수를 사용하여 metadata.json 파일을 만듭니다.
예시를 보려면 메타데이터 파일 예시를 참조하세요.
메타데이터 파일을 Cloud Storage에서 템플릿과 동일한 폴더에 저장합니다.

메타데이터 매개변수

매개변수 키		필수	값 설명
`name`		예	템플릿 이름입니다.
`description`		아니요	템플릿을 설명하는 짧은 텍스트 단락입니다.
`streaming`		아니요	`true`면 이 템플릿은 스트리밍을 지원합니다. 기본값은 `false`입니다.
`supportsAtLeastOnce`		아니요	`true`면 이 템플릿은 적어도 한 번 처리를 지원합니다. 기본값은 `false`입니다. 템플릿이 적어도 한 번 스트리밍 모드로 작동하도록 설계된 경우 이 매개변수를 `true`로 설정합니다.
`supportsExactlyOnce`		아니요	`true`면 이 템플릿은 정확히 한 번 처리를 지원합니다. 기본값은 `true`입니다.
`defaultStreamingMode`		아니요	적어도 한 번 모드와 정확히 한 번 모드를 모두 지원하는 템플릿의 기본 스트리밍 모드입니다. 다음 값 중 하나를 사용합니다(`"AT_LEAST_ONCE"` 또는 `"EXACTLY_ONCE"`) 지정하지 않으면 기본 스트리밍 모드는 정확히 한 번입니다.
`parameters`		아니요	템플릿에 사용되는 추가 매개변수 배열입니다. 기본적으로 빈 배열이 사용됩니다.
	`name`	예	템플릿에 사용되는 매개변수 이름입니다.
	`label`	예	Google Cloud 콘솔에서 매개변수 라벨을 지정하기 위해 사용되는 사람이 읽을 수 있는 문자열입니다.
	`helpText`	예	매개변수를 설명하는 짧은 텍스트 단락입니다.
	`isOptional`	아니요	매개변수가 필수이면 `false`이고, 매개변수가 선택사항이면 `true`입니다. 특정 값으로 설정하지 않으면 `isOptional`이 기본적으로 `false`로 설정됩니다. 메타데이터에 이 매개변수 키를 포함하지 않으면 메타데이터가 필수 매개변수가 됩니다.
	`regexes`	아니요	매개변수 값 유효성을 검사하는 데 사용할 문자열 형식의 POSIX-egrep 정규 표현식 배열입니다. 예를 들어 `["^[a-zA-Z][a-zA-Z0-9]+"]`는 값이 문자로 시작하고 문자를 한 개 이상 포함하고 있음을 검증하는 단일 정규 표현식입니다. 기본적으로 빈 배열이 사용됩니다.

메타데이터 파일 예시

자바

{
  "name": "Streaming Beam SQL",
  "description": "An Apache Beam streaming pipeline that reads JSON encoded messages from Pub/Sub, uses Beam SQL to transform the message data, and writes the results to a BigQuery",
  "parameters": [
    {
      "name": "inputSubscription",
      "label": "Pub/Sub input subscription.",
      "helpText": "Pub/Sub subscription to read from.",
      "regexes": [
        "[a-zA-Z][-_.~+%a-zA-Z0-9]{2,}"
      ]
    },
    {
      "name": "outputTable",
      "label": "BigQuery output table",
      "helpText": "BigQuery table spec to write to, in the form 'project:dataset.table'.",
      "isOptional": true,
      "regexes": [
        "[^:]+:[^.]+[.].+"
      ]
    }
  ]
}

Python

{
  "name": "Streaming beam Python flex template",
  "description": "Streaming beam example for python flex template.",
  "parameters": [
    {
      "name": "input_subscription",
      "label": "Input PubSub subscription.",
      "helpText": "Name of the input PubSub subscription to consume from.",
      "regexes": [
        "projects/[^/]+/subscriptions/[a-zA-Z][-_.~+%a-zA-Z0-9]{2,}"
      ]
    },
    {
      "name": "output_table",
      "label": "BigQuery output table name.",
      "helpText": "Name of the BigQuery output table name.",
      "isOptional": true,
      "regexes": [
        "([^:]+:)?[^.]+[.].+"
      ]
    }
  ]
}

Dataflow 템플릿 디렉터리에서 Google 제공 템플릿의 메타데이터 파일을 다운로드할 수 있습니다.

스테이징 위치 및 임시 위치 이해

Google Cloud CLI에서는 Flex 템플릿을 실행할 때 --staging-location 및 --temp-location 옵션을 제공합니다. 마찬가지로 Dataflow REST API는 FlexTemplateRuntimeEnvironment에 대한 stagingLocation 및 tempLocation 필드를 제공합니다.

Flex 템플릿의 경우 스테이징 위치는 템플릿 실행 스테이징 단계 중에 파일이 기록되는 Cloud Storage URL입니다. Dataflow는 이러한 스테이징된 파일을 읽어 템플릿 그래프를 만듭니다. 임시 위치는 실행 단계에서 임시 파일이 기록되는 Cloud Storage URL입니다.

Flex 템플릿 작업 업데이트

다음 요청 예시는 projects.locations.flexTemplates.launch 메서드를 사용하여 템플릿 스트리밍 작업을 업데이트하는 방법을 보여줍니다. gcloud CLI를 사용하려면 기존 파이프라인 업데이트를 참조하세요.

기본 템플릿을 업데이트하려면 projects.locations.templates.launch를 대신 사용합니다.

단계에 따라 Flex 템플릿에서 스트리밍 작업을 만듭니다. 수정된 값을 사용하여 다음 HTTP POST 요청을 보냅니다.
```
POST https://dataflow.googleapis.com/v1b3/projects/PROJECT_ID/locations/REGION/flexTemplates:launch
{
    "launchParameter": {
      "update": true
      "jobName": "JOB_NAME",
      "parameters": {
        "input_subscription": "projects/PROJECT_ID/subscriptions/SUBSCRIPTION_NAME",
        "output_table": "PROJECT_ID:DATASET.TABLE_NAME"
      },
    "containerSpecGcsPath": "STORAGE_PATH"
    },
}
```
- PROJECT_ID를 프로젝트 ID로 바꿉니다.
- REGION을 업데이트하려는 작업의 Dataflow 리전으로 바꿉니다.
- JOB_NAME을 업데이트할 작업의 정확한 이름으로 바꿉니다.
- parameters를 키/값 쌍 목록으로 설정합니다. 나열된 매개변수는 이 템플릿 예시에 적용됩니다. 커스텀 템플릿을 사용하는 경우 매개변수를 필요에 따라 수정합니다. 예시 템플릿을 사용하는 경우 다음 변수를 바꿉니다.
  - SUBSCRIPTION_NAME을 Pub/Sub 구독 이름으로 바꿉니다.
  - DATASET를 BigQuery 데이터 세트 이름으로 바꿉니다.
  - TABLE_NAME을 BigQuery 테이블 이름으로 바꿉니다.
- STORAGE_PATH를 템플릿 파일의 Cloud Storage 위치로 바꿉니다. 위치는 gs://로 시작해야 합니다.
environment 매개변수를 사용하여 환경 설정을 변경합니다. 자세한 내용은 FlexTemplateRuntimeEnvironment를 참조하세요.
선택사항: curl(Linux, macOS 또는 Cloud Shell)을 사용하여 요청을 보내려면 요청을 JSON 파일에 저장한 후 다음 명령어를 실행합니다.
```
curl -X POST -d "@FILE_PATH" -H "Content-Type: application/json" -H "Authorization: Bearer $(gcloud auth print-access-token)"  https://dataflow.googleapis.com/v1b3/projects/PROJECT_ID/locations/REGION/flexTemplates:launch
```
FILE_PATH를 요청 본문이 포함된 JSON 파일의 경로로 바꿉니다.
Dataflow 모니터링 인터페이스를 사용하여 같은 이름의 새 작업이 생성되었는지 확인합니다. 이 작업의 상태가 업데이트되었습니다.

제한사항

Flex 템플릿 작업에 다음과 같은 제한사항이 적용됩니다.

Docker를 사용하여 컨테이너를 패키징하려면 Google에서 제공하는 기본 이미지를 사용해야 합니다. 적용 가능한 이미지 목록은 Flex 템플릿 기본 이미지를 참조하세요.
파이프라인을 시작하려면 run이 호출된 후 파이프라인을 구성하는 프로그램이 종료되어야 합니다.
waitUntilFinish(자바) 및 wait_until_finish(Python)은 지원되지 않습니다.

다음 단계

기본 템플릿 및 Flex 템플릿과 사용 사례 시나리오에 대한 자세한 내용은 Dataflow 템플릿을 참조하세요.
Flex 템플릿 문제 해결 정보는 Flex 템플릿 제한 시간 문제 해결을 참조하세요.
그 밖의 참조 아키텍처, 다이어그램, 튜토리얼, 권장사항을 알아보려면 클라우드 아키텍처 센터를 확인하세요.